code.delx.au - pulseaudio/blob - src/pulse/format.h

   1 #ifndef fooformathfoo
   2 #define fooformathfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2011 Intel Corporation
   8   Copyright 2011 Collabora Multimedia
   9   Copyright 2011 Arun Raghavan <arun.raghavan@collabora.co.uk>
  10
  11   PulseAudio is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU Lesser General Public License as published
  13   by the Free Software Foundation; either version 2.1 of the License,
  14   or (at your option) any later version.
  15
  16   PulseAudio is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with PulseAudio; if not, write to the Free Software
  23   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  24   USA.
  25 ***/
  26
  27 #include <pulse/cdecl.h>
  28 #include <pulse/gccmacro.h>
  29 #include <pulse/proplist.h>
  30 #include <pulse/sample.h>
  31 #include <pulse/channelmap.h>
  32
  33 /** \file
  34  * Utility functions for handling a stream or sink format. */
  35
  36 PA_C_DECL_BEGIN
  37
  38 /** Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */
  39 typedef enum pa_encoding {
  40     PA_ENCODING_ANY,
  41     /**< Any encoding format, PCM or compressed */
  42
  43     PA_ENCODING_PCM,
  44     /**< Any PCM format */
  45
  46     PA_ENCODING_AC3_IEC61937,
  47     /**< AC3 data encapsulated in IEC 61937 header/padding */
  48
  49     PA_ENCODING_EAC3_IEC61937,
  50     /**< EAC3 data encapsulated in IEC 61937 header/padding */
  51
  52     PA_ENCODING_MPEG_IEC61937,
  53     /**< MPEG-1 or MPEG-2 (Part 3, not AAC) data encapsulated in IEC 61937 header/padding */
  54
  55     PA_ENCODING_DTS_IEC61937,
  56     /**< DTS data encapsulated in IEC 61937 header/padding */
  57
  58     PA_ENCODING_MPEG2_AAC_IEC61937,
  59     /**< MPEG-2 AAC data encapsulated in IEC 61937 header/padding. \since 4.0 */
  60
  61     PA_ENCODING_MAX,
  62     /**< Valid encoding types must be less than this value */
  63
  64     PA_ENCODING_INVALID = -1,
  65     /**< Represents an invalid encoding */
  66 } pa_encoding_t;
  67
  68 /** \cond fulldocs */
  69 #define PA_ENCODING_ANY PA_ENCODING_ANY
  70 #define PA_ENCODING_PCM PA_ENCODING_PCM
  71 #define PA_ENCODING_AC3_IEC61937 PA_ENCODING_AC3_IEC61937
  72 #define PA_ENCODING_EAC3_IEC61937 PA_ENCODING_EAC3_IEC61937
  73 #define PA_ENCODING_MPEG_IEC61937 PA_ENCODING_MPEG_IEC61937
  74 #define PA_ENCODING_DTS_IEC61937 PA_ENCODING_DTS_IEC61937
  75 #define PA_ENCODING_MPEG2_AAC_IEC61937 PA_ENCODING_MPEG2_AAC_IEC61937
  76 #define PA_ENCODING_MAX PA_ENCODING_MAX
  77 #define PA_ENCODING_INVALID PA_ENCODING_INVALID
  78 /** \endcond */
  79
  80 /** Returns a printable string representing the given encoding type. \since 1.0 */
  81 const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST;
  82
  83 /** Converts a string of the form returned by \a pa_encoding_to_string() back to a \a pa_encoding_t. \since 1.0 */
  84 pa_encoding_t pa_encoding_from_string(const char *encoding);
  85
  86 /** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */
  87 typedef struct pa_format_info {
  88     pa_encoding_t encoding;
  89     /**< The encoding used for the format */
  90
  91     pa_proplist *plist;
  92     /**< Additional encoding-specific properties such as sample rate, bitrate, etc. */
  93 } pa_format_info;
  94
  95 /** Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. \since 1.0 */
  96 pa_format_info* pa_format_info_new(void);
  97
  98 /** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */
  99 pa_format_info* pa_format_info_copy(const pa_format_info *src);
 100
 101 /** Frees a \a pa_format_info structure. \since 1.0 */
 102 void pa_format_info_free(pa_format_info *f);
 103
 104 /** Returns non-zero when the format info structure is valid. \since 1.0 */
 105 int pa_format_info_valid(const pa_format_info *f);
 106
 107 /** Returns non-zero when the format info structure represents a PCM (i.e.\ uncompressed data) format. \since 1.0 */
 108 int pa_format_info_is_pcm(const pa_format_info *f);
 109
 110 /** Returns non-zero if the format represented by \a first is a subset of
 111  * the format represented by \a second. This means that \a second must
 112  * have all the fields that \a first does, but the reverse need not
 113  * be true. This is typically expected to be used to check if a
 114  * stream's format is compatible with a given sink. In such a case,
 115  * \a first would be the sink's format and \a second would be the
 116  * stream's. \since 1.0 */
 117 int pa_format_info_is_compatible(const pa_format_info *first, const pa_format_info *second);
 118
 119 /** Maximum required string length for
 120  * pa_format_info_snprint(). Please note that this value can change
 121  * with any release without warning and without being considered API
 122  * or ABI breakage. You should not use this definition anywhere where
 123  * it might become part of an ABI. \since 1.0 */
 124 #define PA_FORMAT_INFO_SNPRINT_MAX 256
 125
 126 /** Return a human-readable string representing the given format. \since 1.0 */
 127 char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
 128
 129 /** Parse a human-readable string of the form generated by
 130  * \a pa_format_info_snprint() into a pa_format_info structure. \since 1.0 */
 131 pa_format_info* pa_format_info_from_string(const char *str);
 132
 133 /** Utility function to take a \a pa_sample_spec and generate the corresponding \a pa_format_info. \since 2.0 */
 134 pa_format_info* pa_format_info_from_sample_spec(const pa_sample_spec *ss, const pa_channel_map *map);
 135
 136 /** Utility function to generate a \a pa_sample_spec and \a pa_channel_map corresponding to a given \a pa_format_info. The
 137  * conversion for PCM formats is straight-forward. For non-PCM formats, if there is a fixed size-time conversion (i.e. all
 138  * IEC61937-encapsulated formats), a "fake" sample spec whose size-time conversion corresponds to this format is provided and
 139  * the channel map argument is ignored. For formats with variable size-time conversion, this function will fail. Returns a
 140  * negative integer if conversion failed and 0 on success. \since 2.0 */
 141 int pa_format_info_to_sample_spec(const pa_format_info *f, pa_sample_spec *ss, pa_channel_map *map);
 142
 143 /** Represents the type of value type of a property on a \ref pa_format_info. \since 2.0 */
 144 typedef enum pa_prop_type_t {
 145     PA_PROP_TYPE_INT,
 146     /**< Integer property */
 147
 148     PA_PROP_TYPE_INT_RANGE,
 149     /**< Integer range property */
 150
 151     PA_PROP_TYPE_INT_ARRAY,
 152     /**< Integer array property */
 153
 154     PA_PROP_TYPE_STRING,
 155     /**< String property */
 156
 157     PA_PROP_TYPE_STRING_ARRAY,
 158     /**< String array property */
 159
 160     PA_PROP_TYPE_INVALID = -1,
 161     /**< Represents an invalid type */
 162 } pa_prop_type_t;
 163
 164 /** \cond fulldocs */
 165 #define PA_PROP_TYPE_INT PA_PROP_TYPE_INT
 166 #define PA_PROP_TYPE_INT_RANGE PA_PROP_TYPE_INT_RANGE
 167 #define PA_PROP_TYPE_INT_ARRAY PA_PROP_TYPE_INT_ARRAY
 168 #define PA_PROP_TYPE_STRING PA_PROP_TYPE_STRING
 169 #define PA_PROP_TYPE_STRING_ARRAY PA_PROP_TYPE_STRING_ARRAY
 170 #define PA_PROP_TYPE_INVALID PA_PROP_TYPE_INVALID
 171 /** \endcond */
 172
 173 /** Gets the type of property \a key in a given \ref pa_format_info. \since 2.0 */
 174 pa_prop_type_t pa_format_info_get_prop_type(const pa_format_info *f, const char *key);
 175
 176 /** Gets an integer property from the given format info. Returns 0 on success and a negative integer on failure. \since 2.0 */
 177 int pa_format_info_get_prop_int(const pa_format_info *f, const char *key, int *v);
 178 /** Gets an integer range property from the given format info. Returns 0 on success and a negative integer on failure.
 179  * \since 2.0 */
 180 int pa_format_info_get_prop_int_range(const pa_format_info *f, const char *key, int *min, int *max);
 181 /** Gets an integer array property from the given format info. \a values contains the values and \a n_values contains the
 182  * number of elements. The caller must free \a values using \ref pa_xfree. Returns 0 on success and a negative integer on
 183  * failure. \since 2.0 */
 184 int pa_format_info_get_prop_int_array(const pa_format_info *f, const char *key, int **values, int *n_values);
 185 /** Gets a string property from the given format info.  The caller must free the returned string using \ref pa_xfree. Returns
 186  * 0 on success and a negative integer on failure. \since 2.0 */
 187 int pa_format_info_get_prop_string(const pa_format_info *f, const char *key, char **v);
 188 /** Gets a string array property from the given format info. \a values contains the values and \a n_values contains
 189  * the number of elements. The caller must free \a values using \ref pa_format_info_free_string_array. Returns 0 on success and
 190  * a negative integer on failure. \since 2.0 */
 191 int pa_format_info_get_prop_string_array(const pa_format_info *f, const char *key, char ***values, int *n_values);
 192
 193 /** Frees a string array returned by \ref pa_format_info_get_prop_string_array. \since 2.0 */
 194 void pa_format_info_free_string_array(char **values, int n_values);
 195
 196 /** Sets an integer property on the given format info. \since 1.0 */
 197 void pa_format_info_set_prop_int(pa_format_info *f, const char *key, int value);
 198 /** Sets a property with a list of integer values on the given format info. \since 1.0 */
 199 void pa_format_info_set_prop_int_array(pa_format_info *f, const char *key, const int *values, int n_values);
 200 /** Sets a property which can have any value in a given integer range on the given format info. \since 1.0 */
 201 void pa_format_info_set_prop_int_range(pa_format_info *f, const char *key, int min, int max);
 202 /** Sets a string property on the given format info. \since 1.0 */
 203 void pa_format_info_set_prop_string(pa_format_info *f, const char *key, const char *value);
 204 /** Sets a property with a list of string values on the given format info. \since 1.0 */
 205 void pa_format_info_set_prop_string_array(pa_format_info *f, const char *key, const char **values, int n_values);
 206
 207 /** Convenience method to set the sample format as a property on the given format. \since 1.0 */
 208 void pa_format_info_set_sample_format(pa_format_info *f, pa_sample_format_t sf);
 209 /** Convenience method to set the sampling rate as a property on the given format. \since 1.0 */
 210 void pa_format_info_set_rate(pa_format_info *f, int rate);
 211 /** Convenience method to set the number of channels as a property on the given format. \since 1.0 */
 212 void pa_format_info_set_channels(pa_format_info *f, int channels);
 213 /** Convenience method to set the channel map as a property on the given format. \since 1.0 */
 214 void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map);
 215
 216 PA_C_DECL_END
 217
 218 #endif