X-Git-Url: http://git.xonotic.org/?p=xonotic%2Fxonotic.git;a=blobdiff_plain;f=misc%2Fbuilddeps%2Fwin64%2Fsdl%2Finclude%2FSDL2%2FSDL_audio.h;h=305c01a9d943a5b8c3b2141013051bb2afb8922d;hp=d51f0d1ce2b461648fe17f9c8b4b453a0ed73a1d;hb=1e434bee7af23e6dfd2130a8eadd131e5da3d643;hpb=c40448285437999d5a83a3c9adb62c58ba8640bc diff --git a/misc/builddeps/win64/sdl/include/SDL2/SDL_audio.h b/misc/builddeps/win64/sdl/include/SDL2/SDL_audio.h index d51f0d1c..305c01a9 100644 --- a/misc/builddeps/win64/sdl/include/SDL2/SDL_audio.h +++ b/misc/builddeps/win64/sdl/include/SDL2/SDL_audio.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2016 Sam Lantinga + Copyright (C) 1997-2019 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,8 +25,8 @@ * Access to the raw audio mixing buffer for the SDL library. */ -#ifndef _SDL_audio_h -#define _SDL_audio_h +#ifndef SDL_audio_h_ +#define SDL_audio_h_ #include "SDL_stdinc.h" #include "SDL_error.h" @@ -140,7 +140,8 @@ typedef Uint16 SDL_AudioFormat; #define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE 0x00000001 #define SDL_AUDIO_ALLOW_FORMAT_CHANGE 0x00000002 #define SDL_AUDIO_ALLOW_CHANNELS_CHANGE 0x00000004 -#define SDL_AUDIO_ALLOW_ANY_CHANGE (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE) +#define SDL_AUDIO_ALLOW_SAMPLES_CHANGE 0x00000008 +#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) /* @} */ /* @} *//* Audio flags */ @@ -164,6 +165,15 @@ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, /** * The calculated values in this structure are calculated by SDL_OpenAudio(). + * + * For multi-channel audio, the default SDL channel mapping is: + * 2: FL FR (stereo) + * 3: FL FR LFE (2.1 surround) + * 4: FL FR BL BR (quad) + * 5: FL FR FC BL BR (quad + center) + * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) + * 7: FL FR FC LFE BC SL SR (6.1 surround) + * 8: FL FR FC LFE BL BR SL SR (7.1 surround) */ typedef struct SDL_AudioSpec { @@ -171,7 +181,7 @@ typedef struct SDL_AudioSpec SDL_AudioFormat format; /**< Audio data format */ Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ Uint8 silence; /**< Audio buffer silence value (calculated) */ - Uint16 samples; /**< Audio buffer size in samples (power of 2) */ + Uint16 samples; /**< Audio buffer size in sample FRAMES (total samples divided by channel count) */ Uint16 padding; /**< Necessary for some compile environments */ Uint32 size; /**< Audio buffer size in bytes (calculated) */ SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */ @@ -184,7 +194,23 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt, SDL_AudioFormat format); /** - * A structure to hold a set of audio conversion filters and buffers. + * \brief Upper limit of filters in SDL_AudioCVT + * + * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is + * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, + * one of which is the terminating NULL pointer. + */ +#define SDL_AUDIOCVT_MAX_FILTERS 9 + +/** + * \struct SDL_AudioCVT + * \brief A structure to hold a set of audio conversion filters and buffers. + * + * Note that various parts of the conversion pipeline can take advantage + * of SIMD operations (like SSE2, for example). SDL_AudioCVT doesn't require + * you to pass it aligned data, but can possibly run much faster if you + * set both its (buf) field to a pointer that is aligned to 16 bytes, and its + * (len) field to something that's a multiple of 16, if possible. */ #ifdef __GNUC__ /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't @@ -208,7 +234,7 @@ typedef struct SDL_AudioCVT int len_cvt; /**< Length of converted audio buffer */ int len_mult; /**< buffer must be len*len_mult big */ double len_ratio; /**< Given len, final size is len*len_ratio */ - SDL_AudioFilter filters[10]; /**< Filter list */ + SDL_AudioFilter filters[SDL_AUDIOCVT_MAX_FILTERS + 1]; /**< NULL-terminated list of filter functions */ int filter_index; /**< Current audio conversion function */ } SDL_AUDIOCVT_PACKED SDL_AudioCVT; @@ -394,23 +420,56 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, /* @} *//* Pause audio functions */ /** - * This function loads a WAVE from the data source, automatically freeing - * that source if \c freesrc is non-zero. For example, to load a WAVE file, - * you could do: + * \brief Load the audio data of a WAVE file into memory + * + * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len + * to be valid pointers. The entire data portion of the file is then loaded + * into memory and decoded if necessary. + * + * If \c freesrc is non-zero, the data source gets automatically closed and + * freed before the function returns. + * + * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits), + * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and + * µ-law (8 bits). Other formats are currently unsupported and cause an error. + * + * If this function succeeds, the pointer returned by it is equal to \c spec + * and the pointer to the audio data allocated by the function is written to + * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec + * members \c freq, \c channels, and \c format are set to the values of the + * audio data in the buffer. The \c samples member is set to a sane default and + * all others are set to zero. + * + * It's necessary to use SDL_FreeWAV() to free the audio data returned in + * \c audio_buf when it is no longer used. + * + * Because of the underspecification of the Waveform format, there are many + * problematic files in the wild that cause issues with strict decoders. To + * provide compatibility with these files, this decoder is lenient in regards + * to the truncation of the file, the fact chunk, and the size of the RIFF + * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION, + * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the + * loading process. + * + * Any file that is invalid (due to truncation, corruption, or wrong values in + * the headers), too big, or unsupported causes an error. Additionally, any + * critical I/O error from the data source will terminate the loading process + * with an error. The function returns NULL on error and in all cases (with the + * exception of \c src being NULL), an appropriate error message will be set. + * + * It is required that the data source supports seeking. + * + * Example: * \code * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); * \endcode * - * If this function succeeds, it returns the given SDL_AudioSpec, - * filled with the audio data format of the wave data, and sets - * \c *audio_buf to a malloc()'d buffer containing the audio data, - * and sets \c *audio_len to the length of that audio buffer, in bytes. - * You need to free the audio buffer with SDL_FreeWAV() when you are - * done with it. - * - * This function returns NULL and sets the SDL error message if the - * wave file cannot be opened, uses an unknown data format, or is - * corrupt. Currently raw and MS-ADPCM WAVE files are supported. + * \param src The data source with the WAVE data + * \param freesrc A integer value that makes the function close the data source if non-zero + * \param spec A pointer filled with the audio format of the audio data + * \param audio_buf A pointer filled with the audio data allocated by the function + * \param audio_len A pointer filled with the length of the audio data buffer in bytes + * \return NULL on error, or non-NULL on success. */ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, int freesrc, @@ -434,10 +493,10 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); * This function takes a source format and rate and a destination format * and rate, and initializes the \c cvt structure with information needed * by SDL_ConvertAudio() to convert a buffer of audio data from one format - * to the other. + * to the other. An unsupported format causes an error and -1 will be returned. * - * \return -1 if the format conversion is not supported, 0 if there's - * no conversion needed, or 1 if the audio filter is set up. + * \return 0 if no conversion is needed, 1 if the audio filter is set up, + * or -1 on error. */ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, SDL_AudioFormat src_format, @@ -456,9 +515,137 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt, * The data conversion may expand the size of the audio data, so the buffer * \c cvt->buf should be allocated after the \c cvt structure is initialized by * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long. + * + * \return 0 on success or -1 if \c cvt->buf is NULL. */ extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt); +/* SDL_AudioStream is a new audio conversion interface. + The benefits vs SDL_AudioCVT: + - it can handle resampling data in chunks without generating + artifacts, when it doesn't have the complete buffer available. + - it can handle incoming data in any variable size. + - You push data as you have it, and pull it when you need it + */ +/* this is opaque to the outside world. */ +struct _SDL_AudioStream; +typedef struct _SDL_AudioStream SDL_AudioStream; + +/** + * Create a new audio stream + * + * \param src_format The format of the source audio + * \param src_channels The number of channels of the source audio + * \param src_rate The sampling rate of the source audio + * \param dst_format The format of the desired audio output + * \param dst_channels The number of channels of the desired audio output + * \param dst_rate The sampling rate of the desired audio output + * \return 0 on success, or -1 on error. + * + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + */ +extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format, + const Uint8 src_channels, + const int src_rate, + const SDL_AudioFormat dst_format, + const Uint8 dst_channels, + const int dst_rate); + +/** + * Add data to be converted/resampled to the stream + * + * \param stream The stream the audio data is being added to + * \param buf A pointer to the audio data to add + * \param len The number of bytes to write to the stream + * \return 0 on success, or -1 on error. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + */ +extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len); + +/** + * Get converted/resampled data from the stream + * + * \param stream The stream the audio is being requested from + * \param buf A buffer to fill with audio data + * \param len The maximum number of bytes to fill + * \return The number of bytes read from the stream, or -1 on error + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + */ +extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len); + +/** + * Get the number of converted/resampled bytes available. The stream may be + * buffering data behind the scenes until it has enough to resample + * correctly, so this number might be lower than what you expect, or even + * be zero. Add more data or flush the stream if you need the data now. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + */ +extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream); + +/** + * Tell the stream that you're done sending data, and anything being buffered + * should be converted/resampled and made available immediately. + * + * It is legal to add more data to a stream after flushing, but there will + * be audio gaps in the output. Generally this is intended to signal the + * end of input, so the complete output becomes available. + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamClear + * \sa SDL_FreeAudioStream + */ +extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream); + +/** + * Clear any pending data in the stream without converting it + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_FreeAudioStream + */ +extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream); + +/** + * Free an audio stream + * + * \sa SDL_NewAudioStream + * \sa SDL_AudioStreamPut + * \sa SDL_AudioStreamGet + * \sa SDL_AudioStreamAvailable + * \sa SDL_AudioStreamFlush + * \sa SDL_AudioStreamClear + */ +extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); + #define SDL_MIX_MAXVOLUME 128 /** * This takes two audio buffers of the playing audio format and mixes @@ -514,7 +701,7 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, * \param dev The device ID to which we will queue audio. * \param data The data to queue to the device for later playback. * \param len The number of bytes (not samples!) to which (data) points. - * \return zero on success, -1 on error. + * \return 0 on success, or -1 on error. * * \sa SDL_GetQueuedAudioSize * \sa SDL_ClearQueuedAudio @@ -667,6 +854,6 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev); #endif #include "close_code.h" -#endif /* _SDL_audio_h */ +#endif /* SDL_audio_h_ */ /* vi: set ts=4 sw=4 expandtab: */