Return to sdl_audio.h CVS log

Up to [Synchronet] / sbbs / include / sdl

Annotation of sbbs/include/sdl/sdl_audio.h, revision 1.1

1.1     ! root        1: /*
        !             2:     SDL - Simple DirectMedia Layer
        !             3:     Copyright (C) 1997-2004 Sam Lantinga
        !             4: 
        !             5:     This library is free software; you can redistribute it and/or
        !             6:     modify it under the terms of the GNU Library General Public
        !             7:     License as published by the Free Software Foundation; either
        !             8:     version 2 of the License, or (at your option) any later version.
        !             9: 
        !            10:     This library is distributed in the hope that it will be useful,
        !            11:     but WITHOUT ANY WARRANTY; without even the implied warranty of
        !            12:     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        !            13:     Library General Public License for more details.
        !            14: 
        !            15:     You should have received a copy of the GNU Library General Public
        !            16:     License along with this library; if not, write to the Free
        !            17:     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
        !            18: 
        !            19:     Sam Lantinga
        !            20:     [email protected]
        !            21: */
        !            22: 
        !            23: #ifdef SAVE_RCSID
        !            24: static char rcsid =
        !            25:  "@(#) $Id: SDL_audio.h,v 1.1.1.1 2005/11/18 23:23:29 rswindell Exp $";
        !            26: #endif
        !            27: 
        !            28: /* Access to the raw audio mixing buffer for the SDL library */
        !            29: 
        !            30: #ifndef _SDL_audio_h
        !            31: #define _SDL_audio_h
        !            32: 
        !            33: #include <stdio.h>
        !            34: 
        !            35: #include "SDL_main.h"
        !            36: #include "SDL_types.h"
        !            37: #include "SDL_error.h"
        !            38: #include "SDL_rwops.h"
        !            39: #include "SDL_byteorder.h"
        !            40: 
        !            41: #include "begin_code.h"
        !            42: /* Set up for C function definitions, even when using C++ */
        !            43: #ifdef __cplusplus
        !            44: extern "C" {
        !            45: #endif
        !            46: 
        !            47: /* The calculated values in this structure are calculated by SDL_OpenAudio() */
        !            48: typedef struct SDL_AudioSpec {
        !            49:        int freq;               /* DSP frequency -- samples per second */
        !            50:        Uint16 format;          /* Audio data format */
        !            51:        Uint8  channels;        /* Number of channels: 1 mono, 2 stereo */
        !            52:        Uint8  silence;         /* Audio buffer silence value (calculated) */
        !            53:        Uint16 samples;         /* Audio buffer size in samples (power of 2) */
        !            54:        Uint16 padding;         /* Necessary for some compile environments */
        !            55:        Uint32 size;            /* Audio buffer size in bytes (calculated) */
        !            56:        /* This function is called when the audio device needs more data.
        !            57:           'stream' is a pointer to the audio data buffer
        !            58:           'len' is the length of that buffer in bytes.
        !            59:           Once the callback returns, the buffer will no longer be valid.
        !            60:           Stereo samples are stored in a LRLRLR ordering.
        !            61:        */
        !            62:        void (SDLCALL *callback)(void *userdata, Uint8 *stream, int len);
        !            63:        void  *userdata;
        !            64: } SDL_AudioSpec;
        !            65: 
        !            66: /* Audio format flags (defaults to LSB byte order) */
        !            67: #define AUDIO_U8       0x0008  /* Unsigned 8-bit samples */
        !            68: #define AUDIO_S8       0x8008  /* Signed 8-bit samples */
        !            69: #define AUDIO_U16LSB   0x0010  /* Unsigned 16-bit samples */
        !            70: #define AUDIO_S16LSB   0x8010  /* Signed 16-bit samples */
        !            71: #define AUDIO_U16MSB   0x1010  /* As above, but big-endian byte order */
        !            72: #define AUDIO_S16MSB   0x9010  /* As above, but big-endian byte order */
        !            73: #define AUDIO_U16      AUDIO_U16LSB
        !            74: #define AUDIO_S16      AUDIO_S16LSB
        !            75: 
        !            76: /* Native audio byte ordering */
        !            77: #if SDL_BYTEORDER == SDL_LIL_ENDIAN
        !            78: #define AUDIO_U16SYS   AUDIO_U16LSB
        !            79: #define AUDIO_S16SYS   AUDIO_S16LSB
        !            80: #else
        !            81: #define AUDIO_U16SYS   AUDIO_U16MSB
        !            82: #define AUDIO_S16SYS   AUDIO_S16MSB
        !            83: #endif
        !            84: 
        !            85: 
        !            86: /* A structure to hold a set of audio conversion filters and buffers */
        !            87: typedef struct SDL_AudioCVT {
        !            88:        int needed;                     /* Set to 1 if conversion possible */
        !            89:        Uint16 src_format;              /* Source audio format */
        !            90:        Uint16 dst_format;              /* Target audio format */
        !            91:        double rate_incr;               /* Rate conversion increment */
        !            92:        Uint8 *buf;                     /* Buffer to hold entire audio data */
        !            93:        int    len;                     /* Length of original audio buffer */
        !            94:        int    len_cvt;                 /* Length of converted audio buffer */
        !            95:        int    len_mult;                /* buffer must be len*len_mult big */
        !            96:        double len_ratio;       /* Given len, final size is len*len_ratio */
        !            97:        void (SDLCALL *filters[10])(struct SDL_AudioCVT *cvt, Uint16 format);
        !            98:        int filter_index;               /* Current audio conversion function */
        !            99: } SDL_AudioCVT;
        !           100: 
        !           101: 
        !           102: /* Function prototypes */
        !           103: 
        !           104: /* These functions are used internally, and should not be used unless you
        !           105:  * have a specific need to specify the audio driver you want to use.
        !           106:  * You should normally use SDL_Init() or SDL_InitSubSystem().
        !           107:  */
        !           108: extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
        !           109: extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
        !           110: 
        !           111: /* This function fills the given character buffer with the name of the
        !           112:  * current audio driver, and returns a pointer to it if the audio driver has
        !           113:  * been initialized.  It returns NULL if no driver has been initialized.
        !           114:  */
        !           115: extern DECLSPEC char * SDLCALL SDL_AudioDriverName(char *namebuf, int maxlen);
        !           116: 
        !           117: /*
        !           118:  * This function opens the audio device with the desired parameters, and
        !           119:  * returns 0 if successful, placing the actual hardware parameters in the
        !           120:  * structure pointed to by 'obtained'.  If 'obtained' is NULL, the audio
        !           121:  * data passed to the callback function will be guaranteed to be in the
        !           122:  * requested format, and will be automatically converted to the hardware
        !           123:  * audio format if necessary.  This function returns -1 if it failed 
        !           124:  * to open the audio device, or couldn't set up the audio thread.
        !           125:  *
        !           126:  * When filling in the desired audio spec structure,
        !           127:  *  'desired->freq' should be the desired audio frequency in samples-per-second.
        !           128:  *  'desired->format' should be the desired audio format.
        !           129:  *  'desired->samples' is the desired size of the audio buffer, in samples.
        !           130:  *     This number should be a power of two, and may be adjusted by the audio
        !           131:  *     driver to a value more suitable for the hardware.  Good values seem to
        !           132:  *     range between 512 and 8096 inclusive, depending on the application and
        !           133:  *     CPU speed.  Smaller values yield faster response time, but can lead
        !           134:  *     to underflow if the application is doing heavy processing and cannot
        !           135:  *     fill the audio buffer in time.  A stereo sample consists of both right
        !           136:  *     and left channels in LR ordering.
        !           137:  *     Note that the number of samples is directly related to time by the
        !           138:  *     following formula:  ms = (samples*1000)/freq
        !           139:  *  'desired->size' is the size in bytes of the audio buffer, and is
        !           140:  *     calculated by SDL_OpenAudio().
        !           141:  *  'desired->silence' is the value used to set the buffer to silence,
        !           142:  *     and is calculated by SDL_OpenAudio().
        !           143:  *  'desired->callback' should be set to a function that will be called
        !           144:  *     when the audio device is ready for more data.  It is passed a pointer
        !           145:  *     to the audio buffer, and the length in bytes of the audio buffer.
        !           146:  *     This function usually runs in a separate thread, and so you should
        !           147:  *     protect data structures that it accesses by calling SDL_LockAudio()
        !           148:  *     and SDL_UnlockAudio() in your code.
        !           149:  *  'desired->userdata' is passed as the first parameter to your callback
        !           150:  *     function.
        !           151:  *
        !           152:  * The audio device starts out playing silence when it's opened, and should
        !           153:  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
        !           154:  * for your audio callback function to be called.  Since the audio driver
        !           155:  * may modify the requested size of the audio buffer, you should allocate
        !           156:  * any local mixing buffers after you open the audio device.
        !           157:  */
        !           158: extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained);
        !           159: 
        !           160: /*
        !           161:  * Get the current audio state:
        !           162:  */
        !           163: typedef enum {
        !           164:        SDL_AUDIO_STOPPED = 0,
        !           165:        SDL_AUDIO_PLAYING,
        !           166:        SDL_AUDIO_PAUSED
        !           167: } SDL_audiostatus;
        !           168: extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
        !           169: 
        !           170: /*
        !           171:  * This function pauses and unpauses the audio callback processing.
        !           172:  * It should be called with a parameter of 0 after opening the audio
        !           173:  * device to start playing sound.  This is so you can safely initialize
        !           174:  * data for your callback function after opening the audio device.
        !           175:  * Silence will be written to the audio device during the pause.
        !           176:  */
        !           177: extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
        !           178: 
        !           179: /*
        !           180:  * This function loads a WAVE from the data source, automatically freeing
        !           181:  * that source if 'freesrc' is non-zero.  For example, to load a WAVE file,
        !           182:  * you could do:
        !           183:  *     SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
        !           184:  *
        !           185:  * If this function succeeds, it returns the given SDL_AudioSpec,
        !           186:  * filled with the audio data format of the wave data, and sets
        !           187:  * 'audio_buf' to a malloc()'d buffer containing the audio data,
        !           188:  * and sets 'audio_len' to the length of that audio buffer, in bytes.
        !           189:  * You need to free the audio buffer with SDL_FreeWAV() when you are 
        !           190:  * done with it.
        !           191:  *
        !           192:  * This function returns NULL and sets the SDL error message if the 
        !           193:  * wave file cannot be opened, uses an unknown data format, or is 
        !           194:  * corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
        !           195:  */
        !           196: extern DECLSPEC SDL_AudioSpec * SDLCALL SDL_LoadWAV_RW(SDL_RWops *src, int freesrc, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
        !           197: 
        !           198: /* Compatibility convenience function -- loads a WAV from a file */
        !           199: #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
        !           200:        SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
        !           201: 
        !           202: /*
        !           203:  * This function frees data previously allocated with SDL_LoadWAV_RW()
        !           204:  */
        !           205: extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 *audio_buf);
        !           206: 
        !           207: /*
        !           208:  * This function takes a source format and rate and a destination format
        !           209:  * and rate, and initializes the 'cvt' structure with information needed
        !           210:  * by SDL_ConvertAudio() to convert a buffer of audio data from one format
        !           211:  * to the other.
        !           212:  * This function returns 0, or -1 if there was an error.
        !           213:  */
        !           214: extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT *cvt,
        !           215:                Uint16 src_format, Uint8 src_channels, int src_rate,
        !           216:                Uint16 dst_format, Uint8 dst_channels, int dst_rate);
        !           217: 
        !           218: /* Once you have initialized the 'cvt' structure using SDL_BuildAudioCVT(),
        !           219:  * created an audio buffer cvt->buf, and filled it with cvt->len bytes of
        !           220:  * audio data in the source format, this function will convert it in-place
        !           221:  * to the desired format.
        !           222:  * The data conversion may expand the size of the audio data, so the buffer
        !           223:  * cvt->buf should be allocated after the cvt structure is initialized by
        !           224:  * SDL_BuildAudioCVT(), and should be cvt->len*cvt->len_mult bytes long.
        !           225:  */
        !           226: extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT *cvt);
        !           227: 
        !           228: /*
        !           229:  * This takes two audio buffers of the playing audio format and mixes
        !           230:  * them, performing addition, volume adjustment, and overflow clipping.
        !           231:  * The volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
        !           232:  * for full audio volume.  Note this does not change hardware volume.
        !           233:  * This is provided for convenience -- you can mix your own audio data.
        !           234:  */
        !           235: #define SDL_MIX_MAXVOLUME 128
        !           236: extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, Uint32 len, int volume);
        !           237: 
        !           238: /*
        !           239:  * The lock manipulated by these functions protects the callback function.
        !           240:  * During a LockAudio/UnlockAudio pair, you can be guaranteed that the
        !           241:  * callback function is not running.  Do not call these from the callback
        !           242:  * function or you will cause deadlock.
        !           243:  */
        !           244: extern DECLSPEC void SDLCALL SDL_LockAudio(void);
        !           245: extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
        !           246: 
        !           247: /*
        !           248:  * This function shuts down audio processing and closes the audio device.
        !           249:  */
        !           250: extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
        !           251: 
        !           252: 
        !           253: /* Ends C function definitions when using C++ */
        !           254: #ifdef __cplusplus
        !           255: }
        !           256: #endif
        !           257: #include "close_code.h"
        !           258: 
        !           259: #endif /* _SDL_audio_h */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.