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=4c987d5110435893f216280503306d4288af2c8f;hb=1e434bee7af23e6dfd2130a8eadd131e5da3d643;hpb=47a4fd358e26ad7b6abc173b9e73955b1cab2cf5 diff --git a/misc/builddeps/win64/sdl/include/SDL2/SDL_audio.h b/misc/builddeps/win64/sdl/include/SDL2/SDL_audio.h index 4c987d51..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-2014 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 */ @@ -155,12 +156,24 @@ typedef Uint16 SDL_AudioFormat; * * Once the callback returns, the buffer will no longer be valid. * Stereo samples are stored in a LRLRLR ordering. + * + * You can choose to avoid callbacks and use SDL_QueueAudio() instead, if + * you like. Just open your audio device with a NULL callback. */ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream, int len); /** * 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 { @@ -168,11 +181,11 @@ 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; - void *userdata; + SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */ + void *userdata; /**< Userdata passed to callback (ignored for NULL callbacks). */ } SDL_AudioSpec; @@ -181,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 @@ -205,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; @@ -273,9 +302,12 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void); * to the audio buffer, and the length in bytes of the audio buffer. * This function usually runs in a separate thread, and so you should * protect data structures that it accesses by calling SDL_LockAudio() - * and SDL_UnlockAudio() in your code. + * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL + * pointer here, and call SDL_QueueAudio() with some frequency, to queue + * more audio samples to be played (or for capture devices, call + * SDL_DequeueAudio() with some frequency, to obtain audio samples). * - \c desired->userdata is passed as the first parameter to your callback - * function. + * function. If you passed a NULL callback, this value is ignored. * * The audio device starts out playing silence when it's opened, and should * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready @@ -388,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, @@ -428,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, @@ -450,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 @@ -474,6 +667,166 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, SDL_AudioFormat format, Uint32 len, int volume); +/** + * Queue more audio on non-callback devices. + * + * (If you are looking to retrieve queued audio from a non-callback capture + * device, you want SDL_DequeueAudio() instead. This will return -1 to + * signify an error if you use it with capture devices.) + * + * SDL offers two ways to feed audio to the device: you can either supply a + * callback that SDL triggers with some frequency to obtain more audio + * (pull method), or you can supply no callback, and then SDL will expect + * you to supply data at regular intervals (push method) with this function. + * + * There are no limits on the amount of data you can queue, short of + * exhaustion of address space. Queued data will drain to the device as + * necessary without further intervention from you. If the device needs + * audio but there is not enough queued, it will play silence to make up + * the difference. This means you will have skips in your audio playback + * if you aren't routinely queueing sufficient data. + * + * This function copies the supplied data, so you are safe to free it when + * the function returns. This function is thread-safe, but queueing to the + * same device from two threads at once does not promise which buffer will + * be queued first. + * + * You may not queue audio on a device that is using an application-supplied + * callback; doing so returns an error. You have to use the audio callback + * or queue audio with this function, but not both. + * + * You should not call SDL_LockAudio() on the device before queueing; SDL + * handles locking internally for this function. + * + * \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 0 on success, or -1 on error. + * + * \sa SDL_GetQueuedAudioSize + * \sa SDL_ClearQueuedAudio + */ +extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len); + +/** + * Dequeue more audio on non-callback devices. + * + * (If you are looking to queue audio for output on a non-callback playback + * device, you want SDL_QueueAudio() instead. This will always return 0 + * if you use it with playback devices.) + * + * SDL offers two ways to retrieve audio from a capture device: you can + * either supply a callback that SDL triggers with some frequency as the + * device records more audio data, (push method), or you can supply no + * callback, and then SDL will expect you to retrieve data at regular + * intervals (pull method) with this function. + * + * There are no limits on the amount of data you can queue, short of + * exhaustion of address space. Data from the device will keep queuing as + * necessary without further intervention from you. This means you will + * eventually run out of memory if you aren't routinely dequeueing data. + * + * Capture devices will not queue data when paused; if you are expecting + * to not need captured audio for some length of time, use + * SDL_PauseAudioDevice() to stop the capture device from queueing more + * data. This can be useful during, say, level loading times. When + * unpaused, capture devices will start queueing data from that point, + * having flushed any capturable data available while paused. + * + * This function is thread-safe, but dequeueing from the same device from + * two threads at once does not promise which thread will dequeued data + * first. + * + * You may not dequeue audio from a device that is using an + * application-supplied callback; doing so returns an error. You have to use + * the audio callback, or dequeue audio with this function, but not both. + * + * You should not call SDL_LockAudio() on the device before queueing; SDL + * handles locking internally for this function. + * + * \param dev The device ID from which we will dequeue audio. + * \param data A pointer into where audio data should be copied. + * \param len The number of bytes (not samples!) to which (data) points. + * \return number of bytes dequeued, which could be less than requested. + * + * \sa SDL_GetQueuedAudioSize + * \sa SDL_ClearQueuedAudio + */ +extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len); + +/** + * Get the number of bytes of still-queued audio. + * + * For playback device: + * + * This is the number of bytes that have been queued for playback with + * SDL_QueueAudio(), but have not yet been sent to the hardware. This + * number may shrink at any time, so this only informs of pending data. + * + * Once we've sent it to the hardware, this function can not decide the + * exact byte boundary of what has been played. It's possible that we just + * gave the hardware several kilobytes right before you called this + * function, but it hasn't played any of it yet, or maybe half of it, etc. + * + * For capture devices: + * + * This is the number of bytes that have been captured by the device and + * are waiting for you to dequeue. This number may grow at any time, so + * this only informs of the lower-bound of available data. + * + * You may not queue audio on a device that is using an application-supplied + * callback; calling this function on such a device always returns 0. + * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use + * the audio callback, but not both. + * + * You should not call SDL_LockAudio() on the device before querying; SDL + * handles locking internally for this function. + * + * \param dev The device ID of which we will query queued audio size. + * \return Number of bytes (not samples!) of queued audio. + * + * \sa SDL_QueueAudio + * \sa SDL_ClearQueuedAudio + */ +extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); + +/** + * Drop any queued audio data. For playback devices, this is any queued data + * still waiting to be submitted to the hardware. For capture devices, this + * is any data that was queued by the device that hasn't yet been dequeued by + * the application. + * + * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For + * playback devices, the hardware will start playing silence if more audio + * isn't queued. Unpaused capture devices will start filling the queue again + * as soon as they have more data available (which, depending on the state + * of the hardware and the thread, could be before this function call + * returns!). + * + * This will not prevent playback of queued audio that's already been sent + * to the hardware, as we can not undo that, so expect there to be some + * fraction of a second of audio that might still be heard. This can be + * useful if you want to, say, drop any pending music during a level change + * in your game. + * + * You may not queue audio on a device that is using an application-supplied + * callback; calling this function on such a device is always a no-op. + * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use + * the audio callback, but not both. + * + * You should not call SDL_LockAudio() on the device before clearing the + * queue; SDL handles locking internally for this function. + * + * This function always succeeds and thus returns void. + * + * \param dev The device ID of which to clear the audio queue. + * + * \sa SDL_QueueAudio + * \sa SDL_GetQueuedAudioSize + */ +extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev); + + /** * \name Audio lock functions * @@ -501,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: */