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 PA_SAMPLE_MAX,
175 /**< Upper limit of valid sample types */
176
177 PA_SAMPLE_INVALID = -1
178 /**< An invalid value */
179} pa_sample_format_t;
180
181#ifdef WORDS_BIGENDIAN
182/** Signed 16 Bit PCM, native endian */
183#define PA_SAMPLE_S16NE PA_SAMPLE_S16BE
184/** 32 Bit IEEE floating point, native endian */
185#define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32BE
186/** Signed 32 Bit PCM, native endian */
187#define PA_SAMPLE_S32NE PA_SAMPLE_S32BE
188/** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
189#define PA_SAMPLE_S24NE PA_SAMPLE_S24BE
190/** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
191#define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32BE
192
193/** Signed 16 Bit PCM reverse endian */
194#define PA_SAMPLE_S16RE PA_SAMPLE_S16LE
195/** 32 Bit IEEE floating point, reverse endian */
196#define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32LE
197/** Signed 32 Bit PCM, reverse endian */
198#define PA_SAMPLE_S32RE PA_SAMPLE_S32LE
199/** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
200#define PA_SAMPLE_S24RE PA_SAMPLE_S24LE
201/** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
202#define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32LE
203#else
204/** Signed 16 Bit PCM, native endian */
205#define PA_SAMPLE_S16NE PA_SAMPLE_S16LE
206/** 32 Bit IEEE floating point, native endian */
207#define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32LE
208/** Signed 32 Bit PCM, native endian */
209#define PA_SAMPLE_S32NE PA_SAMPLE_S32LE
210/** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
211#define PA_SAMPLE_S24NE PA_SAMPLE_S24LE
212/** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
213#define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32LE
214
215/** Signed 16 Bit PCM, reverse endian */
216#define PA_SAMPLE_S16RE PA_SAMPLE_S16BE
217/** 32 Bit IEEE floating point, reverse endian */
218#define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32BE
219/** Signed 32 Bit PCM, reverse endian */
220#define PA_SAMPLE_S32RE PA_SAMPLE_S32BE
221/** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
222#define PA_SAMPLE_S24RE PA_SAMPLE_S24BE
223/** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
224#define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32BE
225#endif
226
227/** A Shortcut for PA_SAMPLE_FLOAT32NE */
228#define PA_SAMPLE_FLOAT32 PA_SAMPLE_FLOAT32NE
229
230/** \cond fulldocs */
231/* Allow clients to check with #ifdef for these sample formats */
232#define PA_SAMPLE_U8 PA_SAMPLE_U8
233#define PA_SAMPLE_ALAW PA_SAMPLE_ALAW
234#define PA_SAMPLE_ULAW PA_SAMPLE_ULAW
235#define PA_SAMPLE_S16LE PA_SAMPLE_S16LE
236#define PA_SAMPLE_S16BE PA_SAMPLE_S16BE
237#define PA_SAMPLE_FLOAT32LE PA_SAMPLE_FLOAT32LE
238#define PA_SAMPLE_FLOAT32BE PA_SAMPLE_FLOAT32BE
239#define PA_SAMPLE_S32LE PA_SAMPLE_S32LE
240#define PA_SAMPLE_S32BE PA_SAMPLE_S32BE
241#define PA_SAMPLE_S24LE PA_SAMPLE_S24LE
242#define PA_SAMPLE_S24BE PA_SAMPLE_S24BE
243#define PA_SAMPLE_S24_32LE PA_SAMPLE_S24_32LE
244#define PA_SAMPLE_S24_32BE PA_SAMPLE_S24_32BE
245/** \endcond */
246
247/** A sample format and attribute specification */
248typedef struct pa_sample_spec {
249 pa_sample_format_t format;
250 /**< The sample format */
251
252 uint32_t rate;
253 /**< The sample rate. (e.g. 44100) */
254
255 uint8_t channels;
256 /**< Audio channels. (1 for mono, 2 for stereo, ...) */
257} pa_sample_spec;
258
259/** Type for usec specifications (unsigned). Always 64 bit. */
260typedef uint64_t pa_usec_t;
261
262/** Return the amount of bytes that constitute playback of one second of
263 * audio, with the specified sample spec. */
264size_t pa_bytes_per_second(const pa_sample_spec *spec) PA_GCC_PURE;
265
266/** Return the size of a frame with the specific sample type */
267size_t pa_frame_size(const pa_sample_spec *spec) PA_GCC_PURE;
268
269/** Return the size of a sample with the specific sample type */
270size_t pa_sample_size(const pa_sample_spec *spec) PA_GCC_PURE;
271
272/** Similar to pa_sample_size() but take a sample format instead of a
273 * full sample spec. \since 0.9.15 */
274size_t pa_sample_size_of_format(pa_sample_format_t f) PA_GCC_PURE;
275
276/** Calculate the time it would take to play a buffer of the specified
277 * size with the specified sample type. The return value will always
278 * be rounded down for non-integral return values. */
279pa_usec_t pa_bytes_to_usec(uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE;
280
281/** Calculates the size of a buffer required, for playback duration
282 * of the time specified, with the specified sample type. The
283 * return value will always be rounded down for non-integral
284 * return values. \since 0.9 */
285size_t pa_usec_to_bytes(pa_usec_t t, const pa_sample_spec *spec) PA_GCC_PURE;
286
287/** Initialize the specified sample spec and return a pointer to
288 * it. The sample spec will have a defined state but
289 * pa_sample_spec_valid() will fail for it. \since 0.9.13 */
290pa_sample_spec* pa_sample_spec_init(pa_sample_spec *spec);
291
292/** Return non-zero if the given integer is a valid sample format. \since 5.0 */
293int pa_sample_format_valid(unsigned format) PA_GCC_PURE;
294
295/** Return non-zero if the rate is within the supported range. \since 5.0 */
296int pa_sample_rate_valid(uint32_t rate) PA_GCC_PURE;
297
298/** Return non-zero if the channel count is within the supported range.
299 * \since 5.0 */
300int pa_channels_valid(uint8_t channels) PA_GCC_PURE;
301
302/** Return non-zero when the sample type specification is valid */
303int pa_sample_spec_valid(const pa_sample_spec *spec) PA_GCC_PURE;
304
305/** Return non-zero when the two sample type specifications match */
306int pa_sample_spec_equal(const pa_sample_spec*a, const pa_sample_spec*b) PA_GCC_PURE;
307
308/** Return a descriptive string for the specified sample format. \since 0.8 */
309const char *pa_sample_format_to_string(pa_sample_format_t f) PA_GCC_PURE;
310
311/** Parse a sample format text. Inverse of pa_sample_format_to_string() */
312pa_sample_format_t pa_parse_sample_format(const char *format) PA_GCC_PURE;
313
314/** Maximum required string length for
315 * pa_sample_spec_snprint(). Please note that this value can change
316 * with any release without warning and without being considered API
317 * or ABI breakage. You should not use this definition anywhere where
318 * it might become part of an ABI. */
319#define PA_SAMPLE_SPEC_SNPRINT_MAX 32
320
321/** Pretty print a sample type specification to a string. Returns \a s. */
322char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
323
324/** Maximum required string length for pa_bytes_snprint(). Please note
325 * that this value can change with any release without warning and
326 * without being considered API or ABI breakage. You should not use
327 * this definition anywhere where it might become part of an
328 * ABI. \since 0.9.16 */
329#define PA_BYTES_SNPRINT_MAX 11
330
331/** Pretty print a byte size value (i.e.\ "2.5 MiB"). Returns \a s. */
332char* pa_bytes_snprint(char *s, size_t l, unsigned v);
333
334/** Returns 1 when the specified format is little endian, 0 when
335 * big endian. Returns -1 when endianness does not apply to the
336 * specified format, or endianess is unknown. \since 0.9.16 */
337int pa_sample_format_is_le(pa_sample_format_t f) PA_GCC_PURE;
338
339/** Returns 1 when the specified format is big endian, 0 when
340 * little endian. Returns -1 when endianness does not apply to the
341 * specified format, or endianess is unknown. \since 0.9.16 */
342int pa_sample_format_is_be(pa_sample_format_t f) PA_GCC_PURE;
343
344#ifdef WORDS_BIGENDIAN
345#define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
346#define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
347#else
348/** Returns 1 when the specified format is native endian, 0 when
349 * not. Returns -1 when endianness does not apply to the
350 * specified format, or endianess is unknown. \since 0.9.16 */
351#define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
352/** Returns 1 when the specified format is reverse endian, 0 when
353 * native. 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_re(f) pa_sample_format_is_be(f)
356#endif
357
358PA_C_DECL_END
359
360#endif
361