1#ifndef foosamplehfoo
2#define foosamplehfoo
3
4/***
5 This file is part of PulseAudio.
6
7 Copyright 2004-2006 Lennart Poettering
8 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
9
10 PulseAudio is free software; you can redistribute it and/or modify
11 it under the terms of the GNU Lesser General Public License as published
12 by the Free Software Foundation; either version 2.1 of the License,
13 or (at your option) any later version.
14
15 PulseAudio is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
22***/
23
24#include <inttypes.h>
25#include <sys/types.h>
26#include <sys/param.h>
27
28#include <pulse/gccmacro.h>
29#include <pulse/cdecl.h>
30#include <pulse/version.h>
31
32/** \page sample Sample Format Specifications
33 *
34 * \section overv_sec Overview
35 *
36 * PulseAudio is capable of handling a multitude of sample formats, rates
37 * and channels, transparently converting and mixing them as needed.
38 *
39 * \section format_sec Sample Format
40 *
41 * PulseAudio supports the following sample formats:
42 *
43 * \li PA_SAMPLE_U8 - Unsigned 8 bit integer PCM.
44 * \li PA_SAMPLE_S16LE - Signed 16 integer bit PCM, little endian.
45 * \li PA_SAMPLE_S16BE - Signed 16 integer bit PCM, big endian.
46 * \li PA_SAMPLE_FLOAT32LE - 32 bit IEEE floating point PCM, little endian.
47 * \li PA_SAMPLE_FLOAT32BE - 32 bit IEEE floating point PCM, big endian.
48 * \li PA_SAMPLE_ALAW - 8 bit a-Law.
49 * \li PA_SAMPLE_ULAW - 8 bit mu-Law.
50 * \li PA_SAMPLE_S32LE - Signed 32 bit integer PCM, little endian.
51 * \li PA_SAMPLE_S32BE - Signed 32 bit integer PCM, big endian.
52 * \li PA_SAMPLE_S24LE - Signed 24 bit integer PCM packed, little endian.
53 * \li PA_SAMPLE_S24BE - Signed 24 bit integer PCM packed, big endian.
54 * \li PA_SAMPLE_S24_32LE - Signed 24 bit integer PCM in LSB of 32 bit words, little endian.
55 * \li PA_SAMPLE_S24_32BE - Signed 24 bit integer PCM in LSB of 32 bit words, big endian.
56 *
57 * The floating point sample formats have the range from -1.0 to 1.0.
58 *
59 * The sample formats that are sensitive to endianness have convenience
60 * macros for native endian (NE), and reverse endian (RE).
61 *
62 * \section rate_sec Sample Rates
63 *
64 * PulseAudio supports any sample rate between 1 Hz and 192000 Hz. There is no
65 * point trying to exceed the sample rate of the output device though as the
66 * signal will only get downsampled, consuming CPU on the machine running the
67 * server.
68 *
69 * \section chan_sec Channels
70 *
71 * PulseAudio supports up to 32 individual channels. The order of the
72 * channels is up to the application, but they must be continuous. To map
73 * channels to speakers, see \ref channelmap.
74 *
75 * \section calc_sec Calculations
76 *
77 * The PulseAudio library contains a number of convenience functions to do
78 * calculations on sample formats:
79 *
80 * \li pa_bytes_per_second() - The number of bytes one second of audio will
81 * take given a sample format.
82 * \li pa_frame_size() - The size, in bytes, of one frame (i.e. one set of
83 * samples, one for each channel).
84 * \li pa_sample_size() - The size, in bytes, of one sample.
85 * \li pa_bytes_to_usec() - Calculate the time it would take to play a buffer
86 * of a certain size.
87 *
88 * \section util_sec Convenience Functions
89 *
90 * The library also contains a couple of other convenience functions:
91 *
92 * \li pa_sample_spec_valid() - Tests if a sample format specification is
93 * valid.
94 * \li pa_sample_spec_equal() - Tests if the sample format specifications are
95 * identical.
96 * \li pa_sample_format_to_string() - Return a textual description of a
97 * sample format.
98 * \li pa_parse_sample_format() - Parse a text string into a sample format.
99 * \li pa_sample_spec_snprint() - Create a textual description of a complete
100 * sample format specification.
101 * \li pa_bytes_snprint() - Pretty print a byte value (e.g. 2.5 MiB).
102 */
103
104/** \file
105 * Constants and routines for sample type handling
106 *
107 * See also \subpage sample
108 */
109
110PA_C_DECL_BEGIN
111
112#if !defined(WORDS_BIGENDIAN)
113
114#if defined(__BYTE_ORDER)
115#if __BYTE_ORDER == __BIG_ENDIAN
116#define WORDS_BIGENDIAN
117#endif
118#endif
119
120/* On Sparc, WORDS_BIGENDIAN needs to be set if _BIG_ENDIAN is defined. */
121#if defined(__sparc__) && defined(_BIG_ENDIAN)
122#define WORDS_BIGENDIAN
123#endif
124
125#endif
126
127/** Maximum number of allowed channels */
128#define PA_CHANNELS_MAX 32U
129
130/** Maximum allowed sample rate */
131#define PA_RATE_MAX (48000U*8U)
132
133/** Sample format */
134typedef enum pa_sample_format {
135 PA_SAMPLE_U8,
136 /**< Unsigned 8 Bit PCM */
137
138 PA_SAMPLE_ALAW,
139 /**< 8 Bit a-Law */
140
141 PA_SAMPLE_ULAW,
142 /**< 8 Bit mu-Law */
143
144 PA_SAMPLE_S16LE,
145 /**< Signed 16 Bit PCM, little endian (PC) */
146
147 PA_SAMPLE_S16BE,
148 /**< Signed 16 Bit PCM, big endian */
149
150 PA_SAMPLE_FLOAT32LE,
151 /**< 32 Bit IEEE floating point, little endian (PC), range -1.0 to 1.0 */
152
153 PA_SAMPLE_FLOAT32BE,
154 /**< 32 Bit IEEE floating point, big endian, range -1.0 to 1.0 */
155
156 PA_SAMPLE_S32LE,
157 /**< Signed 32 Bit PCM, little endian (PC) */
158
159 PA_SAMPLE_S32BE,
160 /**< Signed 32 Bit PCM, big endian */
161
162 PA_SAMPLE_S24LE,
163 /**< Signed 24 Bit PCM packed, little endian (PC). \since 0.9.15 */
164
165 PA_SAMPLE_S24BE,
166 /**< Signed 24 Bit PCM packed, big endian. \since 0.9.15 */
167
168 PA_SAMPLE_S24_32LE,
169 /**< Signed 24 Bit PCM in LSB of 32 Bit words, little endian (PC). \since 0.9.15 */
170
171 PA_SAMPLE_S24_32BE,
172 /**< Signed 24 Bit PCM in LSB of 32 Bit words, big endian. \since 0.9.15 */
173
174 /* Remeber to update
175 * https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
176 * when adding new formats! */
177
178 PA_SAMPLE_MAX,
179 /**< Upper limit of valid sample types */
180
181 PA_SAMPLE_INVALID = -1
182 /**< An invalid value */
183} pa_sample_format_t;
184
185#ifdef WORDS_BIGENDIAN
186/** Signed 16 Bit PCM, native endian */
187#define PA_SAMPLE_S16NE PA_SAMPLE_S16BE
188/** 32 Bit IEEE floating point, native endian */
189#define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32BE
190/** Signed 32 Bit PCM, native endian */
191#define PA_SAMPLE_S32NE PA_SAMPLE_S32BE
192/** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
193#define PA_SAMPLE_S24NE PA_SAMPLE_S24BE
194/** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
195#define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32BE
196
197/** Signed 16 Bit PCM reverse endian */
198#define PA_SAMPLE_S16RE PA_SAMPLE_S16LE
199/** 32 Bit IEEE floating point, reverse endian */
200#define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32LE
201/** Signed 32 Bit PCM, reverse endian */
202#define PA_SAMPLE_S32RE PA_SAMPLE_S32LE
203/** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
204#define PA_SAMPLE_S24RE PA_SAMPLE_S24LE
205/** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
206#define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32LE
207#else
208/** Signed 16 Bit PCM, native endian */
209#define PA_SAMPLE_S16NE PA_SAMPLE_S16LE
210/** 32 Bit IEEE floating point, native endian */
211#define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32LE
212/** Signed 32 Bit PCM, native endian */
213#define PA_SAMPLE_S32NE PA_SAMPLE_S32LE
214/** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
215#define PA_SAMPLE_S24NE PA_SAMPLE_S24LE
216/** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
217#define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32LE
218
219/** Signed 16 Bit PCM, reverse endian */
220#define PA_SAMPLE_S16RE PA_SAMPLE_S16BE
221/** 32 Bit IEEE floating point, reverse endian */
222#define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32BE
223/** Signed 32 Bit PCM, reverse endian */
224#define PA_SAMPLE_S32RE PA_SAMPLE_S32BE
225/** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
226#define PA_SAMPLE_S24RE PA_SAMPLE_S24BE
227/** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
228#define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32BE
229#endif
230
231/** A Shortcut for PA_SAMPLE_FLOAT32NE */
232#define PA_SAMPLE_FLOAT32 PA_SAMPLE_FLOAT32NE
233
234/** \cond fulldocs */
235/* Allow clients to check with #ifdef for these sample formats */
236#define PA_SAMPLE_U8 PA_SAMPLE_U8
237#define PA_SAMPLE_ALAW PA_SAMPLE_ALAW
238#define PA_SAMPLE_ULAW PA_SAMPLE_ULAW
239#define PA_SAMPLE_S16LE PA_SAMPLE_S16LE
240#define PA_SAMPLE_S16BE PA_SAMPLE_S16BE
241#define PA_SAMPLE_FLOAT32LE PA_SAMPLE_FLOAT32LE
242#define PA_SAMPLE_FLOAT32BE PA_SAMPLE_FLOAT32BE
243#define PA_SAMPLE_S32LE PA_SAMPLE_S32LE
244#define PA_SAMPLE_S32BE PA_SAMPLE_S32BE
245#define PA_SAMPLE_S24LE PA_SAMPLE_S24LE
246#define PA_SAMPLE_S24BE PA_SAMPLE_S24BE
247#define PA_SAMPLE_S24_32LE PA_SAMPLE_S24_32LE
248#define PA_SAMPLE_S24_32BE PA_SAMPLE_S24_32BE
249/** \endcond */
250
251/** A sample format and attribute specification */
252typedef struct pa_sample_spec {
253 pa_sample_format_t format;
254 /**< The sample format */
255
256 uint32_t rate;
257 /**< The sample rate. (e.g. 44100) */
258
259 uint8_t channels;
260 /**< Audio channels. (1 for mono, 2 for stereo, ...) */
261} pa_sample_spec;
262
263/** Type for usec specifications (unsigned). Always 64 bit. */
264typedef uint64_t pa_usec_t;
265
266/** Return the amount of bytes that constitute playback of one second of
267 * audio, with the specified sample spec. */
268size_t pa_bytes_per_second(const pa_sample_spec *spec) PA_GCC_PURE;
269
270/** Return the size of a frame with the specific sample type */
271size_t pa_frame_size(const pa_sample_spec *spec) PA_GCC_PURE;
272
273/** Return the size of a sample with the specific sample type */
274size_t pa_sample_size(const pa_sample_spec *spec) PA_GCC_PURE;
275
276/** Similar to pa_sample_size() but take a sample format instead of a
277 * full sample spec. \since 0.9.15 */
278size_t pa_sample_size_of_format(pa_sample_format_t f) PA_GCC_PURE;
279
280/** Calculate the time it would take to play a buffer of the specified
281 * size with the specified sample type. The return value will always
282 * be rounded down for non-integral return values. */
283pa_usec_t pa_bytes_to_usec(uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE;
284
285/** Calculates the size of a buffer required, for playback duration
286 * of the time specified, with the specified sample type. The
287 * return value will always be rounded down for non-integral
288 * return values. \since 0.9 */
289size_t pa_usec_to_bytes(pa_usec_t t, const pa_sample_spec *spec) PA_GCC_PURE;
290
291/** Initialize the specified sample spec and return a pointer to
292 * it. The sample spec will have a defined state but
293 * pa_sample_spec_valid() will fail for it. \since 0.9.13 */
294pa_sample_spec* pa_sample_spec_init(pa_sample_spec *spec);
295
296/** Return non-zero if the given integer is a valid sample format. \since 5.0 */
297int pa_sample_format_valid(unsigned format) PA_GCC_PURE;
298
299/** Return non-zero if the rate is within the supported range. \since 5.0 */
300int pa_sample_rate_valid(uint32_t rate) PA_GCC_PURE;
301
302/** Return non-zero if the channel count is within the supported range.
303 * \since 5.0 */
304int pa_channels_valid(uint8_t channels) PA_GCC_PURE;
305
306/** Return non-zero when the sample type specification is valid */
307int pa_sample_spec_valid(const pa_sample_spec *spec) PA_GCC_PURE;
308
309/** Return non-zero when the two sample type specifications match */
310int pa_sample_spec_equal(const pa_sample_spec*a, const pa_sample_spec*b) PA_GCC_PURE;
311
312/** Return a descriptive string for the specified sample format. \since 0.8 */
313const char *pa_sample_format_to_string(pa_sample_format_t f) PA_GCC_PURE;
314
315/** Parse a sample format text. Inverse of pa_sample_format_to_string() */
316pa_sample_format_t pa_parse_sample_format(const char *format) PA_GCC_PURE;
317
318/** Maximum required string length for
319 * pa_sample_spec_snprint(). Please note that this value can change
320 * with any release without warning and without being considered API
321 * or ABI breakage. You should not use this definition anywhere where
322 * it might become part of an ABI. */
323#define PA_SAMPLE_SPEC_SNPRINT_MAX 32
324
325/** Pretty print a sample type specification to a string. Returns \a s. */
326char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
327
328/** Maximum required string length for pa_bytes_snprint(). Please note
329 * that this value can change with any release without warning and
330 * without being considered API or ABI breakage. You should not use
331 * this definition anywhere where it might become part of an
332 * ABI. \since 0.9.16 */
333#define PA_BYTES_SNPRINT_MAX 11
334
335/** Pretty print a byte size value (i.e.\ "2.5 MiB"). Returns \a s. */
336char* pa_bytes_snprint(char *s, size_t l, unsigned v);
337
338/** Returns 1 when the specified format is little endian, 0 when
339 * big endian. Returns -1 when endianness does not apply to the
340 * specified format, or endianess is unknown. \since 0.9.16 */
341int pa_sample_format_is_le(pa_sample_format_t f) PA_GCC_PURE;
342
343/** Returns 1 when the specified format is big endian, 0 when
344 * little endian. Returns -1 when endianness does not apply to the
345 * specified format, or endianess is unknown. \since 0.9.16 */
346int pa_sample_format_is_be(pa_sample_format_t f) PA_GCC_PURE;
347
348#ifdef WORDS_BIGENDIAN
349#define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
350#define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
351#else
352/** Returns 1 when the specified format is native endian, 0 when
353 * not. Returns -1 when endianness does not apply to the
354 * specified format, or endianess is unknown. \since 0.9.16 */
355#define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
356/** Returns 1 when the specified format is reverse endian, 0 when
357 * native. Returns -1 when endianness does not apply to the
358 * specified format, or endianess is unknown. \since 0.9.16 */
359#define pa_sample_format_is_re(f) pa_sample_format_is_be(f)
360#endif
361
362PA_C_DECL_END
363
364#endif
365

source code of include/pulse/sample.h