include/SDL_audio.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 08 Jun 2019 19:02:42 -0700
changeset 12806 b06fa7da012b
parent 12503 806492103856
permissions -rw-r--r--
Fixed bug 3894 - Fuzzing crashes for SDL_LoadWAV

Simon Hug

I had a look at this and made some additions to SDL_wave.c.

The attached patch adds many checks and error messages. For some reason I also added A-law and µ-law decoders. Forgot exactly why... but hey, they're small.

The WAVE format is seriously underspecified (at least by the documents that are publicly available on the internet) and it's a shame Microsoft never put something better out there. The language used in them is so loose at times, it's not surprising the encoders and decoders behave very differently. The Windows Media Player doesn't even support MS ADPCM correctly.

The patch also adds some hints to make the decoder more strict at the cost of compatibility with weird WAVE files.

I still think it needs a bit of cleaning up (Not happy with the MultiplySize function. Don't like the name and other SDL code may want to use something like this too.) and some duplicated code may be folded together. It does work in this state and I have thrown all kinds of WAVE files at it. The AFL files also pass with it and some even play (obviously just noise). Crafty little fuzzer.

Any critique would be welcome. I have a fork of SDL with a audio-loadwav branch over here if someone wants to use the commenting feature of Bitbucket:

https://bitbucket.org/ChliHug/SDL

I also cobbled some Lua scripts together to create WAVE test files:

https://bitbucket.org/ChliHug/gendat
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@12503
     3
  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
slouken@0
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@0
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@0
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@0
    20
*/
slouken@0
    21
slouken@1895
    22
/**
slouken@3407
    23
 *  \file SDL_audio.h
slouken@7191
    24
 *
slouken@3407
    25
 *  Access to the raw audio mixing buffer for the SDL library.
slouken@1895
    26
 */
slouken@0
    27
slouken@10638
    28
#ifndef SDL_audio_h_
slouken@10638
    29
#define SDL_audio_h_
slouken@0
    30
slouken@1353
    31
#include "SDL_stdinc.h"
slouken@0
    32
#include "SDL_error.h"
slouken@1358
    33
#include "SDL_endian.h"
slouken@1358
    34
#include "SDL_mutex.h"
slouken@1358
    35
#include "SDL_thread.h"
slouken@0
    36
#include "SDL_rwops.h"
slouken@0
    37
slouken@0
    38
#include "begin_code.h"
slouken@0
    39
/* Set up for C function definitions, even when using C++ */
slouken@0
    40
#ifdef __cplusplus
slouken@0
    41
extern "C" {
slouken@0
    42
#endif
slouken@0
    43
slouken@3407
    44
/**
slouken@3407
    45
 *  \brief Audio format flags.
slouken@7191
    46
 *
slouken@3407
    47
 *  These are what the 16 bits in SDL_AudioFormat currently mean...
slouken@3407
    48
 *  (Unspecified bits are always zero).
slouken@7191
    49
 *
slouken@3407
    50
 *  \verbatim
slouken@3407
    51
    ++-----------------------sample is signed if set
slouken@3407
    52
    ||
slouken@3407
    53
    ||       ++-----------sample is bigendian if set
slouken@3407
    54
    ||       ||
slouken@3407
    55
    ||       ||          ++---sample is float if set
slouken@3407
    56
    ||       ||          ||
slouken@3407
    57
    ||       ||          || +---sample bit size---+
slouken@3407
    58
    ||       ||          || |                     |
slouken@3407
    59
    15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
slouken@3407
    60
    \endverbatim
slouken@7191
    61
 *
slouken@6251
    62
 *  There are macros in SDL 2.0 and later to query these bits.
slouken@3407
    63
 */
icculus@1964
    64
typedef Uint16 SDL_AudioFormat;
icculus@1964
    65
slouken@3407
    66
/**
slouken@3407
    67
 *  \name Audio flags
slouken@3407
    68
 */
gabomdq@7678
    69
/* @{ */
icculus@1964
    70
icculus@1964
    71
#define SDL_AUDIO_MASK_BITSIZE       (0xFF)
icculus@1964
    72
#define SDL_AUDIO_MASK_DATATYPE      (1<<8)
icculus@1964
    73
#define SDL_AUDIO_MASK_ENDIAN        (1<<12)
icculus@1964
    74
#define SDL_AUDIO_MASK_SIGNED        (1<<15)
icculus@1964
    75
#define SDL_AUDIO_BITSIZE(x)         (x & SDL_AUDIO_MASK_BITSIZE)
icculus@1964
    76
#define SDL_AUDIO_ISFLOAT(x)         (x & SDL_AUDIO_MASK_DATATYPE)
icculus@1964
    77
#define SDL_AUDIO_ISBIGENDIAN(x)     (x & SDL_AUDIO_MASK_ENDIAN)
icculus@1964
    78
#define SDL_AUDIO_ISSIGNED(x)        (x & SDL_AUDIO_MASK_SIGNED)
icculus@1964
    79
#define SDL_AUDIO_ISINT(x)           (!SDL_AUDIO_ISFLOAT(x))
icculus@1964
    80
#define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
icculus@1964
    81
#define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
icculus@1964
    82
slouken@7191
    83
/**
slouken@3407
    84
 *  \name Audio format flags
slouken@3407
    85
 *
slouken@3407
    86
 *  Defaults to LSB byte order.
slouken@3407
    87
 */
gabomdq@7678
    88
/* @{ */
slouken@7191
    89
#define AUDIO_U8        0x0008  /**< Unsigned 8-bit samples */
slouken@7191
    90
#define AUDIO_S8        0x8008  /**< Signed 8-bit samples */
slouken@7191
    91
#define AUDIO_U16LSB    0x0010  /**< Unsigned 16-bit samples */
slouken@7191
    92
#define AUDIO_S16LSB    0x8010  /**< Signed 16-bit samples */
slouken@7191
    93
#define AUDIO_U16MSB    0x1010  /**< As above, but big-endian byte order */
slouken@7191
    94
#define AUDIO_S16MSB    0x9010  /**< As above, but big-endian byte order */
slouken@7191
    95
#define AUDIO_U16       AUDIO_U16LSB
slouken@7191
    96
#define AUDIO_S16       AUDIO_S16LSB
gabomdq@7678
    97
/* @} */
slouken@0
    98
slouken@3407
    99
/**
slouken@3407
   100
 *  \name int32 support
slouken@3407
   101
 */
gabomdq@7678
   102
/* @{ */
slouken@7191
   103
#define AUDIO_S32LSB    0x8020  /**< 32-bit integer samples */
slouken@7191
   104
#define AUDIO_S32MSB    0x9020  /**< As above, but big-endian byte order */
slouken@7191
   105
#define AUDIO_S32       AUDIO_S32LSB
gabomdq@7678
   106
/* @} */
icculus@1964
   107
slouken@3407
   108
/**
slouken@3407
   109
 *  \name float32 support
slouken@3407
   110
 */
gabomdq@7678
   111
/* @{ */
slouken@7191
   112
#define AUDIO_F32LSB    0x8120  /**< 32-bit floating point samples */
slouken@7191
   113
#define AUDIO_F32MSB    0x9120  /**< As above, but big-endian byte order */
slouken@7191
   114
#define AUDIO_F32       AUDIO_F32LSB
gabomdq@7678
   115
/* @} */
icculus@1964
   116
slouken@3407
   117
/**
slouken@3407
   118
 *  \name Native audio byte ordering
slouken@3407
   119
 */
gabomdq@7678
   120
/* @{ */
slouken@0
   121
#if SDL_BYTEORDER == SDL_LIL_ENDIAN
slouken@7191
   122
#define AUDIO_U16SYS    AUDIO_U16LSB
slouken@7191
   123
#define AUDIO_S16SYS    AUDIO_S16LSB
slouken@7191
   124
#define AUDIO_S32SYS    AUDIO_S32LSB
slouken@7191
   125
#define AUDIO_F32SYS    AUDIO_F32LSB
slouken@0
   126
#else
slouken@7191
   127
#define AUDIO_U16SYS    AUDIO_U16MSB
slouken@7191
   128
#define AUDIO_S16SYS    AUDIO_S16MSB
slouken@7191
   129
#define AUDIO_S32SYS    AUDIO_S32MSB
slouken@7191
   130
#define AUDIO_F32SYS    AUDIO_F32MSB
slouken@0
   131
#endif
gabomdq@7678
   132
/* @} */
slouken@0
   133
slouken@7191
   134
/**
slouken@3407
   135
 *  \name Allow change flags
slouken@7191
   136
 *
slouken@3407
   137
 *  Which audio format changes are allowed when opening a device.
slouken@3407
   138
 */
gabomdq@7678
   139
/* @{ */
slouken@2866
   140
#define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
slouken@2866
   141
#define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
slouken@2866
   142
#define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
slouken@12272
   143
#define SDL_AUDIO_ALLOW_SAMPLES_CHANGE      0x00000008
slouken@12272
   144
#define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE)
gabomdq@7678
   145
/* @} */
slouken@0
   146
gabomdq@7678
   147
/* @} *//* Audio flags */
slouken@3407
   148
slouken@3407
   149
/**
slouken@3554
   150
 *  This function is called when the audio device needs more data.
slouken@3554
   151
 *
slouken@3554
   152
 *  \param userdata An application-specific parameter saved in
slouken@3554
   153
 *                  the SDL_AudioSpec structure
slouken@3554
   154
 *  \param stream A pointer to the audio data buffer.
slouken@3554
   155
 *  \param len    The length of that buffer in bytes.
slouken@3554
   156
 *
slouken@3554
   157
 *  Once the callback returns, the buffer will no longer be valid.
slouken@3554
   158
 *  Stereo samples are stored in a LRLRLR ordering.
icculus@9012
   159
 *
icculus@9012
   160
 *  You can choose to avoid callbacks and use SDL_QueueAudio() instead, if
icculus@9012
   161
 *  you like. Just open your audio device with a NULL callback.
slouken@3554
   162
 */
slouken@3554
   163
typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
slouken@3554
   164
                                            int len);
slouken@3554
   165
slouken@3554
   166
/**
slouken@3407
   167
 *  The calculated values in this structure are calculated by SDL_OpenAudio().
slouken@11640
   168
 *
slouken@11640
   169
 *  For multi-channel audio, the default SDL channel mapping is:
slouken@11640
   170
 *  2:  FL FR                       (stereo)
slouken@11640
   171
 *  3:  FL FR LFE                   (2.1 surround)
slouken@11640
   172
 *  4:  FL FR BL BR                 (quad)
slouken@11640
   173
 *  5:  FL FR FC BL BR              (quad + center)
slouken@11640
   174
 *  6:  FL FR FC LFE SL SR          (5.1 surround - last two can also be BL BR)
slouken@11640
   175
 *  7:  FL FR FC LFE BC SL SR       (6.1 surround)
slouken@11640
   176
 *  8:  FL FR FC LFE BL BR SL SR    (7.1 surround)
slouken@3407
   177
 */
slouken@3407
   178
typedef struct SDL_AudioSpec
slouken@3407
   179
{
slouken@3407
   180
    int freq;                   /**< DSP frequency -- samples per second */
slouken@3407
   181
    SDL_AudioFormat format;     /**< Audio data format */
slouken@3407
   182
    Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
slouken@3407
   183
    Uint8 silence;              /**< Audio buffer silence value (calculated) */
icculus@10920
   184
    Uint16 samples;             /**< Audio buffer size in sample FRAMES (total samples divided by channel count) */
slouken@3407
   185
    Uint16 padding;             /**< Necessary for some compile environments */
slouken@3407
   186
    Uint32 size;                /**< Audio buffer size in bytes (calculated) */
icculus@9012
   187
    SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */
icculus@9012
   188
    void *userdata;             /**< Userdata passed to callback (ignored for NULL callbacks). */
slouken@3407
   189
} SDL_AudioSpec;
slouken@3407
   190
slouken@3407
   191
icculus@1983
   192
struct SDL_AudioCVT;
slouken@1985
   193
typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
slouken@1985
   194
                                          SDL_AudioFormat format);
icculus@1983
   195
slouken@3407
   196
/**
slouken@11096
   197
 *  \brief Upper limit of filters in SDL_AudioCVT
slouken@11096
   198
 *
slouken@11096
   199
 *  The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is
slouken@11096
   200
 *  currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers,
slouken@11096
   201
 *  one of which is the terminating NULL pointer.
slouken@11096
   202
 */
slouken@11096
   203
#define SDL_AUDIOCVT_MAX_FILTERS 9
slouken@11096
   204
slouken@11096
   205
/**
slouken@11096
   206
 *  \struct SDL_AudioCVT
slouken@11096
   207
 *  \brief A structure to hold a set of audio conversion filters and buffers.
icculus@10845
   208
 *
icculus@10845
   209
 *  Note that various parts of the conversion pipeline can take advantage
icculus@10845
   210
 *  of SIMD operations (like SSE2, for example). SDL_AudioCVT doesn't require
icculus@10845
   211
 *  you to pass it aligned data, but can possibly run much faster if you
icculus@10845
   212
 *  set both its (buf) field to a pointer that is aligned to 16 bytes, and its
icculus@10845
   213
 *  (len) field to something that's a multiple of 16, if possible.
slouken@3407
   214
 */
slouken@7546
   215
#ifdef __GNUC__
slouken@7546
   216
/* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
slouken@7546
   217
   pad it out to 88 bytes to guarantee ABI compatibility between compilers.
slouken@7546
   218
   vvv
slouken@7546
   219
   The next time we rev the ABI, make sure to size the ints and add padding.
slouken@7546
   220
*/
slouken@7546
   221
#define SDL_AUDIOCVT_PACKED __attribute__((packed))
slouken@7546
   222
#else
slouken@7546
   223
#define SDL_AUDIOCVT_PACKED
slouken@7546
   224
#endif
slouken@7546
   225
/* */
slouken@1895
   226
typedef struct SDL_AudioCVT
slouken@1895
   227
{
slouken@3407
   228
    int needed;                 /**< Set to 1 if conversion possible */
slouken@3407
   229
    SDL_AudioFormat src_format; /**< Source audio format */
slouken@3407
   230
    SDL_AudioFormat dst_format; /**< Target audio format */
slouken@3407
   231
    double rate_incr;           /**< Rate conversion increment */
slouken@3407
   232
    Uint8 *buf;                 /**< Buffer to hold entire audio data */
slouken@3407
   233
    int len;                    /**< Length of original audio buffer */
slouken@3407
   234
    int len_cvt;                /**< Length of converted audio buffer */
slouken@3407
   235
    int len_mult;               /**< buffer must be len*len_mult big */
slouken@3407
   236
    double len_ratio;           /**< Given len, final size is len*len_ratio */
slouken@11096
   237
    SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1]; /**< NULL-terminated list of filter functions */
slouken@3407
   238
    int filter_index;           /**< Current audio conversion function */
slouken@7546
   239
} SDL_AUDIOCVT_PACKED SDL_AudioCVT;
slouken@0
   240
slouken@0
   241
slouken@0
   242
/* Function prototypes */
slouken@0
   243
slouken@3407
   244
/**
slouken@3407
   245
 *  \name Driver discovery functions
slouken@7191
   246
 *
slouken@3407
   247
 *  These functions return the list of built in audio drivers, in the
slouken@3407
   248
 *  order that they are normally initialized by default.
slouken@1895
   249
 */
gabomdq@7678
   250
/* @{ */
slouken@1895
   251
extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
slouken@1895
   252
extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
gabomdq@7678
   253
/* @} */
slouken@1895
   254
slouken@3407
   255
/**
slouken@3407
   256
 *  \name Initialization and cleanup
slouken@7191
   257
 *
slouken@3407
   258
 *  \internal These functions are used internally, and should not be used unless
slouken@7191
   259
 *            you have a specific need to specify the audio driver you want to
slouken@3407
   260
 *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
slouken@0
   261
 */
gabomdq@7678
   262
/* @{ */
slouken@337
   263
extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
slouken@337
   264
extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
gabomdq@7678
   265
/* @} */
slouken@0
   266
slouken@3407
   267
/**
slouken@3407
   268
 *  This function returns the name of the current audio driver, or NULL
slouken@3407
   269
 *  if no driver has been initialized.
slouken@0
   270
 */
slouken@1895
   271
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
slouken@0
   272
slouken@3407
   273
/**
slouken@3407
   274
 *  This function opens the audio device with the desired parameters, and
slouken@3407
   275
 *  returns 0 if successful, placing the actual hardware parameters in the
slouken@3407
   276
 *  structure pointed to by \c obtained.  If \c obtained is NULL, the audio
slouken@3407
   277
 *  data passed to the callback function will be guaranteed to be in the
slouken@3407
   278
 *  requested format, and will be automatically converted to the hardware
slouken@7191
   279
 *  audio format if necessary.  This function returns -1 if it failed
slouken@3407
   280
 *  to open the audio device, or couldn't set up the audio thread.
slouken@7191
   281
 *
slouken@3407
   282
 *  When filling in the desired audio spec structure,
slouken@3407
   283
 *    - \c desired->freq should be the desired audio frequency in samples-per-
slouken@3407
   284
 *      second.
slouken@3407
   285
 *    - \c desired->format should be the desired audio format.
slouken@7191
   286
 *    - \c desired->samples is the desired size of the audio buffer, in
slouken@7191
   287
 *      samples.  This number should be a power of two, and may be adjusted by
slouken@3407
   288
 *      the audio driver to a value more suitable for the hardware.  Good values
slouken@7191
   289
 *      seem to range between 512 and 8096 inclusive, depending on the
slouken@7191
   290
 *      application and CPU speed.  Smaller values yield faster response time,
slouken@7191
   291
 *      but can lead to underflow if the application is doing heavy processing
slouken@7191
   292
 *      and cannot fill the audio buffer in time.  A stereo sample consists of
slouken@3407
   293
 *      both right and left channels in LR ordering.
slouken@3407
   294
 *      Note that the number of samples is directly related to time by the
slouken@3407
   295
 *      following formula:  \code ms = (samples*1000)/freq \endcode
slouken@3407
   296
 *    - \c desired->size is the size in bytes of the audio buffer, and is
slouken@3407
   297
 *      calculated by SDL_OpenAudio().
slouken@3407
   298
 *    - \c desired->silence is the value used to set the buffer to silence,
slouken@3407
   299
 *      and is calculated by SDL_OpenAudio().
slouken@3407
   300
 *    - \c desired->callback should be set to a function that will be called
slouken@3407
   301
 *      when the audio device is ready for more data.  It is passed a pointer
slouken@3407
   302
 *      to the audio buffer, and the length in bytes of the audio buffer.
slouken@3407
   303
 *      This function usually runs in a separate thread, and so you should
slouken@3407
   304
 *      protect data structures that it accesses by calling SDL_LockAudio()
icculus@9012
   305
 *      and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
icculus@9012
   306
 *      pointer here, and call SDL_QueueAudio() with some frequency, to queue
icculus@10262
   307
 *      more audio samples to be played (or for capture devices, call
icculus@10262
   308
 *      SDL_DequeueAudio() with some frequency, to obtain audio samples).
slouken@3407
   309
 *    - \c desired->userdata is passed as the first parameter to your callback
icculus@9012
   310
 *      function. If you passed a NULL callback, this value is ignored.
slouken@7191
   311
 *
slouken@3407
   312
 *  The audio device starts out playing silence when it's opened, and should
slouken@3407
   313
 *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
slouken@3407
   314
 *  for your audio callback function to be called.  Since the audio driver
slouken@3407
   315
 *  may modify the requested size of the audio buffer, you should allocate
slouken@3407
   316
 *  any local mixing buffers after you open the audio device.
slouken@0
   317
 */
slouken@2866
   318
extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
slouken@1895
   319
                                          SDL_AudioSpec * obtained);
slouken@0
   320
slouken@3407
   321
/**
slouken@3407
   322
 *  SDL Audio Device IDs.
slouken@7191
   323
 *
slouken@3407
   324
 *  A successful call to SDL_OpenAudio() is always device id 1, and legacy
icculus@1964
   325
 *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
icculus@1964
   326
 *  always returns devices >= 2 on success. The legacy calls are good both
icculus@1964
   327
 *  for backwards compatibility and when you don't care about multiple,
icculus@1964
   328
 *  specific, or capture devices.
icculus@1964
   329
 */
icculus@1964
   330
typedef Uint32 SDL_AudioDeviceID;
icculus@1964
   331
slouken@3407
   332
/**
slouken@3407
   333
 *  Get the number of available devices exposed by the current driver.
icculus@1964
   334
 *  Only valid after a successfully initializing the audio subsystem.
icculus@2049
   335
 *  Returns -1 if an explicit list of devices can't be determined; this is
icculus@2049
   336
 *  not an error. For example, if SDL is set up to talk to a remote audio
icculus@2049
   337
 *  server, it can't list every one available on the Internet, but it will
icculus@2049
   338
 *  still allow a specific host to be specified to SDL_OpenAudioDevice().
slouken@7191
   339
 *
slouken@3407
   340
 *  In many common cases, when this function returns a value <= 0, it can still
icculus@2049
   341
 *  successfully open the default device (NULL for first argument of
icculus@2049
   342
 *  SDL_OpenAudioDevice()).
icculus@1964
   343
 */
icculus@1964
   344
extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
icculus@1964
   345
slouken@3407
   346
/**
slouken@3407
   347
 *  Get the human-readable name of a specific audio device.
icculus@1964
   348
 *  Must be a value between 0 and (number of audio devices-1).
icculus@1964
   349
 *  Only valid after a successfully initializing the audio subsystem.
icculus@2049
   350
 *  The values returned by this function reflect the latest call to
icculus@2049
   351
 *  SDL_GetNumAudioDevices(); recall that function to redetect available
icculus@2049
   352
 *  hardware.
slouken@7191
   353
 *
slouken@3407
   354
 *  The string returned by this function is UTF-8 encoded, read-only, and
icculus@2049
   355
 *  managed internally. You are not to free it. If you need to keep the
icculus@2049
   356
 *  string for any length of time, you should make your own copy of it, as it
icculus@2049
   357
 *  will be invalid next time any of several other SDL functions is called.
icculus@1964
   358
 */
icculus@2049
   359
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
icculus@2049
   360
                                                           int iscapture);
icculus@1964
   361
icculus@1964
   362
slouken@3407
   363
/**
slouken@3407
   364
 *  Open a specific audio device. Passing in a device name of NULL requests
icculus@2049
   365
 *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
slouken@7191
   366
 *
slouken@3407
   367
 *  The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
icculus@2049
   368
 *  some drivers allow arbitrary and driver-specific strings, such as a
icculus@2049
   369
 *  hostname/IP address for a remote audio server, or a filename in the
icculus@2049
   370
 *  diskaudio driver.
slouken@7191
   371
 *
slouken@3407
   372
 *  \return 0 on error, a valid device ID that is >= 2 on success.
slouken@7191
   373
 *
icculus@2049
   374
 *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
icculus@1964
   375
 */
slouken@1967
   376
extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
slouken@1967
   377
                                                              *device,
slouken@1967
   378
                                                              int iscapture,
slouken@1967
   379
                                                              const
slouken@1967
   380
                                                              SDL_AudioSpec *
slouken@1967
   381
                                                              desired,
slouken@1967
   382
                                                              SDL_AudioSpec *
slouken@2866
   383
                                                              obtained,
slouken@2866
   384
                                                              int
slouken@2866
   385
                                                              allowed_changes);
icculus@1964
   386
icculus@1964
   387
icculus@1964
   388
slouken@3407
   389
/**
slouken@3407
   390
 *  \name Audio state
slouken@7191
   391
 *
slouken@3407
   392
 *  Get the current audio state.
slouken@0
   393
 */
gabomdq@7678
   394
/* @{ */
slouken@1895
   395
typedef enum
slouken@1895
   396
{
slouken@1895
   397
    SDL_AUDIO_STOPPED = 0,
slouken@1895
   398
    SDL_AUDIO_PLAYING,
slouken@1895
   399
    SDL_AUDIO_PAUSED
slouken@3537
   400
} SDL_AudioStatus;
slouken@3537
   401
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
slouken@0
   402
slouken@3537
   403
extern DECLSPEC SDL_AudioStatus SDLCALL
slouken@1967
   404
SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
gabomdq@7678
   405
/* @} *//* Audio State */
icculus@1964
   406
slouken@3407
   407
/**
slouken@3407
   408
 *  \name Pause audio functions
slouken@7191
   409
 *
slouken@3407
   410
 *  These functions pause and unpause the audio callback processing.
slouken@3407
   411
 *  They should be called with a parameter of 0 after opening the audio
slouken@3407
   412
 *  device to start playing sound.  This is so you can safely initialize
slouken@3407
   413
 *  data for your callback function after opening the audio device.
slouken@3407
   414
 *  Silence will be written to the audio device during the pause.
slouken@0
   415
 */
gabomdq@7678
   416
/* @{ */
slouken@337
   417
extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
icculus@1964
   418
extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
icculus@1964
   419
                                                  int pause_on);
gabomdq@7678
   420
/* @} *//* Pause audio functions */
slouken@0
   421
slouken@3407
   422
/**
slouken@12806
   423
 *  \brief Load the audio data of a WAVE file into memory
slouken@12806
   424
 *
slouken@12806
   425
 *  Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
slouken@12806
   426
 *  to be valid pointers. The entire data portion of the file is then loaded
slouken@12806
   427
 *  into memory and decoded if necessary.
slouken@12806
   428
 *
slouken@12806
   429
 *  If \c freesrc is non-zero, the data source gets automatically closed and
slouken@12806
   430
 *  freed before the function returns.
slouken@12806
   431
 *
slouken@12806
   432
 *  Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
slouken@12806
   433
 *  IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
slouken@12806
   434
 *  µ-law (8 bits). Other formats are currently unsupported and cause an error.
slouken@12806
   435
 *
slouken@12806
   436
 *  If this function succeeds, the pointer returned by it is equal to \c spec
slouken@12806
   437
 *  and the pointer to the audio data allocated by the function is written to
slouken@12806
   438
 *  \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
slouken@12806
   439
 *  members \c freq, \c channels, and \c format are set to the values of the
slouken@12806
   440
 *  audio data in the buffer. The \c samples member is set to a sane default and
slouken@12806
   441
 *  all others are set to zero.
slouken@12806
   442
 *
slouken@12806
   443
 *  It's necessary to use SDL_FreeWAV() to free the audio data returned in
slouken@12806
   444
 *  \c audio_buf when it is no longer used.
slouken@12806
   445
 *
slouken@12806
   446
 *  Because of the underspecification of the Waveform format, there are many
slouken@12806
   447
 *  problematic files in the wild that cause issues with strict decoders. To
slouken@12806
   448
 *  provide compatibility with these files, this decoder is lenient in regards
slouken@12806
   449
 *  to the truncation of the file, the fact chunk, and the size of the RIFF
slouken@12806
   450
 *  chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
slouken@12806
   451
 *  and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
slouken@12806
   452
 *  loading process.
slouken@12806
   453
 *
slouken@12806
   454
 *  Any file that is invalid (due to truncation, corruption, or wrong values in
slouken@12806
   455
 *  the headers), too big, or unsupported causes an error. Additionally, any
slouken@12806
   456
 *  critical I/O error from the data source will terminate the loading process
slouken@12806
   457
 *  with an error. The function returns NULL on error and in all cases (with the
slouken@12806
   458
 *  exception of \c src being NULL), an appropriate error message will be set.
slouken@12806
   459
 *
slouken@12806
   460
 *  It is required that the data source supports seeking.
slouken@12806
   461
 *
slouken@12806
   462
 *  Example:
slouken@3407
   463
 *  \code
slouken@7191
   464
 *      SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
slouken@3407
   465
 *  \endcode
slouken@0
   466
 *
slouken@12806
   467
 *  \param src The data source with the WAVE data
slouken@12806
   468
 *  \param freesrc A integer value that makes the function close the data source if non-zero
slouken@12806
   469
 *  \param spec A pointer filled with the audio format of the audio data
slouken@12806
   470
 *  \param audio_buf A pointer filled with the audio data allocated by the function
slouken@12806
   471
 *  \param audio_len A pointer filled with the length of the audio data buffer in bytes
slouken@12806
   472
 *  \return NULL on error, or non-NULL on success.
slouken@0
   473
 */
slouken@1895
   474
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
slouken@1895
   475
                                                      int freesrc,
slouken@1895
   476
                                                      SDL_AudioSpec * spec,
slouken@1895
   477
                                                      Uint8 ** audio_buf,
slouken@1895
   478
                                                      Uint32 * audio_len);
slouken@0
   479
slouken@7191
   480
/**
slouken@3407
   481
 *  Loads a WAV from a file.
slouken@3407
   482
 *  Compatibility convenience function.
slouken@3407
   483
 */
slouken@0
   484
#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
slouken@7191
   485
    SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
slouken@0
   486
slouken@3407
   487
/**
slouken@3407
   488
 *  This function frees data previously allocated with SDL_LoadWAV_RW()
slouken@0
   489
 */
slouken@1895
   490
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
slouken@0
   491
slouken@3407
   492
/**
slouken@3407
   493
 *  This function takes a source format and rate and a destination format
slouken@3407
   494
 *  and rate, and initializes the \c cvt structure with information needed
slouken@3407
   495
 *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
icculus@11319
   496
 *  to the other. An unsupported format causes an error and -1 will be returned.
slouken@7191
   497
 *
icculus@11319
   498
 *  \return 0 if no conversion is needed, 1 if the audio filter is set up,
icculus@11319
   499
 *  or -1 on error.
slouken@0
   500
 */
slouken@1895
   501
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
icculus@1983
   502
                                              SDL_AudioFormat src_format,
slouken@1895
   503
                                              Uint8 src_channels,
slouken@1895
   504
                                              int src_rate,
icculus@1983
   505
                                              SDL_AudioFormat dst_format,
slouken@1895
   506
                                              Uint8 dst_channels,
slouken@1895
   507
                                              int dst_rate);
slouken@0
   508
slouken@3407
   509
/**
slouken@3407
   510
 *  Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
slouken@3407
   511
 *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
slouken@3407
   512
 *  audio data in the source format, this function will convert it in-place
slouken@3407
   513
 *  to the desired format.
slouken@7191
   514
 *
slouken@3407
   515
 *  The data conversion may expand the size of the audio data, so the buffer
slouken@3407
   516
 *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
slouken@3407
   517
 *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
icculus@11319
   518
 *
icculus@11319
   519
 *  \return 0 on success or -1 if \c cvt->buf is NULL.
slouken@0
   520
 */
slouken@1895
   521
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
slouken@0
   522
slouken@11631
   523
/* SDL_AudioStream is a new audio conversion interface.
slouken@11631
   524
   The benefits vs SDL_AudioCVT:
slouken@11631
   525
    - it can handle resampling data in chunks without generating
slouken@11631
   526
      artifacts, when it doesn't have the complete buffer available.
slouken@11631
   527
    - it can handle incoming data in any variable size.
slouken@11631
   528
    - You push data as you have it, and pull it when you need it
slouken@11631
   529
 */
slouken@11631
   530
/* this is opaque to the outside world. */
slouken@11631
   531
struct _SDL_AudioStream;
slouken@11631
   532
typedef struct _SDL_AudioStream SDL_AudioStream;
slouken@11631
   533
slouken@11631
   534
/**
slouken@11631
   535
 *  Create a new audio stream
slouken@11631
   536
 *
slouken@11631
   537
 *  \param src_format The format of the source audio
slouken@11631
   538
 *  \param src_channels The number of channels of the source audio
slouken@11631
   539
 *  \param src_rate The sampling rate of the source audio
slouken@11631
   540
 *  \param dst_format The format of the desired audio output
slouken@11631
   541
 *  \param dst_channels The number of channels of the desired audio output
slouken@11631
   542
 *  \param dst_rate The sampling rate of the desired audio output
slouken@11631
   543
 *  \return 0 on success, or -1 on error.
slouken@11631
   544
 *
slouken@11631
   545
 *  \sa SDL_AudioStreamPut
slouken@11631
   546
 *  \sa SDL_AudioStreamGet
slouken@11631
   547
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   548
 *  \sa SDL_AudioStreamFlush
slouken@11631
   549
 *  \sa SDL_AudioStreamClear
slouken@11631
   550
 *  \sa SDL_FreeAudioStream
slouken@11631
   551
 */
slouken@11631
   552
extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
slouken@11631
   553
                                           const Uint8 src_channels,
slouken@11631
   554
                                           const int src_rate,
slouken@11631
   555
                                           const SDL_AudioFormat dst_format,
slouken@11631
   556
                                           const Uint8 dst_channels,
slouken@11631
   557
                                           const int dst_rate);
slouken@11631
   558
slouken@11631
   559
/**
slouken@11631
   560
 *  Add data to be converted/resampled to the stream
slouken@11631
   561
 *
slouken@11631
   562
 *  \param stream The stream the audio data is being added to
slouken@11631
   563
 *  \param buf A pointer to the audio data to add
icculus@11748
   564
 *  \param len The number of bytes to write to the stream
slouken@11631
   565
 *  \return 0 on success, or -1 on error.
slouken@11631
   566
 *
slouken@11631
   567
 *  \sa SDL_NewAudioStream
slouken@11631
   568
 *  \sa SDL_AudioStreamGet
slouken@11631
   569
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   570
 *  \sa SDL_AudioStreamFlush
slouken@11631
   571
 *  \sa SDL_AudioStreamClear
slouken@11631
   572
 *  \sa SDL_FreeAudioStream
slouken@11631
   573
 */
slouken@11631
   574
extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
slouken@11631
   575
slouken@11631
   576
/**
slouken@11631
   577
 *  Get converted/resampled data from the stream
slouken@11631
   578
 *
slouken@11631
   579
 *  \param stream The stream the audio is being requested from
slouken@11631
   580
 *  \param buf A buffer to fill with audio data
slouken@11631
   581
 *  \param len The maximum number of bytes to fill
slouken@11631
   582
 *  \return The number of bytes read from the stream, or -1 on error
slouken@11631
   583
 *
slouken@11631
   584
 *  \sa SDL_NewAudioStream
slouken@11631
   585
 *  \sa SDL_AudioStreamPut
slouken@11631
   586
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   587
 *  \sa SDL_AudioStreamFlush
slouken@11631
   588
 *  \sa SDL_AudioStreamClear
slouken@11631
   589
 *  \sa SDL_FreeAudioStream
slouken@11631
   590
 */
slouken@11631
   591
extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
slouken@11631
   592
slouken@11631
   593
/**
icculus@11636
   594
 * Get the number of converted/resampled bytes available. The stream may be
icculus@11636
   595
 *  buffering data behind the scenes until it has enough to resample
icculus@11636
   596
 *  correctly, so this number might be lower than what you expect, or even
icculus@11636
   597
 *  be zero. Add more data or flush the stream if you need the data now.
icculus@11636
   598
 *
icculus@11636
   599
 *  \sa SDL_NewAudioStream
icculus@11636
   600
 *  \sa SDL_AudioStreamPut
icculus@11636
   601
 *  \sa SDL_AudioStreamGet
slouken@11639
   602
 *  \sa SDL_AudioStreamFlush
icculus@11636
   603
 *  \sa SDL_AudioStreamClear
icculus@11636
   604
 *  \sa SDL_FreeAudioStream
icculus@11636
   605
 */
icculus@11636
   606
extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
icculus@11636
   607
icculus@11636
   608
/**
icculus@11636
   609
 * Tell the stream that you're done sending data, and anything being buffered
icculus@11636
   610
 *  should be converted/resampled and made available immediately.
icculus@11636
   611
 *
icculus@11636
   612
 * It is legal to add more data to a stream after flushing, but there will
icculus@11636
   613
 *  be audio gaps in the output. Generally this is intended to signal the
icculus@11636
   614
 *  end of input, so the complete output becomes available.
slouken@11631
   615
 *
slouken@11631
   616
 *  \sa SDL_NewAudioStream
slouken@11631
   617
 *  \sa SDL_AudioStreamPut
slouken@11631
   618
 *  \sa SDL_AudioStreamGet
slouken@11639
   619
 *  \sa SDL_AudioStreamAvailable
slouken@11631
   620
 *  \sa SDL_AudioStreamClear
slouken@11631
   621
 *  \sa SDL_FreeAudioStream
slouken@11631
   622
 */
icculus@11636
   623
extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
slouken@11631
   624
slouken@11631
   625
/**
slouken@11631
   626
 *  Clear any pending data in the stream without converting it
slouken@11631
   627
 *
slouken@11631
   628
 *  \sa SDL_NewAudioStream
slouken@11631
   629
 *  \sa SDL_AudioStreamPut
slouken@11631
   630
 *  \sa SDL_AudioStreamGet
slouken@11631
   631
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   632
 *  \sa SDL_AudioStreamFlush
slouken@11631
   633
 *  \sa SDL_FreeAudioStream
slouken@11631
   634
 */
slouken@11631
   635
extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
slouken@11631
   636
slouken@11631
   637
/**
slouken@11631
   638
 * Free an audio stream
slouken@11631
   639
 *
slouken@11631
   640
 *  \sa SDL_NewAudioStream
slouken@11631
   641
 *  \sa SDL_AudioStreamPut
slouken@11631
   642
 *  \sa SDL_AudioStreamGet
slouken@11631
   643
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   644
 *  \sa SDL_AudioStreamFlush
slouken@11631
   645
 *  \sa SDL_AudioStreamClear
slouken@11631
   646
 */
slouken@11631
   647
extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
slouken@11631
   648
slouken@3407
   649
#define SDL_MIX_MAXVOLUME 128
slouken@3407
   650
/**
slouken@3407
   651
 *  This takes two audio buffers of the playing audio format and mixes
slouken@3407
   652
 *  them, performing addition, volume adjustment, and overflow clipping.
slouken@3407
   653
 *  The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
slouken@3407
   654
 *  for full audio volume.  Note this does not change hardware volume.
slouken@3407
   655
 *  This is provided for convenience -- you can mix your own audio data.
slouken@0
   656
 */
slouken@1895
   657
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
slouken@1895
   658
                                          Uint32 len, int volume);
slouken@0
   659
slouken@3407
   660
/**
slouken@3407
   661
 *  This works like SDL_MixAudio(), but you specify the audio format instead of
icculus@1964
   662
 *  using the format of audio device 1. Thus it can be used when no audio
icculus@1964
   663
 *  device is open at all.
icculus@1964
   664
 */
slouken@1967
   665
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
slouken@1967
   666
                                                const Uint8 * src,
icculus@1964
   667
                                                SDL_AudioFormat format,
icculus@1964
   668
                                                Uint32 len, int volume);
icculus@1964
   669
slouken@3407
   670
/**
icculus@9012
   671
 *  Queue more audio on non-callback devices.
icculus@9012
   672
 *
icculus@10262
   673
 *  (If you are looking to retrieve queued audio from a non-callback capture
icculus@10262
   674
 *  device, you want SDL_DequeueAudio() instead. This will return -1 to
icculus@10262
   675
 *  signify an error if you use it with capture devices.)
icculus@10262
   676
 *
icculus@9012
   677
 *  SDL offers two ways to feed audio to the device: you can either supply a
icculus@9012
   678
 *  callback that SDL triggers with some frequency to obtain more audio
icculus@9012
   679
 *  (pull method), or you can supply no callback, and then SDL will expect
icculus@9012
   680
 *  you to supply data at regular intervals (push method) with this function.
icculus@9012
   681
 *
icculus@9012
   682
 *  There are no limits on the amount of data you can queue, short of
icculus@9012
   683
 *  exhaustion of address space. Queued data will drain to the device as
icculus@9012
   684
 *  necessary without further intervention from you. If the device needs
icculus@9012
   685
 *  audio but there is not enough queued, it will play silence to make up
icculus@9012
   686
 *  the difference. This means you will have skips in your audio playback
icculus@9012
   687
 *  if you aren't routinely queueing sufficient data.
icculus@9012
   688
 *
icculus@9012
   689
 *  This function copies the supplied data, so you are safe to free it when
icculus@9012
   690
 *  the function returns. This function is thread-safe, but queueing to the
icculus@9012
   691
 *  same device from two threads at once does not promise which buffer will
icculus@9012
   692
 *  be queued first.
icculus@9012
   693
 *
icculus@9012
   694
 *  You may not queue audio on a device that is using an application-supplied
icculus@9012
   695
 *  callback; doing so returns an error. You have to use the audio callback
icculus@9012
   696
 *  or queue audio with this function, but not both.
icculus@9012
   697
 *
icculus@9012
   698
 *  You should not call SDL_LockAudio() on the device before queueing; SDL
icculus@9012
   699
 *  handles locking internally for this function.
icculus@9012
   700
 *
icculus@9012
   701
 *  \param dev The device ID to which we will queue audio.
icculus@9012
   702
 *  \param data The data to queue to the device for later playback.
icculus@9012
   703
 *  \param len The number of bytes (not samples!) to which (data) points.
slouken@11631
   704
 *  \return 0 on success, or -1 on error.
icculus@9012
   705
 *
icculus@9012
   706
 *  \sa SDL_GetQueuedAudioSize
icculus@9012
   707
 *  \sa SDL_ClearQueuedAudio
icculus@9012
   708
 */
icculus@9012
   709
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
icculus@9012
   710
icculus@9012
   711
/**
icculus@10262
   712
 *  Dequeue more audio on non-callback devices.
icculus@10262
   713
 *
icculus@10262
   714
 *  (If you are looking to queue audio for output on a non-callback playback
icculus@10262
   715
 *  device, you want SDL_QueueAudio() instead. This will always return 0
icculus@10262
   716
 *  if you use it with playback devices.)
icculus@10262
   717
 *
icculus@10262
   718
 *  SDL offers two ways to retrieve audio from a capture device: you can
icculus@10262
   719
 *  either supply a callback that SDL triggers with some frequency as the
icculus@10262
   720
 *  device records more audio data, (push method), or you can supply no
icculus@10262
   721
 *  callback, and then SDL will expect you to retrieve data at regular
icculus@10262
   722
 *  intervals (pull method) with this function.
icculus@10262
   723
 *
icculus@10262
   724
 *  There are no limits on the amount of data you can queue, short of
icculus@10262
   725
 *  exhaustion of address space. Data from the device will keep queuing as
icculus@10262
   726
 *  necessary without further intervention from you. This means you will
icculus@10262
   727
 *  eventually run out of memory if you aren't routinely dequeueing data.
icculus@10262
   728
 *
icculus@10262
   729
 *  Capture devices will not queue data when paused; if you are expecting
icculus@10262
   730
 *  to not need captured audio for some length of time, use
icculus@10262
   731
 *  SDL_PauseAudioDevice() to stop the capture device from queueing more
icculus@10262
   732
 *  data. This can be useful during, say, level loading times. When
icculus@10262
   733
 *  unpaused, capture devices will start queueing data from that point,
icculus@10262
   734
 *  having flushed any capturable data available while paused.
icculus@10262
   735
 *
icculus@10262
   736
 *  This function is thread-safe, but dequeueing from the same device from
icculus@10262
   737
 *  two threads at once does not promise which thread will dequeued data
icculus@10262
   738
 *  first.
icculus@10262
   739
 *
icculus@10262
   740
 *  You may not dequeue audio from a device that is using an
icculus@10262
   741
 *  application-supplied callback; doing so returns an error. You have to use
icculus@10262
   742
 *  the audio callback, or dequeue audio with this function, but not both.
icculus@10262
   743
 *
icculus@10262
   744
 *  You should not call SDL_LockAudio() on the device before queueing; SDL
icculus@10262
   745
 *  handles locking internally for this function.
icculus@10262
   746
 *
icculus@10262
   747
 *  \param dev The device ID from which we will dequeue audio.
icculus@10262
   748
 *  \param data A pointer into where audio data should be copied.
icculus@10262
   749
 *  \param len The number of bytes (not samples!) to which (data) points.
icculus@10262
   750
 *  \return number of bytes dequeued, which could be less than requested.
icculus@10262
   751
 *
icculus@10262
   752
 *  \sa SDL_GetQueuedAudioSize
icculus@10262
   753
 *  \sa SDL_ClearQueuedAudio
icculus@10262
   754
 */
icculus@10262
   755
extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
icculus@10262
   756
icculus@10262
   757
/**
icculus@9012
   758
 *  Get the number of bytes of still-queued audio.
icculus@9012
   759
 *
icculus@10262
   760
 *  For playback device:
icculus@9012
   761
 *
icculus@10262
   762
 *    This is the number of bytes that have been queued for playback with
icculus@10262
   763
 *    SDL_QueueAudio(), but have not yet been sent to the hardware. This
icculus@10262
   764
 *    number may shrink at any time, so this only informs of pending data.
icculus@10262
   765
 *
icculus@10262
   766
 *    Once we've sent it to the hardware, this function can not decide the
icculus@10262
   767
 *    exact byte boundary of what has been played. It's possible that we just
icculus@10262
   768
 *    gave the hardware several kilobytes right before you called this
icculus@10262
   769
 *    function, but it hasn't played any of it yet, or maybe half of it, etc.
icculus@10262
   770
 *
icculus@10262
   771
 *  For capture devices:
icculus@10262
   772
 *
icculus@10262
   773
 *    This is the number of bytes that have been captured by the device and
icculus@10262
   774
 *    are waiting for you to dequeue. This number may grow at any time, so
icculus@10262
   775
 *    this only informs of the lower-bound of available data.
icculus@9012
   776
 *
icculus@9012
   777
 *  You may not queue audio on a device that is using an application-supplied
icculus@9012
   778
 *  callback; calling this function on such a device always returns 0.
icculus@10262
   779
 *  You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
icculus@10262
   780
 *  the audio callback, but not both.
icculus@9012
   781
 *
icculus@9012
   782
 *  You should not call SDL_LockAudio() on the device before querying; SDL
icculus@9012
   783
 *  handles locking internally for this function.
icculus@9012
   784
 *
icculus@9012
   785
 *  \param dev The device ID of which we will query queued audio size.
icculus@9012
   786
 *  \return Number of bytes (not samples!) of queued audio.
icculus@9012
   787
 *
icculus@9012
   788
 *  \sa SDL_QueueAudio
icculus@9012
   789
 *  \sa SDL_ClearQueuedAudio
icculus@9012
   790
 */
icculus@9012
   791
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
icculus@9012
   792
icculus@9012
   793
/**
icculus@10262
   794
 *  Drop any queued audio data. For playback devices, this is any queued data
icculus@10262
   795
 *  still waiting to be submitted to the hardware. For capture devices, this
icculus@10262
   796
 *  is any data that was queued by the device that hasn't yet been dequeued by
icculus@10262
   797
 *  the application.
icculus@9012
   798
 *
icculus@10262
   799
 *  Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
icculus@10262
   800
 *  playback devices, the hardware will start playing silence if more audio
icculus@10262
   801
 *  isn't queued. Unpaused capture devices will start filling the queue again
icculus@10262
   802
 *  as soon as they have more data available (which, depending on the state
icculus@10262
   803
 *  of the hardware and the thread, could be before this function call
icculus@10262
   804
 *  returns!).
icculus@9012
   805
 *
icculus@9012
   806
 *  This will not prevent playback of queued audio that's already been sent
icculus@9012
   807
 *  to the hardware, as we can not undo that, so expect there to be some
icculus@9012
   808
 *  fraction of a second of audio that might still be heard. This can be
icculus@9012
   809
 *  useful if you want to, say, drop any pending music during a level change
icculus@9012
   810
 *  in your game.
icculus@9012
   811
 *
icculus@9012
   812
 *  You may not queue audio on a device that is using an application-supplied
icculus@9012
   813
 *  callback; calling this function on such a device is always a no-op.
icculus@10262
   814
 *  You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
icculus@10262
   815
 *  the audio callback, but not both.
icculus@9012
   816
 *
icculus@9012
   817
 *  You should not call SDL_LockAudio() on the device before clearing the
icculus@9012
   818
 *  queue; SDL handles locking internally for this function.
icculus@9012
   819
 *
icculus@9012
   820
 *  This function always succeeds and thus returns void.
icculus@9012
   821
 *
icculus@9012
   822
 *  \param dev The device ID of which to clear the audio queue.
icculus@9012
   823
 *
icculus@9012
   824
 *  \sa SDL_QueueAudio
icculus@9012
   825
 *  \sa SDL_GetQueuedAudioSize
icculus@9012
   826
 */
icculus@9012
   827
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
icculus@9012
   828
icculus@9012
   829
icculus@9012
   830
/**
slouken@3407
   831
 *  \name Audio lock functions
slouken@7191
   832
 *
slouken@3407
   833
 *  The lock manipulated by these functions protects the callback function.
slouken@7191
   834
 *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
slouken@3407
   835
 *  the callback function is not running.  Do not call these from the callback
slouken@3407
   836
 *  function or you will cause deadlock.
slouken@0
   837
 */
gabomdq@7678
   838
/* @{ */
slouken@337
   839
extern DECLSPEC void SDLCALL SDL_LockAudio(void);
icculus@1964
   840
extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
slouken@337
   841
extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
icculus@1964
   842
extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
gabomdq@7678
   843
/* @} *//* Audio lock functions */
slouken@0
   844
slouken@3407
   845
/**
slouken@3407
   846
 *  This function shuts down audio processing and closes the audio device.
slouken@0
   847
 */
slouken@337
   848
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
icculus@1964
   849
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
icculus@1964
   850
slouken@0
   851
/* Ends C function definitions when using C++ */
slouken@0
   852
#ifdef __cplusplus
slouken@0
   853
}
slouken@0
   854
#endif
slouken@0
   855
#include "close_code.h"
slouken@0
   856
slouken@10638
   857
#endif /* SDL_audio_h_ */
slouken@1895
   858
slouken@1895
   859
/* vi: set ts=4 sw=4 expandtab: */