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