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, see <http://www.gnu.org/licenses/>.
23***/
24
25#include <pulse/cdecl.h>
26#include <pulse/gccmacro.h>
27#include <pulse/proplist.h>
28#include <pulse/sample.h>
29#include <pulse/channelmap.h>
30
31/** \file
32 * Utility functions for handling a stream or sink format. */
33
34PA_C_DECL_BEGIN
35
36/** Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */
37typedef enum pa_encoding {
38 PA_ENCODING_ANY,
39 /**< Any encoding format, PCM or compressed */
40
41 PA_ENCODING_PCM,
42 /**< Any PCM format */
43
44 PA_ENCODING_AC3_IEC61937,
45 /**< AC3 data encapsulated in IEC 61937 header/padding */
46
47 PA_ENCODING_EAC3_IEC61937,
48 /**< EAC3 data encapsulated in IEC 61937 header/padding */
49
50 PA_ENCODING_MPEG_IEC61937,
51 /**< MPEG-1 or MPEG-2 (Part 3, not AAC) data encapsulated in IEC 61937 header/padding */
52
53 PA_ENCODING_DTS_IEC61937,
54 /**< DTS data encapsulated in IEC 61937 header/padding */
55
56 PA_ENCODING_MPEG2_AAC_IEC61937,
57 /**< MPEG-2 AAC data encapsulated in IEC 61937 header/padding. \since 4.0 */
58
59 PA_ENCODING_MAX,
60 /**< Valid encoding types must be less than this value */
61
62 PA_ENCODING_INVALID = -1,
63 /**< Represents an invalid encoding */
64} pa_encoding_t;
65
66/** \cond fulldocs */
67#define PA_ENCODING_ANY PA_ENCODING_ANY
68#define PA_ENCODING_PCM PA_ENCODING_PCM
69#define PA_ENCODING_AC3_IEC61937 PA_ENCODING_AC3_IEC61937
70#define PA_ENCODING_EAC3_IEC61937 PA_ENCODING_EAC3_IEC61937
71#define PA_ENCODING_MPEG_IEC61937 PA_ENCODING_MPEG_IEC61937
72#define PA_ENCODING_DTS_IEC61937 PA_ENCODING_DTS_IEC61937
73#define PA_ENCODING_MPEG2_AAC_IEC61937 PA_ENCODING_MPEG2_AAC_IEC61937
74#define PA_ENCODING_MAX PA_ENCODING_MAX
75#define PA_ENCODING_INVALID PA_ENCODING_INVALID
76/** \endcond */
77
78/** Returns a printable string representing the given encoding type. \since 1.0 */
79const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST;
80
81/** Converts a string of the form returned by \a pa_encoding_to_string() back to
82 * a \a pa_encoding_t. \since 1.0 */
83pa_encoding_t pa_encoding_from_string(const char *encoding);
84
85/** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */
86typedef struct pa_format_info {
87 pa_encoding_t encoding;
88 /**< The encoding used for the format */
89
90 pa_proplist *plist;
91 /**< Additional encoding-specific properties such as sample rate, bitrate, etc. */
92} pa_format_info;
93
94/** Allocates a new \a pa_format_info structure. Clients must initialise at
95 * least the encoding field themselves. Free with pa_format_info_free. \since 1.0 */
96pa_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 */
99pa_format_info* pa_format_info_copy(const pa_format_info *src);
100
101/** Frees a \a pa_format_info structure. \since 1.0 */
102void pa_format_info_free(pa_format_info *f);
103
104/** Returns non-zero when the format info structure is valid. \since 1.0 */
105int pa_format_info_valid(const pa_format_info *f);
106
107/** Returns non-zero when the format info structure represents a PCM
108 * (i.e.\ uncompressed data) format. \since 1.0 */
109int pa_format_info_is_pcm(const pa_format_info *f);
110
111/** Returns non-zero if the format represented by \a first is a subset of
112 * the format represented by \a second. This means that \a second must
113 * have all the fields that \a first does, but the reverse need not
114 * be true. This is typically expected to be used to check if a
115 * stream's format is compatible with a given sink. In such a case,
116 * \a first would be the sink's format and \a second would be the
117 * stream's. \since 1.0 */
118int pa_format_info_is_compatible(const pa_format_info *first, const pa_format_info *second);
119
120/** Maximum required string length for
121 * pa_format_info_snprint(). Please note that this value can change
122 * with any release without warning and without being considered API
123 * or ABI breakage. You should not use this definition anywhere where
124 * it might become part of an ABI. \since 1.0 */
125#define PA_FORMAT_INFO_SNPRINT_MAX 256
126
127/** Make a human-readable string representing the given format. Returns \a s. \since 1.0 */
128char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
129
130/** Parse a human-readable string of the form generated by
131 * \a pa_format_info_snprint() into a pa_format_info structure. \since 1.0 */
132pa_format_info* pa_format_info_from_string(const char *str);
133
134/** Utility function to take a \a pa_sample_spec and generate the corresponding
135 * \a pa_format_info.
136 *
137 * Note that if you want the server to choose some of the stream parameters,
138 * for example the sample rate, so that they match the device parameters, then
139 * you shouldn't use this function. In order to allow the server to choose
140 * a parameter value, that parameter must be left unspecified in the
141 * pa_format_info object, and this function always specifies all parameters. An
142 * exception is the channel map: if you pass NULL for the channel map, then the
143 * channel map will be left unspecified, allowing the server to choose it.
144 *
145 * \since 2.0 */
146pa_format_info* pa_format_info_from_sample_spec(const pa_sample_spec *ss, const pa_channel_map *map);
147
148/** Utility function to generate a \a pa_sample_spec and \a pa_channel_map corresponding to a given \a pa_format_info. The
149 * conversion for PCM formats is straight-forward. For non-PCM formats, if there is a fixed size-time conversion (i.e. all
150 * IEC61937-encapsulated formats), a "fake" sample spec whose size-time conversion corresponds to this format is provided and
151 * the channel map argument is ignored. For formats with variable size-time conversion, this function will fail. Returns a
152 * negative integer if conversion failed and 0 on success. \since 2.0 */
153int pa_format_info_to_sample_spec(const pa_format_info *f, pa_sample_spec *ss, pa_channel_map *map);
154
155/** Represents the type of value type of a property on a \ref pa_format_info. \since 2.0 */
156typedef enum pa_prop_type_t {
157 PA_PROP_TYPE_INT,
158 /**< Integer property */
159
160 PA_PROP_TYPE_INT_RANGE,
161 /**< Integer range property */
162
163 PA_PROP_TYPE_INT_ARRAY,
164 /**< Integer array property */
165
166 PA_PROP_TYPE_STRING,
167 /**< String property */
168
169 PA_PROP_TYPE_STRING_ARRAY,
170 /**< String array property */
171
172 PA_PROP_TYPE_INVALID = -1,
173 /**< Represents an invalid type */
174} pa_prop_type_t;
175
176/** \cond fulldocs */
177#define PA_PROP_TYPE_INT PA_PROP_TYPE_INT
178#define PA_PROP_TYPE_INT_RANGE PA_PROP_TYPE_INT_RANGE
179#define PA_PROP_TYPE_INT_ARRAY PA_PROP_TYPE_INT_ARRAY
180#define PA_PROP_TYPE_STRING PA_PROP_TYPE_STRING
181#define PA_PROP_TYPE_STRING_ARRAY PA_PROP_TYPE_STRING_ARRAY
182#define PA_PROP_TYPE_INVALID PA_PROP_TYPE_INVALID
183/** \endcond */
184
185/** Gets the type of property \a key in a given \ref pa_format_info. \since 2.0 */
186pa_prop_type_t pa_format_info_get_prop_type(const pa_format_info *f, const char *key);
187
188/** Gets an integer property from the given format info. Returns 0 on success and a negative integer on failure. \since 2.0 */
189int pa_format_info_get_prop_int(const pa_format_info *f, const char *key, int *v);
190/** Gets an integer range property from the given format info. Returns 0 on success and a negative integer on failure.
191 * \since 2.0 */
192int pa_format_info_get_prop_int_range(const pa_format_info *f, const char *key, int *min, int *max);
193/** Gets an integer array property from the given format info. \a values contains the values and \a n_values contains the
194 * number of elements. The caller must free \a values using \ref pa_xfree. Returns 0 on success and a negative integer on
195 * failure. \since 2.0 */
196int pa_format_info_get_prop_int_array(const pa_format_info *f, const char *key, int **values, int *n_values);
197/** Gets a string property from the given format info. The caller must free the returned string using \ref pa_xfree. Returns
198 * 0 on success and a negative integer on failure. \since 2.0 */
199int pa_format_info_get_prop_string(const pa_format_info *f, const char *key, char **v);
200/** Gets a string array property from the given format info. \a values contains the values and \a n_values contains
201 * the number of elements. The caller must free \a values using \ref pa_format_info_free_string_array. Returns 0 on success and
202 * a negative integer on failure. \since 2.0 */
203int pa_format_info_get_prop_string_array(const pa_format_info *f, const char *key, char ***values, int *n_values);
204
205/** Frees a string array returned by \ref pa_format_info_get_prop_string_array. \since 2.0 */
206void pa_format_info_free_string_array(char **values, int n_values);
207
208/** Sets an integer property on the given format info. \since 1.0 */
209void pa_format_info_set_prop_int(pa_format_info *f, const char *key, int value);
210/** Sets a property with a list of integer values on the given format info. \since 1.0 */
211void pa_format_info_set_prop_int_array(pa_format_info *f, const char *key, const int *values, int n_values);
212/** Sets a property which can have any value in a given integer range on the given format info. \since 1.0 */
213void pa_format_info_set_prop_int_range(pa_format_info *f, const char *key, int min, int max);
214/** Sets a string property on the given format info. \since 1.0 */
215void pa_format_info_set_prop_string(pa_format_info *f, const char *key, const char *value);
216/** Sets a property with a list of string values on the given format info. \since 1.0 */
217void pa_format_info_set_prop_string_array(pa_format_info *f, const char *key, const char **values, int n_values);
218
219/** Convenience method to set the sample format as a property on the given
220 * format.
221 *
222 * Note for PCM: If the sample format is left unspecified in the pa_format_info
223 * object, then the server will select the stream sample format. In that case
224 * the stream sample format will most likely match the device sample format,
225 * meaning that sample format conversion will be avoided.
226 *
227 * \since 1.0 */
228void pa_format_info_set_sample_format(pa_format_info *f, pa_sample_format_t sf);
229
230/** Convenience method to set the sampling rate as a property on the given
231 * format.
232 *
233 * Note for PCM: If the sample rate is left unspecified in the pa_format_info
234 * object, then the server will select the stream sample rate. In that case the
235 * stream sample rate will most likely match the device sample rate, meaning
236 * that sample rate conversion will be avoided.
237 *
238 * \since 1.0 */
239void pa_format_info_set_rate(pa_format_info *f, int rate);
240
241/** Convenience method to set the number of channels as a property on the given
242 * format.
243 *
244 * Note for PCM: If the channel count is left unspecified in the pa_format_info
245 * object, then the server will select the stream channel count. In that case
246 * the stream channel count will most likely match the device channel count,
247 * meaning that up/downmixing will be avoided.
248 *
249 * \since 1.0 */
250void pa_format_info_set_channels(pa_format_info *f, int channels);
251
252/** Convenience method to set the channel map as a property on the given
253 * format.
254 *
255 * Note for PCM: If the channel map is left unspecified in the pa_format_info
256 * object, then the server will select the stream channel map. In that case the
257 * stream channel map will most likely match the device channel map, meaning
258 * that remixing will be avoided.
259 *
260 * \since 1.0 */
261void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map);
262
263PA_C_DECL_END
264
265#endif
266