code.delx.au - pulseaudio/blob - src/pulse/sample.h

   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, 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
 116 #if defined(__BYTE_ORDER)
 117 #if __BYTE_ORDER == __BIG_ENDIAN
 118 #define WORDS_BIGENDIAN
 119 #endif
 120 #endif
 121
 122 /* On Sparc, WORDS_BIGENDIAN needs to be set if _BIG_ENDIAN is defined. */
 123 #if defined(__sparc__) && defined(_BIG_ENDIAN)
 124 #define WORDS_BIGENDIAN
 125 #endif
 126
 127 #endif
 128
 129 /** Maximum number of allowed channels */
 130 #define PA_CHANNELS_MAX 32U
 131
 132 /** Maximum allowed sample rate */
 133 #define PA_RATE_MAX (48000U*4U)
 134
 135 /** Sample format */
 136 typedef enum pa_sample_format {
 137     PA_SAMPLE_U8,
 138     /**< Unsigned 8 Bit PCM */
 139
 140     PA_SAMPLE_ALAW,
 141     /**< 8 Bit a-Law */
 142
 143     PA_SAMPLE_ULAW,
 144     /**< 8 Bit mu-Law */
 145
 146     PA_SAMPLE_S16LE,
 147     /**< Signed 16 Bit PCM, little endian (PC) */
 148
 149     PA_SAMPLE_S16BE,
 150     /**< Signed 16 Bit PCM, big endian */
 151
 152     PA_SAMPLE_FLOAT32LE,
 153     /**< 32 Bit IEEE floating point, little endian (PC), range -1.0 to 1.0 */
 154
 155     PA_SAMPLE_FLOAT32BE,
 156     /**< 32 Bit IEEE floating point, big endian, range -1.0 to 1.0 */
 157
 158     PA_SAMPLE_S32LE,
 159     /**< Signed 32 Bit PCM, little endian (PC) */
 160
 161     PA_SAMPLE_S32BE,
 162     /**< Signed 32 Bit PCM, big endian */
 163
 164     PA_SAMPLE_S24LE,
 165     /**< Signed 24 Bit PCM packed, little endian (PC). \since 0.9.15 */
 166
 167     PA_SAMPLE_S24BE,
 168     /**< Signed 24 Bit PCM packed, big endian. \since 0.9.15 */
 169
 170     PA_SAMPLE_S24_32LE,
 171     /**< Signed 24 Bit PCM in LSB of 32 Bit words, little endian (PC). \since 0.9.15 */
 172
 173     PA_SAMPLE_S24_32BE,
 174     /**< Signed 24 Bit PCM in LSB of 32 Bit words, big endian. \since 0.9.15 */
 175
 176     PA_SAMPLE_MAX,
 177     /**< Upper limit of valid sample types */
 178
 179     PA_SAMPLE_INVALID = -1
 180     /**< An invalid value */
 181 } pa_sample_format_t;
 182
 183 #ifdef WORDS_BIGENDIAN
 184 /** Signed 16 Bit PCM, native endian */
 185 #define PA_SAMPLE_S16NE PA_SAMPLE_S16BE
 186 /** 32 Bit IEEE floating point, native endian */
 187 #define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32BE
 188 /** Signed 32 Bit PCM, native endian */
 189 #define PA_SAMPLE_S32NE PA_SAMPLE_S32BE
 190 /** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
 191 #define PA_SAMPLE_S24NE PA_SAMPLE_S24BE
 192 /** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
 193 #define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32BE
 194
 195 /** Signed 16 Bit PCM reverse endian */
 196 #define PA_SAMPLE_S16RE PA_SAMPLE_S16LE
 197 /** 32 Bit IEEE floating point, reverse endian */
 198 #define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32LE
 199 /** Signed 32 Bit PCM, reverse endian */
 200 #define PA_SAMPLE_S32RE PA_SAMPLE_S32LE
 201 /** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
 202 #define PA_SAMPLE_S24RE PA_SAMPLE_S24LE
 203 /** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
 204 #define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32LE
 205 #else
 206 /** Signed 16 Bit PCM, native endian */
 207 #define PA_SAMPLE_S16NE PA_SAMPLE_S16LE
 208 /** 32 Bit IEEE floating point, native endian */
 209 #define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32LE
 210 /** Signed 32 Bit PCM, native endian */
 211 #define PA_SAMPLE_S32NE PA_SAMPLE_S32LE
 212 /** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
 213 #define PA_SAMPLE_S24NE PA_SAMPLE_S24LE
 214 /** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
 215 #define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32LE
 216
 217 /** Signed 16 Bit PCM, reverse endian */
 218 #define PA_SAMPLE_S16RE PA_SAMPLE_S16BE
 219 /** 32 Bit IEEE floating point, reverse endian */
 220 #define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32BE
 221 /** Signed 32 Bit PCM, reverse endian */
 222 #define PA_SAMPLE_S32RE PA_SAMPLE_S32BE
 223 /** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
 224 #define PA_SAMPLE_S24RE PA_SAMPLE_S24BE
 225 /** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
 226 #define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32BE
 227 #endif
 228
 229 /** A Shortcut for PA_SAMPLE_FLOAT32NE */
 230 #define PA_SAMPLE_FLOAT32 PA_SAMPLE_FLOAT32NE
 231
 232 /** \cond fulldocs */
 233 /* Allow clients to check with #ifdef for these sample formats */
 234 #define PA_SAMPLE_U8 PA_SAMPLE_U8
 235 #define PA_SAMPLE_ALAW PA_SAMPLE_ALAW
 236 #define PA_SAMPLE_ULAW PA_SAMPLE_ULAW
 237 #define PA_SAMPLE_S16LE PA_SAMPLE_S16LE
 238 #define PA_SAMPLE_S16BE PA_SAMPLE_S16BE
 239 #define PA_SAMPLE_FLOAT32LE PA_SAMPLE_FLOAT32LE
 240 #define PA_SAMPLE_FLOAT32BE PA_SAMPLE_FLOAT32BE
 241 #define PA_SAMPLE_S32LE PA_SAMPLE_S32LE
 242 #define PA_SAMPLE_S32BE PA_SAMPLE_S32BE
 243 #define PA_SAMPLE_S24LE PA_SAMPLE_S24LE
 244 #define PA_SAMPLE_S24BE PA_SAMPLE_S24BE
 245 #define PA_SAMPLE_S24_32LE PA_SAMPLE_S24_32LE
 246 #define PA_SAMPLE_S24_32BE PA_SAMPLE_S24_32BE
 247 /** \endcond */
 248
 249 /** A sample format and attribute specification */
 250 typedef struct pa_sample_spec {
 251     pa_sample_format_t format;
 252     /**< The sample format */
 253
 254     uint32_t rate;
 255     /**< The sample rate. (e.g. 44100) */
 256
 257     uint8_t channels;
 258     /**< Audio channels. (1 for mono, 2 for stereo, ...) */
 259 } pa_sample_spec;
 260
 261 /** Type for usec specifications (unsigned). Always 64 bit. */
 262 typedef uint64_t pa_usec_t;
 263
 264 /** Return the amount of bytes playback of a second of audio with the specified sample type takes */
 265 size_t pa_bytes_per_second(const pa_sample_spec *spec) PA_GCC_PURE;
 266
 267 /** Return the size of a frame with the specific sample type */
 268 size_t pa_frame_size(const pa_sample_spec *spec) PA_GCC_PURE;
 269
 270 /** Return the size of a sample with the specific sample type */
 271 size_t pa_sample_size(const pa_sample_spec *spec) PA_GCC_PURE;
 272
 273 /** Similar to pa_sample_size() but take a sample format instead of a
 274  * full sample spec. \since 0.9.15 */
 275 size_t pa_sample_size_of_format(pa_sample_format_t f) PA_GCC_PURE;
 276
 277 /** Calculate the time the specified bytes take to play with the
 278  * specified sample type. The return value will always be rounded
 279  * down for non-integral return values. */
 280 pa_usec_t pa_bytes_to_usec(uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE;
 281
 282 /** Calculates the number of bytes that are required for the specified
 283  * time. The return value will always be rounded down for non-integral
 284  * return values. \since 0.9 */
 285 size_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 */
 290 pa_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 */
 293 int 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 */
 296 int 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 */
 300 int pa_channels_valid(uint8_t channels) PA_GCC_PURE;
 301
 302 /** Return non-zero when the sample type specification is valid */
 303 int pa_sample_spec_valid(const pa_sample_spec *spec) PA_GCC_PURE;
 304
 305 /** Return non-zero when the two sample type specifications match */
 306 int 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 */
 309 const 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() */
 312 pa_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 */
 322 char* 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") */
 332 char* pa_bytes_snprint(char *s, size_t l, unsigned v);
 333
 334 /** Return 1 when the specified format is little endian, return -1
 335  * when endianness does not apply to this format. \since 0.9.16 */
 336 int pa_sample_format_is_le(pa_sample_format_t f) PA_GCC_PURE;
 337
 338 /** Return 1 when the specified format is big endian, return -1 when
 339  * endianness does not apply to this format. \since 0.9.16 */
 340 int pa_sample_format_is_be(pa_sample_format_t f) PA_GCC_PURE;
 341
 342 #ifdef WORDS_BIGENDIAN
 343 #define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
 344 #define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
 345 #else
 346 /** Return 1 when the specified format is native endian, return -1
 347  * when endianness does not apply to this format. \since 0.9.16 */
 348 #define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
 349 /** Return 1 when the specified format is reverse endian, return -1
 350  * when endianness does not apply to this format. \since 0.9.16 */
 351 #define pa_sample_format_is_re(f) pa_sample_format_is_be(f)
 352 #endif
 353
 354 PA_C_DECL_END
 355
 356 #endif