include/SDL_audio.h
author Steven M. Vascellaro <svascellaro@gmail.com>
Mon, 22 Oct 2018 10:55:18 -0400
changeset 12379 5dc13016cf34
parent 12272 c68b05ca0761
child 12503 806492103856
permissions -rw-r--r--
joystick: Add Linux mappings for "Xbox One Wireless Controller (Model 1708)"

Adds controller bindings to support the "Xbox One Wireless Controller
(Model 1708)" on Linux. The Model 1708 was released in 2016 alongside the
Xbox One S. It is the current model being sold by Microsoft as of writing.
(October 22, 2018)
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@11811
     3
  Copyright (C) 1997-2018 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@3407
   423
 *  This function loads a WAVE from the data source, automatically freeing
slouken@3407
   424
 *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
slouken@3407
   425
 *  you could do:
slouken@3407
   426
 *  \code
slouken@7191
   427
 *      SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
slouken@3407
   428
 *  \endcode
slouken@0
   429
 *
slouken@3407
   430
 *  If this function succeeds, it returns the given SDL_AudioSpec,
slouken@3407
   431
 *  filled with the audio data format of the wave data, and sets
slouken@3407
   432
 *  \c *audio_buf to a malloc()'d buffer containing the audio data,
slouken@3407
   433
 *  and sets \c *audio_len to the length of that audio buffer, in bytes.
slouken@7191
   434
 *  You need to free the audio buffer with SDL_FreeWAV() when you are
slouken@3407
   435
 *  done with it.
slouken@0
   436
 *
slouken@7191
   437
 *  This function returns NULL and sets the SDL error message if the
slouken@7191
   438
 *  wave file cannot be opened, uses an unknown data format, or is
slouken@3407
   439
 *  corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
slouken@0
   440
 */
slouken@1895
   441
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
slouken@1895
   442
                                                      int freesrc,
slouken@1895
   443
                                                      SDL_AudioSpec * spec,
slouken@1895
   444
                                                      Uint8 ** audio_buf,
slouken@1895
   445
                                                      Uint32 * audio_len);
slouken@0
   446
slouken@7191
   447
/**
slouken@3407
   448
 *  Loads a WAV from a file.
slouken@3407
   449
 *  Compatibility convenience function.
slouken@3407
   450
 */
slouken@0
   451
#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
slouken@7191
   452
    SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
slouken@0
   453
slouken@3407
   454
/**
slouken@3407
   455
 *  This function frees data previously allocated with SDL_LoadWAV_RW()
slouken@0
   456
 */
slouken@1895
   457
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
slouken@0
   458
slouken@3407
   459
/**
slouken@3407
   460
 *  This function takes a source format and rate and a destination format
slouken@3407
   461
 *  and rate, and initializes the \c cvt structure with information needed
slouken@3407
   462
 *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
icculus@11319
   463
 *  to the other. An unsupported format causes an error and -1 will be returned.
slouken@7191
   464
 *
icculus@11319
   465
 *  \return 0 if no conversion is needed, 1 if the audio filter is set up,
icculus@11319
   466
 *  or -1 on error.
slouken@0
   467
 */
slouken@1895
   468
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
icculus@1983
   469
                                              SDL_AudioFormat src_format,
slouken@1895
   470
                                              Uint8 src_channels,
slouken@1895
   471
                                              int src_rate,
icculus@1983
   472
                                              SDL_AudioFormat dst_format,
slouken@1895
   473
                                              Uint8 dst_channels,
slouken@1895
   474
                                              int dst_rate);
slouken@0
   475
slouken@3407
   476
/**
slouken@3407
   477
 *  Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
slouken@3407
   478
 *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
slouken@3407
   479
 *  audio data in the source format, this function will convert it in-place
slouken@3407
   480
 *  to the desired format.
slouken@7191
   481
 *
slouken@3407
   482
 *  The data conversion may expand the size of the audio data, so the buffer
slouken@3407
   483
 *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
slouken@3407
   484
 *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
icculus@11319
   485
 *
icculus@11319
   486
 *  \return 0 on success or -1 if \c cvt->buf is NULL.
slouken@0
   487
 */
slouken@1895
   488
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
slouken@0
   489
slouken@11631
   490
/* SDL_AudioStream is a new audio conversion interface.
slouken@11631
   491
   The benefits vs SDL_AudioCVT:
slouken@11631
   492
    - it can handle resampling data in chunks without generating
slouken@11631
   493
      artifacts, when it doesn't have the complete buffer available.
slouken@11631
   494
    - it can handle incoming data in any variable size.
slouken@11631
   495
    - You push data as you have it, and pull it when you need it
slouken@11631
   496
 */
slouken@11631
   497
/* this is opaque to the outside world. */
slouken@11631
   498
struct _SDL_AudioStream;
slouken@11631
   499
typedef struct _SDL_AudioStream SDL_AudioStream;
slouken@11631
   500
slouken@11631
   501
/**
slouken@11631
   502
 *  Create a new audio stream
slouken@11631
   503
 *
slouken@11631
   504
 *  \param src_format The format of the source audio
slouken@11631
   505
 *  \param src_channels The number of channels of the source audio
slouken@11631
   506
 *  \param src_rate The sampling rate of the source audio
slouken@11631
   507
 *  \param dst_format The format of the desired audio output
slouken@11631
   508
 *  \param dst_channels The number of channels of the desired audio output
slouken@11631
   509
 *  \param dst_rate The sampling rate of the desired audio output
slouken@11631
   510
 *  \return 0 on success, or -1 on error.
slouken@11631
   511
 *
slouken@11631
   512
 *  \sa SDL_AudioStreamPut
slouken@11631
   513
 *  \sa SDL_AudioStreamGet
slouken@11631
   514
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   515
 *  \sa SDL_AudioStreamFlush
slouken@11631
   516
 *  \sa SDL_AudioStreamClear
slouken@11631
   517
 *  \sa SDL_FreeAudioStream
slouken@11631
   518
 */
slouken@11631
   519
extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
slouken@11631
   520
                                           const Uint8 src_channels,
slouken@11631
   521
                                           const int src_rate,
slouken@11631
   522
                                           const SDL_AudioFormat dst_format,
slouken@11631
   523
                                           const Uint8 dst_channels,
slouken@11631
   524
                                           const int dst_rate);
slouken@11631
   525
slouken@11631
   526
/**
slouken@11631
   527
 *  Add data to be converted/resampled to the stream
slouken@11631
   528
 *
slouken@11631
   529
 *  \param stream The stream the audio data is being added to
slouken@11631
   530
 *  \param buf A pointer to the audio data to add
icculus@11748
   531
 *  \param len The number of bytes to write to the stream
slouken@11631
   532
 *  \return 0 on success, or -1 on error.
slouken@11631
   533
 *
slouken@11631
   534
 *  \sa SDL_NewAudioStream
slouken@11631
   535
 *  \sa SDL_AudioStreamGet
slouken@11631
   536
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   537
 *  \sa SDL_AudioStreamFlush
slouken@11631
   538
 *  \sa SDL_AudioStreamClear
slouken@11631
   539
 *  \sa SDL_FreeAudioStream
slouken@11631
   540
 */
slouken@11631
   541
extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
slouken@11631
   542
slouken@11631
   543
/**
slouken@11631
   544
 *  Get converted/resampled data from the stream
slouken@11631
   545
 *
slouken@11631
   546
 *  \param stream The stream the audio is being requested from
slouken@11631
   547
 *  \param buf A buffer to fill with audio data
slouken@11631
   548
 *  \param len The maximum number of bytes to fill
slouken@11631
   549
 *  \return The number of bytes read from the stream, or -1 on error
slouken@11631
   550
 *
slouken@11631
   551
 *  \sa SDL_NewAudioStream
slouken@11631
   552
 *  \sa SDL_AudioStreamPut
slouken@11631
   553
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   554
 *  \sa SDL_AudioStreamFlush
slouken@11631
   555
 *  \sa SDL_AudioStreamClear
slouken@11631
   556
 *  \sa SDL_FreeAudioStream
slouken@11631
   557
 */
slouken@11631
   558
extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
slouken@11631
   559
slouken@11631
   560
/**
icculus@11636
   561
 * Get the number of converted/resampled bytes available. The stream may be
icculus@11636
   562
 *  buffering data behind the scenes until it has enough to resample
icculus@11636
   563
 *  correctly, so this number might be lower than what you expect, or even
icculus@11636
   564
 *  be zero. Add more data or flush the stream if you need the data now.
icculus@11636
   565
 *
icculus@11636
   566
 *  \sa SDL_NewAudioStream
icculus@11636
   567
 *  \sa SDL_AudioStreamPut
icculus@11636
   568
 *  \sa SDL_AudioStreamGet
slouken@11639
   569
 *  \sa SDL_AudioStreamFlush
icculus@11636
   570
 *  \sa SDL_AudioStreamClear
icculus@11636
   571
 *  \sa SDL_FreeAudioStream
icculus@11636
   572
 */
icculus@11636
   573
extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
icculus@11636
   574
icculus@11636
   575
/**
icculus@11636
   576
 * Tell the stream that you're done sending data, and anything being buffered
icculus@11636
   577
 *  should be converted/resampled and made available immediately.
icculus@11636
   578
 *
icculus@11636
   579
 * It is legal to add more data to a stream after flushing, but there will
icculus@11636
   580
 *  be audio gaps in the output. Generally this is intended to signal the
icculus@11636
   581
 *  end of input, so the complete output becomes available.
slouken@11631
   582
 *
slouken@11631
   583
 *  \sa SDL_NewAudioStream
slouken@11631
   584
 *  \sa SDL_AudioStreamPut
slouken@11631
   585
 *  \sa SDL_AudioStreamGet
slouken@11639
   586
 *  \sa SDL_AudioStreamAvailable
slouken@11631
   587
 *  \sa SDL_AudioStreamClear
slouken@11631
   588
 *  \sa SDL_FreeAudioStream
slouken@11631
   589
 */
icculus@11636
   590
extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
slouken@11631
   591
slouken@11631
   592
/**
slouken@11631
   593
 *  Clear any pending data in the stream without converting it
slouken@11631
   594
 *
slouken@11631
   595
 *  \sa SDL_NewAudioStream
slouken@11631
   596
 *  \sa SDL_AudioStreamPut
slouken@11631
   597
 *  \sa SDL_AudioStreamGet
slouken@11631
   598
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   599
 *  \sa SDL_AudioStreamFlush
slouken@11631
   600
 *  \sa SDL_FreeAudioStream
slouken@11631
   601
 */
slouken@11631
   602
extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
slouken@11631
   603
slouken@11631
   604
/**
slouken@11631
   605
 * Free an audio stream
slouken@11631
   606
 *
slouken@11631
   607
 *  \sa SDL_NewAudioStream
slouken@11631
   608
 *  \sa SDL_AudioStreamPut
slouken@11631
   609
 *  \sa SDL_AudioStreamGet
slouken@11631
   610
 *  \sa SDL_AudioStreamAvailable
slouken@11639
   611
 *  \sa SDL_AudioStreamFlush
slouken@11631
   612
 *  \sa SDL_AudioStreamClear
slouken@11631
   613
 */
slouken@11631
   614
extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
slouken@11631
   615
slouken@3407
   616
#define SDL_MIX_MAXVOLUME 128
slouken@3407
   617
/**
slouken@3407
   618
 *  This takes two audio buffers of the playing audio format and mixes
slouken@3407
   619
 *  them, performing addition, volume adjustment, and overflow clipping.
slouken@3407
   620
 *  The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
slouken@3407
   621
 *  for full audio volume.  Note this does not change hardware volume.
slouken@3407
   622
 *  This is provided for convenience -- you can mix your own audio data.
slouken@0
   623
 */
slouken@1895
   624
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
slouken@1895
   625
                                          Uint32 len, int volume);
slouken@0
   626
slouken@3407
   627
/**
slouken@3407
   628
 *  This works like SDL_MixAudio(), but you specify the audio format instead of
icculus@1964
   629
 *  using the format of audio device 1. Thus it can be used when no audio
icculus@1964
   630
 *  device is open at all.
icculus@1964
   631
 */
slouken@1967
   632
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
slouken@1967
   633
                                                const Uint8 * src,
icculus@1964
   634
                                                SDL_AudioFormat format,
icculus@1964
   635
                                                Uint32 len, int volume);
icculus@1964
   636
slouken@3407
   637
/**
icculus@9012
   638
 *  Queue more audio on non-callback devices.
icculus@9012
   639
 *
icculus@10262
   640
 *  (If you are looking to retrieve queued audio from a non-callback capture
icculus@10262
   641
 *  device, you want SDL_DequeueAudio() instead. This will return -1 to
icculus@10262
   642
 *  signify an error if you use it with capture devices.)
icculus@10262
   643
 *
icculus@9012
   644
 *  SDL offers two ways to feed audio to the device: you can either supply a
icculus@9012
   645
 *  callback that SDL triggers with some frequency to obtain more audio
icculus@9012
   646
 *  (pull method), or you can supply no callback, and then SDL will expect
icculus@9012
   647
 *  you to supply data at regular intervals (push method) with this function.
icculus@9012
   648
 *
icculus@9012
   649
 *  There are no limits on the amount of data you can queue, short of
icculus@9012
   650
 *  exhaustion of address space. Queued data will drain to the device as
icculus@9012
   651
 *  necessary without further intervention from you. If the device needs
icculus@9012
   652
 *  audio but there is not enough queued, it will play silence to make up
icculus@9012
   653
 *  the difference. This means you will have skips in your audio playback
icculus@9012
   654
 *  if you aren't routinely queueing sufficient data.
icculus@9012
   655
 *
icculus@9012
   656
 *  This function copies the supplied data, so you are safe to free it when
icculus@9012
   657
 *  the function returns. This function is thread-safe, but queueing to the
icculus@9012
   658
 *  same device from two threads at once does not promise which buffer will
icculus@9012
   659
 *  be queued first.
icculus@9012
   660
 *
icculus@9012
   661
 *  You may not queue audio on a device that is using an application-supplied
icculus@9012
   662
 *  callback; doing so returns an error. You have to use the audio callback
icculus@9012
   663
 *  or queue audio with this function, but not both.
icculus@9012
   664
 *
icculus@9012
   665
 *  You should not call SDL_LockAudio() on the device before queueing; SDL
icculus@9012
   666
 *  handles locking internally for this function.
icculus@9012
   667
 *
icculus@9012
   668
 *  \param dev The device ID to which we will queue audio.
icculus@9012
   669
 *  \param data The data to queue to the device for later playback.
icculus@9012
   670
 *  \param len The number of bytes (not samples!) to which (data) points.
slouken@11631
   671
 *  \return 0 on success, or -1 on error.
icculus@9012
   672
 *
icculus@9012
   673
 *  \sa SDL_GetQueuedAudioSize
icculus@9012
   674
 *  \sa SDL_ClearQueuedAudio
icculus@9012
   675
 */
icculus@9012
   676
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
icculus@9012
   677
icculus@9012
   678
/**
icculus@10262
   679
 *  Dequeue more audio on non-callback devices.
icculus@10262
   680
 *
icculus@10262
   681
 *  (If you are looking to queue audio for output on a non-callback playback
icculus@10262
   682
 *  device, you want SDL_QueueAudio() instead. This will always return 0
icculus@10262
   683
 *  if you use it with playback devices.)
icculus@10262
   684
 *
icculus@10262
   685
 *  SDL offers two ways to retrieve audio from a capture device: you can
icculus@10262
   686
 *  either supply a callback that SDL triggers with some frequency as the
icculus@10262
   687
 *  device records more audio data, (push method), or you can supply no
icculus@10262
   688
 *  callback, and then SDL will expect you to retrieve data at regular
icculus@10262
   689
 *  intervals (pull method) with this function.
icculus@10262
   690
 *
icculus@10262
   691
 *  There are no limits on the amount of data you can queue, short of
icculus@10262
   692
 *  exhaustion of address space. Data from the device will keep queuing as
icculus@10262
   693
 *  necessary without further intervention from you. This means you will
icculus@10262
   694
 *  eventually run out of memory if you aren't routinely dequeueing data.
icculus@10262
   695
 *
icculus@10262
   696
 *  Capture devices will not queue data when paused; if you are expecting
icculus@10262
   697
 *  to not need captured audio for some length of time, use
icculus@10262
   698
 *  SDL_PauseAudioDevice() to stop the capture device from queueing more
icculus@10262
   699
 *  data. This can be useful during, say, level loading times. When
icculus@10262
   700
 *  unpaused, capture devices will start queueing data from that point,
icculus@10262
   701
 *  having flushed any capturable data available while paused.
icculus@10262
   702
 *
icculus@10262
   703
 *  This function is thread-safe, but dequeueing from the same device from
icculus@10262
   704
 *  two threads at once does not promise which thread will dequeued data
icculus@10262
   705
 *  first.
icculus@10262
   706
 *
icculus@10262
   707
 *  You may not dequeue audio from a device that is using an
icculus@10262
   708
 *  application-supplied callback; doing so returns an error. You have to use
icculus@10262
   709
 *  the audio callback, or dequeue audio with this function, but not both.
icculus@10262
   710
 *
icculus@10262
   711
 *  You should not call SDL_LockAudio() on the device before queueing; SDL
icculus@10262
   712
 *  handles locking internally for this function.
icculus@10262
   713
 *
icculus@10262
   714
 *  \param dev The device ID from which we will dequeue audio.
icculus@10262
   715
 *  \param data A pointer into where audio data should be copied.
icculus@10262
   716
 *  \param len The number of bytes (not samples!) to which (data) points.
icculus@10262
   717
 *  \return number of bytes dequeued, which could be less than requested.
icculus@10262
   718
 *
icculus@10262
   719
 *  \sa SDL_GetQueuedAudioSize
icculus@10262
   720
 *  \sa SDL_ClearQueuedAudio
icculus@10262
   721
 */
icculus@10262
   722
extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
icculus@10262
   723
icculus@10262
   724
/**
icculus@9012
   725
 *  Get the number of bytes of still-queued audio.
icculus@9012
   726
 *
icculus@10262
   727
 *  For playback device:
icculus@9012
   728
 *
icculus@10262
   729
 *    This is the number of bytes that have been queued for playback with
icculus@10262
   730
 *    SDL_QueueAudio(), but have not yet been sent to the hardware. This
icculus@10262
   731
 *    number may shrink at any time, so this only informs of pending data.
icculus@10262
   732
 *
icculus@10262
   733
 *    Once we've sent it to the hardware, this function can not decide the
icculus@10262
   734
 *    exact byte boundary of what has been played. It's possible that we just
icculus@10262
   735
 *    gave the hardware several kilobytes right before you called this
icculus@10262
   736
 *    function, but it hasn't played any of it yet, or maybe half of it, etc.
icculus@10262
   737
 *
icculus@10262
   738
 *  For capture devices:
icculus@10262
   739
 *
icculus@10262
   740
 *    This is the number of bytes that have been captured by the device and
icculus@10262
   741
 *    are waiting for you to dequeue. This number may grow at any time, so
icculus@10262
   742
 *    this only informs of the lower-bound of available data.
icculus@9012
   743
 *
icculus@9012
   744
 *  You may not queue audio on a device that is using an application-supplied
icculus@9012
   745
 *  callback; calling this function on such a device always returns 0.
icculus@10262
   746
 *  You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
icculus@10262
   747
 *  the audio callback, but not both.
icculus@9012
   748
 *
icculus@9012
   749
 *  You should not call SDL_LockAudio() on the device before querying; SDL
icculus@9012
   750
 *  handles locking internally for this function.
icculus@9012
   751
 *
icculus@9012
   752
 *  \param dev The device ID of which we will query queued audio size.
icculus@9012
   753
 *  \return Number of bytes (not samples!) of queued audio.
icculus@9012
   754
 *
icculus@9012
   755
 *  \sa SDL_QueueAudio
icculus@9012
   756
 *  \sa SDL_ClearQueuedAudio
icculus@9012
   757
 */
icculus@9012
   758
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
icculus@9012
   759
icculus@9012
   760
/**
icculus@10262
   761
 *  Drop any queued audio data. For playback devices, this is any queued data
icculus@10262
   762
 *  still waiting to be submitted to the hardware. For capture devices, this
icculus@10262
   763
 *  is any data that was queued by the device that hasn't yet been dequeued by
icculus@10262
   764
 *  the application.
icculus@9012
   765
 *
icculus@10262
   766
 *  Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
icculus@10262
   767
 *  playback devices, the hardware will start playing silence if more audio
icculus@10262
   768
 *  isn't queued. Unpaused capture devices will start filling the queue again
icculus@10262
   769
 *  as soon as they have more data available (which, depending on the state
icculus@10262
   770
 *  of the hardware and the thread, could be before this function call
icculus@10262
   771
 *  returns!).
icculus@9012
   772
 *
icculus@9012
   773
 *  This will not prevent playback of queued audio that's already been sent
icculus@9012
   774
 *  to the hardware, as we can not undo that, so expect there to be some
icculus@9012
   775
 *  fraction of a second of audio that might still be heard. This can be
icculus@9012
   776
 *  useful if you want to, say, drop any pending music during a level change
icculus@9012
   777
 *  in your game.
icculus@9012
   778
 *
icculus@9012
   779
 *  You may not queue audio on a device that is using an application-supplied
icculus@9012
   780
 *  callback; calling this function on such a device is always a no-op.
icculus@10262
   781
 *  You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
icculus@10262
   782
 *  the audio callback, but not both.
icculus@9012
   783
 *
icculus@9012
   784
 *  You should not call SDL_LockAudio() on the device before clearing the
icculus@9012
   785
 *  queue; SDL handles locking internally for this function.
icculus@9012
   786
 *
icculus@9012
   787
 *  This function always succeeds and thus returns void.
icculus@9012
   788
 *
icculus@9012
   789
 *  \param dev The device ID of which to clear the audio queue.
icculus@9012
   790
 *
icculus@9012
   791
 *  \sa SDL_QueueAudio
icculus@9012
   792
 *  \sa SDL_GetQueuedAudioSize
icculus@9012
   793
 */
icculus@9012
   794
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
icculus@9012
   795
icculus@9012
   796
icculus@9012
   797
/**
slouken@3407
   798
 *  \name Audio lock functions
slouken@7191
   799
 *
slouken@3407
   800
 *  The lock manipulated by these functions protects the callback function.
slouken@7191
   801
 *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
slouken@3407
   802
 *  the callback function is not running.  Do not call these from the callback
slouken@3407
   803
 *  function or you will cause deadlock.
slouken@0
   804
 */
gabomdq@7678
   805
/* @{ */
slouken@337
   806
extern DECLSPEC void SDLCALL SDL_LockAudio(void);
icculus@1964
   807
extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
slouken@337
   808
extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
icculus@1964
   809
extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
gabomdq@7678
   810
/* @} *//* Audio lock functions */
slouken@0
   811
slouken@3407
   812
/**
slouken@3407
   813
 *  This function shuts down audio processing and closes the audio device.
slouken@0
   814
 */
slouken@337
   815
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
icculus@1964
   816
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
icculus@1964
   817
slouken@0
   818
/* Ends C function definitions when using C++ */
slouken@0
   819
#ifdef __cplusplus
slouken@0
   820
}
slouken@0
   821
#endif
slouken@0
   822
#include "close_code.h"
slouken@0
   823
slouken@10638
   824
#endif /* SDL_audio_h_ */
slouken@1895
   825
slouken@1895
   826
/* vi: set ts=4 sw=4 expandtab: */