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