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 110 PA_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 */ 134 typedef 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 */ 252 typedef 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. */ 264 typedef 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. */ 268 size_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 */ 271 size_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 */ 274 size_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 */ 278 size_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. */ 283 pa_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 */ 289 size_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 */ 294 pa_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 */ 297 int 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 */ 300 int 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 */ 304 int pa_channels_valid(uint8_t channels) PA_GCC_PURE; 305 306 /** Return non-zero when the sample type specification is valid */ 307 int pa_sample_spec_valid(const pa_sample_spec *spec) PA_GCC_PURE; 308 309 /** Return non-zero when the two sample type specifications match */ 310 int 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 */ 313 const 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() */ 316 pa_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. */ 326 char* 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. */ 336 char* 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 */ 341 int 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 */ 346 int 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 362 PA_C_DECL_END 363 364 #endif 365