slouken@0: /* slouken@5535: Simple DirectMedia Layer slouken@12503: Copyright (C) 1997-2019 Sam Lantinga slouken@0: slouken@5535: This software is provided 'as-is', without any express or implied slouken@5535: warranty. In no event will the authors be held liable for any damages slouken@5535: arising from the use of this software. slouken@0: slouken@5535: Permission is granted to anyone to use this software for any purpose, slouken@5535: including commercial applications, and to alter it and redistribute it slouken@5535: freely, subject to the following restrictions: slouken@0: slouken@5535: 1. The origin of this software must not be misrepresented; you must not slouken@5535: claim that you wrote the original software. If you use this software slouken@5535: in a product, an acknowledgment in the product documentation would be slouken@5535: appreciated but is not required. slouken@5535: 2. Altered source versions must be plainly marked as such, and must not be slouken@5535: misrepresented as being the original software. slouken@5535: 3. This notice may not be removed or altered from any source distribution. slouken@0: */ slouken@0: slouken@1895: /** slouken@3407: * \file SDL_audio.h slouken@7191: * slouken@3407: * Access to the raw audio mixing buffer for the SDL library. slouken@1895: */ slouken@0: slouken@10638: #ifndef SDL_audio_h_ slouken@10638: #define SDL_audio_h_ slouken@0: slouken@1353: #include "SDL_stdinc.h" slouken@0: #include "SDL_error.h" slouken@1358: #include "SDL_endian.h" slouken@1358: #include "SDL_mutex.h" slouken@1358: #include "SDL_thread.h" slouken@0: #include "SDL_rwops.h" slouken@0: slouken@0: #include "begin_code.h" slouken@0: /* Set up for C function definitions, even when using C++ */ slouken@0: #ifdef __cplusplus slouken@0: extern "C" { slouken@0: #endif slouken@0: slouken@3407: /** slouken@3407: * \brief Audio format flags. slouken@7191: * slouken@3407: * These are what the 16 bits in SDL_AudioFormat currently mean... slouken@3407: * (Unspecified bits are always zero). slouken@7191: * slouken@3407: * \verbatim slouken@3407: ++-----------------------sample is signed if set slouken@3407: || slouken@3407: || ++-----------sample is bigendian if set slouken@3407: || || slouken@3407: || || ++---sample is float if set slouken@3407: || || || slouken@3407: || || || +---sample bit size---+ slouken@3407: || || || | | slouken@3407: 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 slouken@3407: \endverbatim slouken@7191: * slouken@6251: * There are macros in SDL 2.0 and later to query these bits. slouken@3407: */ icculus@1964: typedef Uint16 SDL_AudioFormat; icculus@1964: slouken@3407: /** slouken@3407: * \name Audio flags slouken@3407: */ gabomdq@7678: /* @{ */ icculus@1964: icculus@1964: #define SDL_AUDIO_MASK_BITSIZE (0xFF) icculus@1964: #define SDL_AUDIO_MASK_DATATYPE (1<<8) icculus@1964: #define SDL_AUDIO_MASK_ENDIAN (1<<12) icculus@1964: #define SDL_AUDIO_MASK_SIGNED (1<<15) icculus@1964: #define SDL_AUDIO_BITSIZE(x) (x & SDL_AUDIO_MASK_BITSIZE) icculus@1964: #define SDL_AUDIO_ISFLOAT(x) (x & SDL_AUDIO_MASK_DATATYPE) icculus@1964: #define SDL_AUDIO_ISBIGENDIAN(x) (x & SDL_AUDIO_MASK_ENDIAN) icculus@1964: #define SDL_AUDIO_ISSIGNED(x) (x & SDL_AUDIO_MASK_SIGNED) icculus@1964: #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) icculus@1964: #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) icculus@1964: #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) icculus@1964: slouken@7191: /** slouken@3407: * \name Audio format flags slouken@3407: * slouken@3407: * Defaults to LSB byte order. slouken@3407: */ gabomdq@7678: /* @{ */ slouken@7191: #define AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */ slouken@7191: #define AUDIO_S8 0x8008 /**< Signed 8-bit samples */ slouken@7191: #define AUDIO_U16LSB 0x0010 /**< Unsigned 16-bit samples */ slouken@7191: #define AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */ slouken@7191: #define AUDIO_U16MSB 0x1010 /**< As above, but big-endian byte order */ slouken@7191: #define AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */ slouken@7191: #define AUDIO_U16 AUDIO_U16LSB slouken@7191: #define AUDIO_S16 AUDIO_S16LSB gabomdq@7678: /* @} */ slouken@0: slouken@3407: /** slouken@3407: * \name int32 support slouken@3407: */ gabomdq@7678: /* @{ */ slouken@7191: #define AUDIO_S32LSB 0x8020 /**< 32-bit integer samples */ slouken@7191: #define AUDIO_S32MSB 0x9020 /**< As above, but big-endian byte order */ slouken@7191: #define AUDIO_S32 AUDIO_S32LSB gabomdq@7678: /* @} */ icculus@1964: slouken@3407: /** slouken@3407: * \name float32 support slouken@3407: */ gabomdq@7678: /* @{ */ slouken@7191: #define AUDIO_F32LSB 0x8120 /**< 32-bit floating point samples */ slouken@7191: #define AUDIO_F32MSB 0x9120 /**< As above, but big-endian byte order */ slouken@7191: #define AUDIO_F32 AUDIO_F32LSB gabomdq@7678: /* @} */ icculus@1964: slouken@3407: /** slouken@3407: * \name Native audio byte ordering slouken@3407: */ gabomdq@7678: /* @{ */ slouken@0: #if SDL_BYTEORDER == SDL_LIL_ENDIAN slouken@7191: #define AUDIO_U16SYS AUDIO_U16LSB slouken@7191: #define AUDIO_S16SYS AUDIO_S16LSB slouken@7191: #define AUDIO_S32SYS AUDIO_S32LSB slouken@7191: #define AUDIO_F32SYS AUDIO_F32LSB slouken@0: #else slouken@7191: #define AUDIO_U16SYS AUDIO_U16MSB slouken@7191: #define AUDIO_S16SYS AUDIO_S16MSB slouken@7191: #define AUDIO_S32SYS AUDIO_S32MSB slouken@7191: #define AUDIO_F32SYS AUDIO_F32MSB slouken@0: #endif gabomdq@7678: /* @} */ slouken@0: slouken@7191: /** slouken@3407: * \name Allow change flags slouken@7191: * slouken@3407: * Which audio format changes are allowed when opening a device. slouken@3407: */ gabomdq@7678: /* @{ */ slouken@2866: #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001 slouken@2866: #define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002 slouken@2866: #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004 slouken@12272: #define SDL_AUDIO_ALLOW_SAMPLES_CHANGE 0x00000008 slouken@12272: #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: /* @} */ slouken@0: gabomdq@7678: /* @} *//* Audio flags */ slouken@3407: slouken@3407: /** slouken@3554: * This function is called when the audio device needs more data. slouken@3554: * slouken@3554: * \param userdata An application-specific parameter saved in slouken@3554: * the SDL_AudioSpec structure slouken@3554: * \param stream A pointer to the audio data buffer. slouken@3554: * \param len The length of that buffer in bytes. slouken@3554: * slouken@3554: * Once the callback returns, the buffer will no longer be valid. slouken@3554: * Stereo samples are stored in a LRLRLR ordering. icculus@9012: * icculus@9012: * You can choose to avoid callbacks and use SDL_QueueAudio() instead, if icculus@9012: * you like. Just open your audio device with a NULL callback. slouken@3554: */ slouken@3554: typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, slouken@3554: int len); slouken@3554: slouken@3554: /** slouken@3407: * The calculated values in this structure are calculated by SDL_OpenAudio(). slouken@11640: * slouken@11640: * For multi-channel audio, the default SDL channel mapping is: slouken@11640: * 2: FL FR (stereo) slouken@11640: * 3: FL FR LFE (2.1 surround) slouken@11640: * 4: FL FR BL BR (quad) slouken@11640: * 5: FL FR FC BL BR (quad + center) slouken@11640: * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) slouken@11640: * 7: FL FR FC LFE BC SL SR (6.1 surround) slouken@11640: * 8: FL FR FC LFE BL BR SL SR (7.1 surround) slouken@3407: */ slouken@3407: typedef struct SDL_AudioSpec slouken@3407: { slouken@3407: int freq; /**< DSP frequency -- samples per second */ slouken@3407: SDL_AudioFormat format; /**< Audio data format */ slouken@3407: Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ slouken@3407: Uint8 silence; /**< Audio buffer silence value (calculated) */ icculus@10920: Uint16 samples; /**< Audio buffer size in sample FRAMES (total samples divided by channel count) */ slouken@3407: Uint16 padding; /**< Necessary for some compile environments */ slouken@3407: Uint32 size; /**< Audio buffer size in bytes (calculated) */ icculus@9012: SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */ icculus@9012: void *userdata; /**< Userdata passed to callback (ignored for NULL callbacks). */ slouken@3407: } SDL_AudioSpec; slouken@3407: slouken@3407: icculus@1983: struct SDL_AudioCVT; slouken@1985: typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, slouken@1985: SDL_AudioFormat format); icculus@1983: slouken@3407: /** slouken@11096: * \brief Upper limit of filters in SDL_AudioCVT slouken@11096: * slouken@11096: * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is slouken@11096: * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, slouken@11096: * one of which is the terminating NULL pointer. slouken@11096: */ slouken@11096: #define SDL_AUDIOCVT_MAX_FILTERS 9 slouken@11096: slouken@11096: /** slouken@11096: * \struct SDL_AudioCVT slouken@11096: * \brief A structure to hold a set of audio conversion filters and buffers. icculus@10845: * icculus@10845: * Note that various parts of the conversion pipeline can take advantage icculus@10845: * of SIMD operations (like SSE2, for example). SDL_AudioCVT doesn't require icculus@10845: * you to pass it aligned data, but can possibly run much faster if you icculus@10845: * set both its (buf) field to a pointer that is aligned to 16 bytes, and its icculus@10845: * (len) field to something that's a multiple of 16, if possible. slouken@3407: */ slouken@7546: #ifdef __GNUC__ slouken@7546: /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't slouken@7546: pad it out to 88 bytes to guarantee ABI compatibility between compilers. slouken@7546: vvv slouken@7546: The next time we rev the ABI, make sure to size the ints and add padding. slouken@7546: */ slouken@7546: #define SDL_AUDIOCVT_PACKED __attribute__((packed)) slouken@7546: #else slouken@7546: #define SDL_AUDIOCVT_PACKED slouken@7546: #endif slouken@7546: /* */ slouken@1895: typedef struct SDL_AudioCVT slouken@1895: { slouken@3407: int needed; /**< Set to 1 if conversion possible */ slouken@3407: SDL_AudioFormat src_format; /**< Source audio format */ slouken@3407: SDL_AudioFormat dst_format; /**< Target audio format */ slouken@3407: double rate_incr; /**< Rate conversion increment */ slouken@3407: Uint8 *buf; /**< Buffer to hold entire audio data */ slouken@3407: int len; /**< Length of original audio buffer */ slouken@3407: int len_cvt; /**< Length of converted audio buffer */ slouken@3407: int len_mult; /**< buffer must be len*len_mult big */ slouken@3407: double len_ratio; /**< Given len, final size is len*len_ratio */ slouken@11096: SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1]; /**< NULL-terminated list of filter functions */ slouken@3407: int filter_index; /**< Current audio conversion function */ slouken@7546: } SDL_AUDIOCVT_PACKED SDL_AudioCVT; slouken@0: slouken@0: slouken@0: /* Function prototypes */ slouken@0: slouken@3407: /** slouken@3407: * \name Driver discovery functions slouken@7191: * slouken@3407: * These functions return the list of built in audio drivers, in the slouken@3407: * order that they are normally initialized by default. slouken@1895: */ gabomdq@7678: /* @{ */ slouken@1895: extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); slouken@1895: extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); gabomdq@7678: /* @} */ slouken@1895: slouken@3407: /** slouken@3407: * \name Initialization and cleanup slouken@7191: * slouken@3407: * \internal These functions are used internally, and should not be used unless slouken@7191: * you have a specific need to specify the audio driver you want to slouken@3407: * use. You should normally use SDL_Init() or SDL_InitSubSystem(). slouken@0: */ gabomdq@7678: /* @{ */ slouken@337: extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); slouken@337: extern DECLSPEC void SDLCALL SDL_AudioQuit(void); gabomdq@7678: /* @} */ slouken@0: slouken@3407: /** slouken@3407: * This function returns the name of the current audio driver, or NULL slouken@3407: * if no driver has been initialized. slouken@0: */ slouken@1895: extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); slouken@0: slouken@3407: /** slouken@3407: * This function opens the audio device with the desired parameters, and slouken@3407: * returns 0 if successful, placing the actual hardware parameters in the slouken@3407: * structure pointed to by \c obtained. If \c obtained is NULL, the audio slouken@3407: * data passed to the callback function will be guaranteed to be in the slouken@3407: * requested format, and will be automatically converted to the hardware slouken@7191: * audio format if necessary. This function returns -1 if it failed slouken@3407: * to open the audio device, or couldn't set up the audio thread. slouken@7191: * slouken@3407: * When filling in the desired audio spec structure, slouken@3407: * - \c desired->freq should be the desired audio frequency in samples-per- slouken@3407: * second. slouken@3407: * - \c desired->format should be the desired audio format. slouken@7191: * - \c desired->samples is the desired size of the audio buffer, in slouken@7191: * samples. This number should be a power of two, and may be adjusted by slouken@3407: * the audio driver to a value more suitable for the hardware. Good values slouken@7191: * seem to range between 512 and 8096 inclusive, depending on the slouken@7191: * application and CPU speed. Smaller values yield faster response time, slouken@7191: * but can lead to underflow if the application is doing heavy processing slouken@7191: * and cannot fill the audio buffer in time. A stereo sample consists of slouken@3407: * both right and left channels in LR ordering. slouken@3407: * Note that the number of samples is directly related to time by the slouken@3407: * following formula: \code ms = (samples*1000)/freq \endcode slouken@3407: * - \c desired->size is the size in bytes of the audio buffer, and is slouken@3407: * calculated by SDL_OpenAudio(). slouken@3407: * - \c desired->silence is the value used to set the buffer to silence, slouken@3407: * and is calculated by SDL_OpenAudio(). slouken@3407: * - \c desired->callback should be set to a function that will be called slouken@3407: * when the audio device is ready for more data. It is passed a pointer slouken@3407: * to the audio buffer, and the length in bytes of the audio buffer. slouken@3407: * This function usually runs in a separate thread, and so you should slouken@3407: * protect data structures that it accesses by calling SDL_LockAudio() icculus@9012: * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL icculus@9012: * pointer here, and call SDL_QueueAudio() with some frequency, to queue icculus@10262: * more audio samples to be played (or for capture devices, call icculus@10262: * SDL_DequeueAudio() with some frequency, to obtain audio samples). slouken@3407: * - \c desired->userdata is passed as the first parameter to your callback icculus@9012: * function. If you passed a NULL callback, this value is ignored. slouken@7191: * slouken@3407: * The audio device starts out playing silence when it's opened, and should slouken@3407: * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready slouken@3407: * for your audio callback function to be called. Since the audio driver slouken@3407: * may modify the requested size of the audio buffer, you should allocate slouken@3407: * any local mixing buffers after you open the audio device. slouken@0: */ slouken@2866: extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired, slouken@1895: SDL_AudioSpec * obtained); slouken@0: slouken@3407: /** slouken@3407: * SDL Audio Device IDs. slouken@7191: * slouken@3407: * A successful call to SDL_OpenAudio() is always device id 1, and legacy icculus@1964: * SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls icculus@1964: * always returns devices >= 2 on success. The legacy calls are good both icculus@1964: * for backwards compatibility and when you don't care about multiple, icculus@1964: * specific, or capture devices. icculus@1964: */ icculus@1964: typedef Uint32 SDL_AudioDeviceID; icculus@1964: slouken@3407: /** slouken@3407: * Get the number of available devices exposed by the current driver. icculus@1964: * Only valid after a successfully initializing the audio subsystem. icculus@2049: * Returns -1 if an explicit list of devices can't be determined; this is icculus@2049: * not an error. For example, if SDL is set up to talk to a remote audio icculus@2049: * server, it can't list every one available on the Internet, but it will icculus@2049: * still allow a specific host to be specified to SDL_OpenAudioDevice(). slouken@7191: * slouken@3407: * In many common cases, when this function returns a value <= 0, it can still icculus@2049: * successfully open the default device (NULL for first argument of icculus@2049: * SDL_OpenAudioDevice()). icculus@1964: */ icculus@1964: extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); icculus@1964: slouken@3407: /** slouken@3407: * Get the human-readable name of a specific audio device. icculus@1964: * Must be a value between 0 and (number of audio devices-1). icculus@1964: * Only valid after a successfully initializing the audio subsystem. icculus@2049: * The values returned by this function reflect the latest call to icculus@2049: * SDL_GetNumAudioDevices(); recall that function to redetect available icculus@2049: * hardware. slouken@7191: * slouken@3407: * The string returned by this function is UTF-8 encoded, read-only, and icculus@2049: * managed internally. You are not to free it. If you need to keep the icculus@2049: * string for any length of time, you should make your own copy of it, as it icculus@2049: * will be invalid next time any of several other SDL functions is called. icculus@1964: */ icculus@2049: extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, icculus@2049: int iscapture); icculus@1964: icculus@1964: slouken@3407: /** slouken@3407: * Open a specific audio device. Passing in a device name of NULL requests icculus@2049: * the most reasonable default (and is equivalent to calling SDL_OpenAudio()). slouken@7191: * slouken@3407: * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but icculus@2049: * some drivers allow arbitrary and driver-specific strings, such as a icculus@2049: * hostname/IP address for a remote audio server, or a filename in the icculus@2049: * diskaudio driver. slouken@7191: * slouken@3407: * \return 0 on error, a valid device ID that is >= 2 on success. slouken@7191: * icculus@2049: * SDL_OpenAudio(), unlike this function, always acts on device ID 1. icculus@1964: */ slouken@1967: extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char slouken@1967: *device, slouken@1967: int iscapture, slouken@1967: const slouken@1967: SDL_AudioSpec * slouken@1967: desired, slouken@1967: SDL_AudioSpec * slouken@2866: obtained, slouken@2866: int slouken@2866: allowed_changes); icculus@1964: icculus@1964: icculus@1964: slouken@3407: /** slouken@3407: * \name Audio state slouken@7191: * slouken@3407: * Get the current audio state. slouken@0: */ gabomdq@7678: /* @{ */ slouken@1895: typedef enum slouken@1895: { slouken@1895: SDL_AUDIO_STOPPED = 0, slouken@1895: SDL_AUDIO_PLAYING, slouken@1895: SDL_AUDIO_PAUSED slouken@3537: } SDL_AudioStatus; slouken@3537: extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); slouken@0: slouken@3537: extern DECLSPEC SDL_AudioStatus SDLCALL slouken@1967: SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev); gabomdq@7678: /* @} *//* Audio State */ icculus@1964: slouken@3407: /** slouken@3407: * \name Pause audio functions slouken@7191: * slouken@3407: * These functions pause and unpause the audio callback processing. slouken@3407: * They should be called with a parameter of 0 after opening the audio slouken@3407: * device to start playing sound. This is so you can safely initialize slouken@3407: * data for your callback function after opening the audio device. slouken@3407: * Silence will be written to the audio device during the pause. slouken@0: */ gabomdq@7678: /* @{ */ slouken@337: extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); icculus@1964: extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, icculus@1964: int pause_on); gabomdq@7678: /* @} *//* Pause audio functions */ slouken@0: slouken@3407: /** slouken@12806: * \brief Load the audio data of a WAVE file into memory slouken@12806: * slouken@12806: * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len slouken@12806: * to be valid pointers. The entire data portion of the file is then loaded slouken@12806: * into memory and decoded if necessary. slouken@12806: * slouken@12806: * If \c freesrc is non-zero, the data source gets automatically closed and slouken@12806: * freed before the function returns. slouken@12806: * slouken@12806: * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits), slouken@12806: * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and slouken@12806: * ยต-law (8 bits). Other formats are currently unsupported and cause an error. slouken@12806: * slouken@12806: * If this function succeeds, the pointer returned by it is equal to \c spec slouken@12806: * and the pointer to the audio data allocated by the function is written to slouken@12806: * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec slouken@12806: * members \c freq, \c channels, and \c format are set to the values of the slouken@12806: * audio data in the buffer. The \c samples member is set to a sane default and slouken@12806: * all others are set to zero. slouken@12806: * slouken@12806: * It's necessary to use SDL_FreeWAV() to free the audio data returned in slouken@12806: * \c audio_buf when it is no longer used. slouken@12806: * slouken@12806: * Because of the underspecification of the Waveform format, there are many slouken@12806: * problematic files in the wild that cause issues with strict decoders. To slouken@12806: * provide compatibility with these files, this decoder is lenient in regards slouken@12806: * to the truncation of the file, the fact chunk, and the size of the RIFF slouken@12806: * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION, slouken@12806: * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the slouken@12806: * loading process. slouken@12806: * slouken@12806: * Any file that is invalid (due to truncation, corruption, or wrong values in slouken@12806: * the headers), too big, or unsupported causes an error. Additionally, any slouken@12806: * critical I/O error from the data source will terminate the loading process slouken@12806: * with an error. The function returns NULL on error and in all cases (with the slouken@12806: * exception of \c src being NULL), an appropriate error message will be set. slouken@12806: * slouken@12806: * It is required that the data source supports seeking. slouken@12806: * slouken@12806: * Example: slouken@3407: * \code slouken@7191: * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); slouken@3407: * \endcode slouken@0: * slouken@12806: * \param src The data source with the WAVE data slouken@12806: * \param freesrc A integer value that makes the function close the data source if non-zero slouken@12806: * \param spec A pointer filled with the audio format of the audio data slouken@12806: * \param audio_buf A pointer filled with the audio data allocated by the function slouken@12806: * \param audio_len A pointer filled with the length of the audio data buffer in bytes slouken@12806: * \return NULL on error, or non-NULL on success. slouken@0: */ slouken@1895: extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, slouken@1895: int freesrc, slouken@1895: SDL_AudioSpec * spec, slouken@1895: Uint8 ** audio_buf, slouken@1895: Uint32 * audio_len); slouken@0: slouken@7191: /** slouken@3407: * Loads a WAV from a file. slouken@3407: * Compatibility convenience function. slouken@3407: */ slouken@0: #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ slouken@7191: SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) slouken@0: slouken@3407: /** slouken@3407: * This function frees data previously allocated with SDL_LoadWAV_RW() slouken@0: */ slouken@1895: extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); slouken@0: slouken@3407: /** slouken@3407: * This function takes a source format and rate and a destination format slouken@3407: * and rate, and initializes the \c cvt structure with information needed slouken@3407: * by SDL_ConvertAudio() to convert a buffer of audio data from one format icculus@11319: * to the other. An unsupported format causes an error and -1 will be returned. slouken@7191: * icculus@11319: * \return 0 if no conversion is needed, 1 if the audio filter is set up, icculus@11319: * or -1 on error. slouken@0: */ slouken@1895: extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, icculus@1983: SDL_AudioFormat src_format, slouken@1895: Uint8 src_channels, slouken@1895: int src_rate, icculus@1983: SDL_AudioFormat dst_format, slouken@1895: Uint8 dst_channels, slouken@1895: int dst_rate); slouken@0: slouken@3407: /** slouken@3407: * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(), slouken@3407: * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of slouken@3407: * audio data in the source format, this function will convert it in-place slouken@3407: * to the desired format. slouken@7191: * slouken@3407: * The data conversion may expand the size of the audio data, so the buffer slouken@3407: * \c cvt->buf should be allocated after the \c cvt structure is initialized by slouken@3407: * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long. icculus@11319: * icculus@11319: * \return 0 on success or -1 if \c cvt->buf is NULL. slouken@0: */ slouken@1895: extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt); slouken@0: slouken@11631: /* SDL_AudioStream is a new audio conversion interface. slouken@11631: The benefits vs SDL_AudioCVT: slouken@11631: - it can handle resampling data in chunks without generating slouken@11631: artifacts, when it doesn't have the complete buffer available. slouken@11631: - it can handle incoming data in any variable size. slouken@11631: - You push data as you have it, and pull it when you need it slouken@11631: */ slouken@11631: /* this is opaque to the outside world. */ slouken@11631: struct _SDL_AudioStream; slouken@11631: typedef struct _SDL_AudioStream SDL_AudioStream; slouken@11631: slouken@11631: /** slouken@11631: * Create a new audio stream slouken@11631: * slouken@11631: * \param src_format The format of the source audio slouken@11631: * \param src_channels The number of channels of the source audio slouken@11631: * \param src_rate The sampling rate of the source audio slouken@11631: * \param dst_format The format of the desired audio output slouken@11631: * \param dst_channels The number of channels of the desired audio output slouken@11631: * \param dst_rate The sampling rate of the desired audio output slouken@11631: * \return 0 on success, or -1 on error. slouken@11631: * slouken@11631: * \sa SDL_AudioStreamPut slouken@11631: * \sa SDL_AudioStreamGet slouken@11631: * \sa SDL_AudioStreamAvailable slouken@11639: * \sa SDL_AudioStreamFlush slouken@11631: * \sa SDL_AudioStreamClear slouken@11631: * \sa SDL_FreeAudioStream slouken@11631: */ slouken@11631: extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, slouken@11631: const Uint8 src_channels, slouken@11631: const int src_rate, slouken@11631: const SDL_AudioFormat dst_format, slouken@11631: const Uint8 dst_channels, slouken@11631: const int dst_rate); slouken@11631: slouken@11631: /** slouken@11631: * Add data to be converted/resampled to the stream slouken@11631: * slouken@11631: * \param stream The stream the audio data is being added to slouken@11631: * \param buf A pointer to the audio data to add icculus@11748: * \param len The number of bytes to write to the stream slouken@11631: * \return 0 on success, or -1 on error. slouken@11631: * slouken@11631: * \sa SDL_NewAudioStream slouken@11631: * \sa SDL_AudioStreamGet slouken@11631: * \sa SDL_AudioStreamAvailable slouken@11639: * \sa SDL_AudioStreamFlush slouken@11631: * \sa SDL_AudioStreamClear slouken@11631: * \sa SDL_FreeAudioStream slouken@11631: */ slouken@11631: extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len); slouken@11631: slouken@11631: /** slouken@11631: * Get converted/resampled data from the stream slouken@11631: * slouken@11631: * \param stream The stream the audio is being requested from slouken@11631: * \param buf A buffer to fill with audio data slouken@11631: * \param len The maximum number of bytes to fill slouken@11631: * \return The number of bytes read from the stream, or -1 on error slouken@11631: * slouken@11631: * \sa SDL_NewAudioStream slouken@11631: * \sa SDL_AudioStreamPut slouken@11631: * \sa SDL_AudioStreamAvailable slouken@11639: * \sa SDL_AudioStreamFlush slouken@11631: * \sa SDL_AudioStreamClear slouken@11631: * \sa SDL_FreeAudioStream slouken@11631: */ slouken@11631: extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len); slouken@11631: slouken@11631: /** icculus@11636: * Get the number of converted/resampled bytes available. The stream may be icculus@11636: * buffering data behind the scenes until it has enough to resample icculus@11636: * correctly, so this number might be lower than what you expect, or even icculus@11636: * be zero. Add more data or flush the stream if you need the data now. icculus@11636: * icculus@11636: * \sa SDL_NewAudioStream icculus@11636: * \sa SDL_AudioStreamPut icculus@11636: * \sa SDL_AudioStreamGet slouken@11639: * \sa SDL_AudioStreamFlush icculus@11636: * \sa SDL_AudioStreamClear icculus@11636: * \sa SDL_FreeAudioStream icculus@11636: */ icculus@11636: extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream); icculus@11636: icculus@11636: /** icculus@11636: * Tell the stream that you're done sending data, and anything being buffered icculus@11636: * should be converted/resampled and made available immediately. icculus@11636: * icculus@11636: * It is legal to add more data to a stream after flushing, but there will icculus@11636: * be audio gaps in the output. Generally this is intended to signal the icculus@11636: * end of input, so the complete output becomes available. slouken@11631: * slouken@11631: * \sa SDL_NewAudioStream slouken@11631: * \sa SDL_AudioStreamPut slouken@11631: * \sa SDL_AudioStreamGet slouken@11639: * \sa SDL_AudioStreamAvailable slouken@11631: * \sa SDL_AudioStreamClear slouken@11631: * \sa SDL_FreeAudioStream slouken@11631: */ icculus@11636: extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream); slouken@11631: slouken@11631: /** slouken@11631: * Clear any pending data in the stream without converting it slouken@11631: * slouken@11631: * \sa SDL_NewAudioStream slouken@11631: * \sa SDL_AudioStreamPut slouken@11631: * \sa SDL_AudioStreamGet slouken@11631: * \sa SDL_AudioStreamAvailable slouken@11639: * \sa SDL_AudioStreamFlush slouken@11631: * \sa SDL_FreeAudioStream slouken@11631: */ slouken@11631: extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); slouken@11631: slouken@11631: /** slouken@11631: * Free an audio stream slouken@11631: * slouken@11631: * \sa SDL_NewAudioStream slouken@11631: * \sa SDL_AudioStreamPut slouken@11631: * \sa SDL_AudioStreamGet slouken@11631: * \sa SDL_AudioStreamAvailable slouken@11639: * \sa SDL_AudioStreamFlush slouken@11631: * \sa SDL_AudioStreamClear slouken@11631: */ slouken@11631: extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); slouken@11631: slouken@3407: #define SDL_MIX_MAXVOLUME 128 slouken@3407: /** slouken@3407: * This takes two audio buffers of the playing audio format and mixes slouken@3407: * them, performing addition, volume adjustment, and overflow clipping. slouken@3407: * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME slouken@3407: * for full audio volume. Note this does not change hardware volume. slouken@3407: * This is provided for convenience -- you can mix your own audio data. slouken@0: */ slouken@1895: extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, slouken@1895: Uint32 len, int volume); slouken@0: slouken@3407: /** slouken@3407: * This works like SDL_MixAudio(), but you specify the audio format instead of icculus@1964: * using the format of audio device 1. Thus it can be used when no audio icculus@1964: * device is open at all. icculus@1964: */ slouken@1967: extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, slouken@1967: const Uint8 * src, icculus@1964: SDL_AudioFormat format, icculus@1964: Uint32 len, int volume); icculus@1964: slouken@3407: /** icculus@9012: * Queue more audio on non-callback devices. icculus@9012: * icculus@10262: * (If you are looking to retrieve queued audio from a non-callback capture icculus@10262: * device, you want SDL_DequeueAudio() instead. This will return -1 to icculus@10262: * signify an error if you use it with capture devices.) icculus@10262: * icculus@9012: * SDL offers two ways to feed audio to the device: you can either supply a icculus@9012: * callback that SDL triggers with some frequency to obtain more audio icculus@9012: * (pull method), or you can supply no callback, and then SDL will expect icculus@9012: * you to supply data at regular intervals (push method) with this function. icculus@9012: * icculus@9012: * There are no limits on the amount of data you can queue, short of icculus@9012: * exhaustion of address space. Queued data will drain to the device as icculus@9012: * necessary without further intervention from you. If the device needs icculus@9012: * audio but there is not enough queued, it will play silence to make up icculus@9012: * the difference. This means you will have skips in your audio playback icculus@9012: * if you aren't routinely queueing sufficient data. icculus@9012: * icculus@9012: * This function copies the supplied data, so you are safe to free it when icculus@9012: * the function returns. This function is thread-safe, but queueing to the icculus@9012: * same device from two threads at once does not promise which buffer will icculus@9012: * be queued first. icculus@9012: * icculus@9012: * You may not queue audio on a device that is using an application-supplied icculus@9012: * callback; doing so returns an error. You have to use the audio callback icculus@9012: * or queue audio with this function, but not both. icculus@9012: * icculus@9012: * You should not call SDL_LockAudio() on the device before queueing; SDL icculus@9012: * handles locking internally for this function. icculus@9012: * icculus@9012: * \param dev The device ID to which we will queue audio. icculus@9012: * \param data The data to queue to the device for later playback. icculus@9012: * \param len The number of bytes (not samples!) to which (data) points. slouken@11631: * \return 0 on success, or -1 on error. icculus@9012: * icculus@9012: * \sa SDL_GetQueuedAudioSize icculus@9012: * \sa SDL_ClearQueuedAudio icculus@9012: */ icculus@9012: extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len); icculus@9012: icculus@9012: /** icculus@10262: * Dequeue more audio on non-callback devices. icculus@10262: * icculus@10262: * (If you are looking to queue audio for output on a non-callback playback icculus@10262: * device, you want SDL_QueueAudio() instead. This will always return 0 icculus@10262: * if you use it with playback devices.) icculus@10262: * icculus@10262: * SDL offers two ways to retrieve audio from a capture device: you can icculus@10262: * either supply a callback that SDL triggers with some frequency as the icculus@10262: * device records more audio data, (push method), or you can supply no icculus@10262: * callback, and then SDL will expect you to retrieve data at regular icculus@10262: * intervals (pull method) with this function. icculus@10262: * icculus@10262: * There are no limits on the amount of data you can queue, short of icculus@10262: * exhaustion of address space. Data from the device will keep queuing as icculus@10262: * necessary without further intervention from you. This means you will icculus@10262: * eventually run out of memory if you aren't routinely dequeueing data. icculus@10262: * icculus@10262: * Capture devices will not queue data when paused; if you are expecting icculus@10262: * to not need captured audio for some length of time, use icculus@10262: * SDL_PauseAudioDevice() to stop the capture device from queueing more icculus@10262: * data. This can be useful during, say, level loading times. When icculus@10262: * unpaused, capture devices will start queueing data from that point, icculus@10262: * having flushed any capturable data available while paused. icculus@10262: * icculus@10262: * This function is thread-safe, but dequeueing from the same device from icculus@10262: * two threads at once does not promise which thread will dequeued data icculus@10262: * first. icculus@10262: * icculus@10262: * You may not dequeue audio from a device that is using an icculus@10262: * application-supplied callback; doing so returns an error. You have to use icculus@10262: * the audio callback, or dequeue audio with this function, but not both. icculus@10262: * icculus@10262: * You should not call SDL_LockAudio() on the device before queueing; SDL icculus@10262: * handles locking internally for this function. icculus@10262: * icculus@10262: * \param dev The device ID from which we will dequeue audio. icculus@10262: * \param data A pointer into where audio data should be copied. icculus@10262: * \param len The number of bytes (not samples!) to which (data) points. icculus@10262: * \return number of bytes dequeued, which could be less than requested. icculus@10262: * icculus@10262: * \sa SDL_GetQueuedAudioSize icculus@10262: * \sa SDL_ClearQueuedAudio icculus@10262: */ icculus@10262: extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len); icculus@10262: icculus@10262: /** icculus@9012: * Get the number of bytes of still-queued audio. icculus@9012: * icculus@10262: * For playback device: icculus@9012: * icculus@10262: * This is the number of bytes that have been queued for playback with icculus@10262: * SDL_QueueAudio(), but have not yet been sent to the hardware. This icculus@10262: * number may shrink at any time, so this only informs of pending data. icculus@10262: * icculus@10262: * Once we've sent it to the hardware, this function can not decide the icculus@10262: * exact byte boundary of what has been played. It's possible that we just icculus@10262: * gave the hardware several kilobytes right before you called this icculus@10262: * function, but it hasn't played any of it yet, or maybe half of it, etc. icculus@10262: * icculus@10262: * For capture devices: icculus@10262: * icculus@10262: * This is the number of bytes that have been captured by the device and icculus@10262: * are waiting for you to dequeue. This number may grow at any time, so icculus@10262: * this only informs of the lower-bound of available data. icculus@9012: * icculus@9012: * You may not queue audio on a device that is using an application-supplied icculus@9012: * callback; calling this function on such a device always returns 0. icculus@10262: * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use icculus@10262: * the audio callback, but not both. icculus@9012: * icculus@9012: * You should not call SDL_LockAudio() on the device before querying; SDL icculus@9012: * handles locking internally for this function. icculus@9012: * icculus@9012: * \param dev The device ID of which we will query queued audio size. icculus@9012: * \return Number of bytes (not samples!) of queued audio. icculus@9012: * icculus@9012: * \sa SDL_QueueAudio icculus@9012: * \sa SDL_ClearQueuedAudio icculus@9012: */ icculus@9012: extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); icculus@9012: icculus@9012: /** icculus@10262: * Drop any queued audio data. For playback devices, this is any queued data icculus@10262: * still waiting to be submitted to the hardware. For capture devices, this icculus@10262: * is any data that was queued by the device that hasn't yet been dequeued by icculus@10262: * the application. icculus@9012: * icculus@10262: * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For icculus@10262: * playback devices, the hardware will start playing silence if more audio icculus@10262: * isn't queued. Unpaused capture devices will start filling the queue again icculus@10262: * as soon as they have more data available (which, depending on the state icculus@10262: * of the hardware and the thread, could be before this function call icculus@10262: * returns!). icculus@9012: * icculus@9012: * This will not prevent playback of queued audio that's already been sent icculus@9012: * to the hardware, as we can not undo that, so expect there to be some icculus@9012: * fraction of a second of audio that might still be heard. This can be icculus@9012: * useful if you want to, say, drop any pending music during a level change icculus@9012: * in your game. icculus@9012: * icculus@9012: * You may not queue audio on a device that is using an application-supplied icculus@9012: * callback; calling this function on such a device is always a no-op. icculus@10262: * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use icculus@10262: * the audio callback, but not both. icculus@9012: * icculus@9012: * You should not call SDL_LockAudio() on the device before clearing the icculus@9012: * queue; SDL handles locking internally for this function. icculus@9012: * icculus@9012: * This function always succeeds and thus returns void. icculus@9012: * icculus@9012: * \param dev The device ID of which to clear the audio queue. icculus@9012: * icculus@9012: * \sa SDL_QueueAudio icculus@9012: * \sa SDL_GetQueuedAudioSize icculus@9012: */ icculus@9012: extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev); icculus@9012: icculus@9012: icculus@9012: /** slouken@3407: * \name Audio lock functions slouken@7191: * slouken@3407: * The lock manipulated by these functions protects the callback function. slouken@7191: * During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that slouken@3407: * the callback function is not running. Do not call these from the callback slouken@3407: * function or you will cause deadlock. slouken@0: */ gabomdq@7678: /* @{ */ slouken@337: extern DECLSPEC void SDLCALL SDL_LockAudio(void); icculus@1964: extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev); slouken@337: extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); icculus@1964: extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev); gabomdq@7678: /* @} *//* Audio lock functions */ slouken@0: slouken@3407: /** slouken@3407: * This function shuts down audio processing and closes the audio device. slouken@0: */ slouken@337: extern DECLSPEC void SDLCALL SDL_CloseAudio(void); icculus@1964: extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev); icculus@1964: slouken@0: /* Ends C function definitions when using C++ */ slouken@0: #ifdef __cplusplus slouken@0: } slouken@0: #endif slouken@0: #include "close_code.h" slouken@0: slouken@10638: #endif /* SDL_audio_h_ */ slouken@1895: slouken@1895: /* vi: set ts=4 sw=4 expandtab: */