19682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/* 29682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall SDL - Simple DirectMedia Layer 39682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Copyright (C) 1997-2012 Sam Lantinga 49682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 59682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall This library is free software; you can redistribute it and/or 69682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall modify it under the terms of the GNU Lesser General Public 79682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall License as published by the Free Software Foundation; either 89682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall version 2.1 of the License, or (at your option) any later version. 99682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 109682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall This library is distributed in the hope that it will be useful, 119682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall but WITHOUT ANY WARRANTY; without even the implied warranty of 129682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 139682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Lesser General Public License for more details. 149682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 159682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall You should have received a copy of the GNU Lesser General Public 169682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall License along with this library; if not, write to the Free Software 179682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 189682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 199682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Sam Lantinga 209682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall slouken@libsdl.org 219682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall*/ 229682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 239682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 249682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @file SDL_audio.h 259682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * Access to the raw audio mixing buffer for the SDL library 269682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 279682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 289682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#ifndef _SDL_audio_h 299682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define _SDL_audio_h 309682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 319682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "SDL_stdinc.h" 329682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "SDL_error.h" 339682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "SDL_endian.h" 349682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "SDL_mutex.h" 359682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "SDL_thread.h" 369682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "SDL_rwops.h" 379682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 389682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "begin_code.h" 399682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/* Set up for C function definitions, even when using C++ */ 409682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#ifdef __cplusplus 419682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern "C" { 429682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#endif 439682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 449682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 459682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * When filling in the desired audio spec structure, 469682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->freq' should be the desired audio frequency in samples-per-second. 479682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->format' should be the desired audio format. 489682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->samples' is the desired size of the audio buffer, in samples. 499682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This number should be a power of two, and may be adjusted by the audio 509682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * driver to a value more suitable for the hardware. Good values seem to 519682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * range between 512 and 8096 inclusive, depending on the application and 529682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * CPU speed. Smaller values yield faster response time, but can lead 539682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * to underflow if the application is doing heavy processing and cannot 549682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * fill the audio buffer in time. A stereo sample consists of both right 559682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * and left channels in LR ordering. 569682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * Note that the number of samples is directly related to time by the 579682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * following formula: ms = (samples*1000)/freq 589682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->size' is the size in bytes of the audio buffer, and is 599682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * calculated by SDL_OpenAudio(). 609682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->silence' is the value used to set the buffer to silence, 619682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * and is calculated by SDL_OpenAudio(). 629682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->callback' should be set to a function that will be called 639682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * when the audio device is ready for more data. It is passed a pointer 649682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * to the audio buffer, and the length in bytes of the audio buffer. 659682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function usually runs in a separate thread, and so you should 669682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * protect data structures that it accesses by calling SDL_LockAudio() 679682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * and SDL_UnlockAudio() in your code. 689682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * - 'desired->userdata' is passed as the first parameter to your callback 699682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * function. 709682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 719682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @note The calculated values in this structure are calculated by SDL_OpenAudio() 729682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 739682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 749682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Halltypedef struct SDL_AudioSpec { 759682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall int freq; /**< DSP frequency -- samples per second */ 769682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 format; /**< Audio data format */ 779682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint8 channels; /**< Number of channels: 1 mono, 2 stereo */ 789682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint8 silence; /**< Audio buffer silence value (calculated) */ 799682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 samples; /**< Audio buffer size in samples (power of 2) */ 809682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 padding; /**< Necessary for some compile environments */ 819682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint32 size; /**< Audio buffer size in bytes (calculated) */ 829682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall /** 839682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function is called when the audio device needs more data. 849682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 859682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @param[out] stream A pointer to the audio data buffer 869682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @param[in] len The length of the audio buffer in bytes. 879682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 889682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * Once the callback returns, the buffer will no longer be valid. 899682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * Stereo samples are stored in a LRLRLR ordering. 909682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 919682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len); 929682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall void *userdata; 939682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall} SDL_AudioSpec; 949682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 959682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 969682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @name Audio format flags 979682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * defaults to LSB byte order 989682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 999682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@{*/ 1009682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */ 1019682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_S8 0x8008 /**< Signed 8-bit samples */ 1029682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_U16LSB 0x0010 /**< Unsigned 16-bit samples */ 1039682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_S16LSB 0x8010 /**< Signed 16-bit samples */ 1049682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_U16MSB 0x1010 /**< As above, but big-endian byte order */ 1059682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_S16MSB 0x9010 /**< As above, but big-endian byte order */ 1069682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_U16 AUDIO_U16LSB 1079682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_S16 AUDIO_S16LSB 1089682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1099682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 1109682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @name Native audio byte ordering 1119682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 1129682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@{*/ 1139682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#if SDL_BYTEORDER == SDL_LIL_ENDIAN 1149682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_U16SYS AUDIO_U16LSB 1159682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_S16SYS AUDIO_S16LSB 1169682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#else 1179682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_U16SYS AUDIO_U16MSB 1189682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define AUDIO_S16SYS AUDIO_S16MSB 1199682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#endif 1209682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@}*/ 1219682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1229682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@}*/ 1239682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1249682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1259682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** A structure to hold a set of audio conversion filters and buffers */ 1269682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Halltypedef struct SDL_AudioCVT { 1279682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall int needed; /**< Set to 1 if conversion possible */ 1289682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 src_format; /**< Source audio format */ 1299682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 dst_format; /**< Target audio format */ 1309682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall double rate_incr; /**< Rate conversion increment */ 1319682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint8 *buf; /**< Buffer to hold entire audio data */ 1329682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall int len; /**< Length of original audio buffer */ 1339682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall int len_cvt; /**< Length of converted audio buffer */ 1349682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall int len_mult; /**< buffer must be len*len_mult big */ 1359682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall double len_ratio; /**< Given len, final size is len*len_ratio */ 1369682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format); 1379682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall int filter_index; /**< Current audio conversion function */ 1389682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall} SDL_AudioCVT; 1399682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1409682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1419682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/* Function prototypes */ 1429682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1439682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 1449682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @name Audio Init and Quit 1459682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * These functions are used internally, and should not be used unless you 1469682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * have a specific need to specify the audio driver you want to use. 1479682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * You should normally use SDL_Init() or SDL_InitSubSystem(). 1489682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 1499682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@{*/ 1509682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name); 1519682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_AudioQuit(void); 1529682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@}*/ 1539682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1549682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 1559682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function fills the given character buffer with the name of the 1569682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * current audio driver, and returns a pointer to it if the audio driver has 1579682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * been initialized. It returns NULL if no driver has been initialized. 1589682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 1599682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen); 1609682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1619682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 1629682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function opens the audio device with the desired parameters, and 1639682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * returns 0 if successful, placing the actual hardware parameters in the 1649682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * structure pointed to by 'obtained'. If 'obtained' is NULL, the audio 1659682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * data passed to the callback function will be guaranteed to be in the 1669682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * requested format, and will be automatically converted to the hardware 1679682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * audio format if necessary. This function returns -1 if it failed 1689682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * to open the audio device, or couldn't set up the audio thread. 1699682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 1709682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * The audio device starts out playing silence when it's opened, and should 1719682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * be enabled for playing by calling SDL_PauseAudio(0) when you are ready 1729682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * for your audio callback function to be called. Since the audio driver 1739682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * may modify the requested size of the audio buffer, you should allocate 1749682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * any local mixing buffers after you open the audio device. 1759682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 1769682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @sa SDL_AudioSpec 1779682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 1789682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained); 1799682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1809682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Halltypedef enum { 1819682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall SDL_AUDIO_STOPPED = 0, 1829682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall SDL_AUDIO_PLAYING, 1839682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall SDL_AUDIO_PAUSED 1849682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall} SDL_audiostatus; 1859682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1869682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** Get the current audio state */ 1879682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void); 1889682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1899682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 1909682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function pauses and unpauses the audio callback processing. 1919682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * It should be called with a parameter of 0 after opening the audio 1929682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * device to start playing sound. This is so you can safely initialize 1939682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * data for your callback function after opening the audio device. 1949682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * Silence will be written to the audio device during the pause. 1959682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 1969682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); 1979682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 1989682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 1999682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function loads a WAVE from the data source, automatically freeing 2009682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * that source if 'freesrc' is non-zero. For example, to load a WAVE file, 2019682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * you could do: 2029682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @code SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...); @endcode 2039682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 2049682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * If this function succeeds, it returns the given SDL_AudioSpec, 2059682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * filled with the audio data format of the wave data, and sets 2069682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 'audio_buf' to a malloc()'d buffer containing the audio data, 2079682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * and sets 'audio_len' to the length of that audio buffer, in bytes. 2089682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * You need to free the audio buffer with SDL_FreeWAV() when you are 2099682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * done with it. 2109682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 2119682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function returns NULL and sets the SDL error message if the 2129682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * wave file cannot be opened, uses an unknown data format, or is 2139682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * corrupt. Currently raw and MS-ADPCM WAVE files are supported. 2149682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2159682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); 2169682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2179682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** Compatibility convenience function -- loads a WAV from a file */ 2189682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ 2199682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len) 2209682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2219682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 2229682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function frees data previously allocated with SDL_LoadWAV_RW() 2239682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2249682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf); 2259682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2269682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 2279682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function takes a source format and rate and a destination format 2289682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * and rate, and initializes the 'cvt' structure with information needed 2299682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * by SDL_ConvertAudio() to convert a buffer of audio data from one format 2309682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * to the other. 2319682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * 2329682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @return This function returns 0, or -1 if there was an error. 2339682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2349682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt, 2359682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 src_format, Uint8 src_channels, int src_rate, 2369682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall Uint16 dst_format, Uint8 dst_channels, int dst_rate); 2379682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2389682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 2399682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(), 2409682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * created an audio buffer cvt->buf, and filled it with cvt->len bytes of 2419682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * audio data in the source format, this function will convert it in-place 2429682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * to the desired format. 2439682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * The data conversion may expand the size of the audio data, so the buffer 2449682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * cvt->buf should be allocated after the cvt structure is initialized by 2459682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long. 2469682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2479682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt); 2489682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2499682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2509682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#define SDL_MIX_MAXVOLUME 128 2519682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 2529682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This takes two audio buffers of the playing audio format and mixes 2539682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * them, performing addition, volume adjustment, and overflow clipping. 2549682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME 2559682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * for full audio volume. Note this does not change hardware volume. 2569682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This is provided for convenience -- you can mix your own audio data. 2579682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2589682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume); 2599682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2609682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 2619682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * @name Audio Locks 2629682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * The lock manipulated by these functions protects the callback function. 2639682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * During a LockAudio/UnlockAudio pair, you can be guaranteed that the 2649682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * callback function is not running. Do not call these from the callback 2659682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * function or you will cause deadlock. 2669682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2679682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@{*/ 2689682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_LockAudio(void); 2699682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_UnlockAudio(void); 2709682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/*@}*/ 2719682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2729682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/** 2739682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall * This function shuts down audio processing and closes the audio device. 2749682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall */ 2759682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hallextern DECLSPEC void SDLCALL SDL_CloseAudio(void); 2769682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2779682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2789682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall/* Ends C function definitions when using C++ */ 2799682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#ifdef __cplusplus 2809682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall} 2819682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#endif 2829682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#include "close_code.h" 2839682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall 2849682c8870b8ff5e4ac2e4c70b759f791c6f38c1fJesse Hall#endif /* _SDL_audio_h */ 285