X-Git-Url: https://code.delx.au/pulseaudio/blobdiff_plain/8bffbcde1b9ac41703be9c242f4f9f172d5649bb..e11b699d45fa3dca2cde8a976cbf25490f5501a4:/src/pulse/format.h diff --git a/src/pulse/format.h b/src/pulse/format.h index b8b829ef..4184bee5 100644 --- a/src/pulse/format.h +++ b/src/pulse/format.h @@ -30,9 +30,12 @@ #include #include +/** \file + * Utility functions for handling a stream or sink format. */ + PA_C_DECL_BEGIN -/**< Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */ +/** Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */ typedef enum pa_encoding { PA_ENCODING_ANY, /**< Any encoding format, PCM or compressed */ @@ -52,6 +55,9 @@ typedef enum pa_encoding { PA_ENCODING_DTS_IEC61937, /**< DTS data encapsulated in IEC 61937 header/padding */ + PA_ENCODING_MPEG2_AAC_IEC61937, + /**< MPEG-2 AAC data encapsulated in IEC 61937 header/padding. \since 4.0 */ + PA_ENCODING_MAX, /**< Valid encoding types must be less than this value */ @@ -59,13 +65,25 @@ typedef enum pa_encoding { /**< Represents an invalid encoding */ } pa_encoding_t; +/** \cond fulldocs */ +#define PA_ENCODING_ANY PA_ENCODING_ANY +#define PA_ENCODING_PCM PA_ENCODING_PCM +#define PA_ENCODING_AC3_IEC61937 PA_ENCODING_AC3_IEC61937 +#define PA_ENCODING_EAC3_IEC61937 PA_ENCODING_EAC3_IEC61937 +#define PA_ENCODING_MPEG_IEC61937 PA_ENCODING_MPEG_IEC61937 +#define PA_ENCODING_DTS_IEC61937 PA_ENCODING_DTS_IEC61937 +#define PA_ENCODING_MPEG2_AAC_IEC61937 PA_ENCODING_MPEG2_AAC_IEC61937 +#define PA_ENCODING_MAX PA_ENCODING_MAX +#define PA_ENCODING_INVALID PA_ENCODING_INVALID +/** \endcond */ + /** Returns a printable string representing the given encoding type. \since 1.0 */ const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST; /** Converts a string of the form returned by \a pa_encoding_to_string() back to a \a pa_encoding_t. \since 1.0 */ pa_encoding_t pa_encoding_from_string(const char *encoding); -/**< Represents the format of data provided in a stream or processed by a sink. \since 1.0 */ +/** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */ typedef struct pa_format_info { pa_encoding_t encoding; /**< The encoding used for the format */ @@ -74,28 +92,28 @@ typedef struct pa_format_info { /**< Additional encoding-specific properties such as sample rate, bitrate, etc. */ } pa_format_info; -/**< Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. */ +/** Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. \since 1.0 */ pa_format_info* pa_format_info_new(void); -/**< Returns a new \a pa_format_info struct and representing the same format as \a src */ +/** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */ pa_format_info* pa_format_info_copy(const pa_format_info *src); -/**< Frees a \a pa_format_info structure */ +/** Frees a \a pa_format_info structure. \since 1.0 */ void pa_format_info_free(pa_format_info *f); -/** Returns non-zero when the format info structure is valid */ +/** Returns non-zero when the format info structure is valid. \since 1.0 */ int pa_format_info_valid(const pa_format_info *f); -/** Returns non-zero when the format info structure represents a PCM (i.e. uncompressed data) format */ +/** Returns non-zero when the format info structure represents a PCM (i.e.\ uncompressed data) format. \since 1.0 */ int pa_format_info_is_pcm(const pa_format_info *f); -/** Returns non-zero if the format represented \a first is a subset of - * the format represented by \second. This means that \a second must +/** Returns non-zero if the format represented by \a first is a subset of + * the format represented by \a second. This means that \a second must * have all the fields that \a first does, but the reverse need not * be true. This is typically expected to be used to check if a * stream's format is compatible with a given sink. In such a case, * \a first would be the sink's format and \a second would be the - * stream's.*/ + * stream's. \since 1.0 */ int pa_format_info_is_compatible(pa_format_info *first, pa_format_info *second); /** Maximum required string length for @@ -112,24 +130,87 @@ char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f); * \a pa_format_info_snprint() into a pa_format_info structure. \since 1.0 */ pa_format_info* pa_format_info_from_string(const char *str); -/** Sets an integer property on the given format info */ +/** Utility function to take a \a pa_sample_spec and generate the corresponding \a pa_format_info. \since 2.0 */ +pa_format_info* pa_format_info_from_sample_spec(pa_sample_spec *ss, pa_channel_map *map); + +/** Utility function to generate a \a pa_sample_spec and \a pa_channel_map corresponding to a given \a pa_format_info. The + * conversion for PCM formats is straight-forward. For non-PCM formats, if there is a fixed size-time conversion (i.e. all + * IEC61937-encapsulated formats), a "fake" sample spec whose size-time conversion corresponds to this format is provided and + * the channel map argument is ignored. For formats with variable size-time conversion, this function will fail. Returns a + * negative integer if conversion failed and 0 on success. \since 2.0 */ +int pa_format_info_to_sample_spec(pa_format_info *f, pa_sample_spec *ss, pa_channel_map *map); + +/** Represents the type of value type of a property on a \ref pa_format_info. \since 2.0 */ +typedef enum pa_prop_type_t { + PA_PROP_TYPE_INT, + /**< Integer property */ + + PA_PROP_TYPE_INT_RANGE, + /**< Integer range property */ + + PA_PROP_TYPE_INT_ARRAY, + /**< Integer array property */ + + PA_PROP_TYPE_STRING, + /**< String property */ + + PA_PROP_TYPE_STRING_ARRAY, + /**< String array property */ + + PA_PROP_TYPE_INVALID = -1, + /**< Represents an invalid type */ +} pa_prop_type_t; + +/** \cond fulldocs */ +#define PA_PROP_TYPE_INT PA_PROP_TYPE_INT +#define PA_PROP_TYPE_INT_RANGE PA_PROP_TYPE_INT_RANGE +#define PA_PROP_TYPE_INT_ARRAY PA_PROP_TYPE_INT_ARRAY +#define PA_PROP_TYPE_STRING PA_PROP_TYPE_STRING +#define PA_PROP_TYPE_STRING_ARRAY PA_PROP_TYPE_STRING_ARRAY +#define PA_PROP_TYPE_INVALID PA_PROP_TYPE_INVALID +/** \endcond */ + +/** Gets the type of property \a key in a given \ref pa_format_info. \since 2.0 */ +pa_prop_type_t pa_format_info_get_prop_type(pa_format_info *f, const char *key); + +/** Gets an integer property from the given format info. Returns 0 on success and a negative integer on failure. \since 2.0 */ +int pa_format_info_get_prop_int(pa_format_info *f, const char *key, int *v); +/** Gets an integer range property from the given format info. Returns 0 on success and a negative integer on failure. + * \since 2.0 */ +int pa_format_info_get_prop_int_range(pa_format_info *f, const char *key, int *min, int *max); +/** Gets an integer array property from the given format info. \a values contains the values and \a n_values contains the + * number of elements. The caller must free \a values using \ref pa_xfree. Returns 0 on success and a negative integer on + * failure. \since 2.0 */ +int pa_format_info_get_prop_int_array(pa_format_info *f, const char *key, int **values, int *n_values); +/** Gets a string property from the given format info. The caller must free the returned string using \ref pa_xfree. Returns + * 0 on success and a negative integer on failure. \since 2.0 */ +int pa_format_info_get_prop_string(pa_format_info *f, const char *key, char **v); +/** Gets a string array property from the given format info. \a values contains the values and \a n_values contains + * the number of elements. The caller must free \a values using \ref pa_format_info_free_string_array. Returns 0 on success and + * a negative integer on failure. \since 2.0 */ +int pa_format_info_get_prop_string_array(pa_format_info *f, const char *key, char ***values, int *n_values); + +/** Frees a string array returned by \ref pa_format_info_get_prop_string_array. \since 2.0 */ +void pa_format_info_free_string_array(char **values, int n_values); + +/** Sets an integer property on the given format info. \since 1.0 */ void pa_format_info_set_prop_int(pa_format_info *f, const char *key, int value); -/** Sets a property with a list of integer values on the given format info */ +/** Sets a property with a list of integer values on the given format info. \since 1.0 */ void pa_format_info_set_prop_int_array(pa_format_info *f, const char *key, const int *values, int n_values); -/** Sets a property which can have any value in a given integer range on the given format info */ +/** Sets a property which can have any value in a given integer range on the given format info. \since 1.0 */ void pa_format_info_set_prop_int_range(pa_format_info *f, const char *key, int min, int max); -/** Sets a string property on the given format info */ +/** Sets a string property on the given format info. \since 1.0 */ void pa_format_info_set_prop_string(pa_format_info *f, const char *key, const char *value); -/** Sets a property with a list of string values on the given format info */ +/** Sets a property with a list of string values on the given format info. \since 1.0 */ void pa_format_info_set_prop_string_array(pa_format_info *f, const char *key, const char **values, int n_values); -/** Convenience method to set the sample format as a property on the given format */ +/** Convenience method to set the sample format as a property on the given format. \since 1.0 */ void pa_format_info_set_sample_format(pa_format_info *f, pa_sample_format_t sf); -/** Convenience method to set the sampling rate as a property on the given format */ +/** Convenience method to set the sampling rate as a property on the given format. \since 1.0 */ void pa_format_info_set_rate(pa_format_info *f, int rate); -/** Convenience method to set the number of channels as a property on the given format */ +/** Convenience method to set the number of channels as a property on the given format. \since 1.0 */ void pa_format_info_set_channels(pa_format_info *f, int channels); -/** Convenience method to set the channel map as a property on the given format */ +/** Convenience method to set the channel map as a property on the given format. \since 1.0 */ void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map); PA_C_DECL_END