SDL_mixer.h
author Sam Lantinga <slouken@lokigames.com>
Thu, 05 Oct 2000 00:52:16 +0000
changeset 70 8ce14b7f7f6f
parent 59 6afcee51eb50
child 78 1c0ba3caed18
permissions -rw-r--r--
Use the default audio format for this endianness
slouken@34
     1
/*
slouken@34
     2
    MIXERLIB:  An audio mixer library based on the SDL library
slouken@34
     3
    Copyright (C) 1997-1999  Sam Lantinga
slouken@34
     4
slouken@34
     5
    This library is free software; you can redistribute it and/or
slouken@34
     6
    modify it under the terms of the GNU Library General Public
slouken@34
     7
    License as published by the Free Software Foundation; either
slouken@34
     8
    version 2 of the License, or (at your option) any later version.
slouken@34
     9
slouken@34
    10
    This library is distributed in the hope that it will be useful,
slouken@34
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@34
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@34
    13
    Library General Public License for more details.
slouken@34
    14
slouken@34
    15
    You should have received a copy of the GNU Library General Public
slouken@34
    16
    License along with this library; if not, write to the Free
slouken@34
    17
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
slouken@34
    18
slouken@34
    19
    Sam Lantinga
slouken@34
    20
    5635-34 Springhouse Dr.
slouken@34
    21
    Pleasanton, CA 94588 (USA)
slouken@34
    22
    slouken@devolution.com
slouken@34
    23
*/
slouken@34
    24
slouken@34
    25
#ifndef _MIXER_H_
slouken@34
    26
#define _MIXER_H_
slouken@34
    27
slouken@34
    28
#include "SDL_types.h"
slouken@34
    29
#include "SDL_rwops.h"
slouken@34
    30
#include "SDL_audio.h"
slouken@70
    31
#include "SDL_byteorder.h"
slouken@40
    32
#include "begin_code.h"
slouken@34
    33
slouken@34
    34
/* Set up for C function definitions, even when using C++ */
slouken@34
    35
#ifdef __cplusplus
slouken@34
    36
extern "C" {
slouken@34
    37
#endif
slouken@34
    38
slouken@34
    39
/* The default mixer has 8 simultaneous mixing channels */
slouken@34
    40
#ifndef MIX_CHANNELS
slouken@34
    41
#define MIX_CHANNELS	8
slouken@34
    42
#endif
slouken@34
    43
slouken@34
    44
/* Good default values for a PC soundcard */
slouken@34
    45
#define MIX_DEFAULT_FREQUENCY	22050
slouken@70
    46
#if SDL_BYTEORDER == SDL_LIL_ENDIAN
slouken@70
    47
#define MIX_DEFAULT_FORMAT	AUDIO_S16LSB
slouken@70
    48
#else
slouken@70
    49
#define MIX_DEFAULT_FORMAT	AUDIO_S16MSB
slouken@70
    50
#endif
slouken@34
    51
#define MIX_DEFAULT_CHANNELS	2
slouken@34
    52
#define MIX_MAX_VOLUME		128	/* Volume of a chunk */
slouken@34
    53
slouken@34
    54
/* The internal format for an audio chunk */
slouken@34
    55
typedef struct {
slouken@34
    56
	int allocated;
slouken@34
    57
	Uint8 *abuf;
slouken@34
    58
	Uint32 alen;
slouken@34
    59
	Uint8 volume;		/* Per-sample volume, 0-128 */
slouken@34
    60
} Mix_Chunk;
slouken@34
    61
slouken@34
    62
/* The different fading types supported */
slouken@34
    63
typedef enum {
slouken@34
    64
	MIX_NO_FADING,
slouken@34
    65
	MIX_FADING_OUT,
slouken@34
    66
	MIX_FADING_IN
slouken@34
    67
} Mix_Fading;
slouken@34
    68
slouken@34
    69
/* The internal format for a music chunk interpreted via mikmod */
slouken@34
    70
typedef struct _Mix_Music Mix_Music;
slouken@34
    71
slouken@34
    72
/* Open the mixer with a certain audio format */
slouken@40
    73
extern DECLSPEC int Mix_OpenAudio(int frequency, Uint16 format, int channels,
slouken@34
    74
							int chunksize);
slouken@34
    75
slouken@34
    76
/* Dynamically change the number of channels managed by the mixer.
slouken@34
    77
   If decreasing the number of channels, the upper channels are
slouken@34
    78
   stopped.
slouken@34
    79
   This function returns the new number of allocated channels.
slouken@34
    80
 */
slouken@40
    81
extern DECLSPEC int Mix_AllocateChannels(int numchans);
slouken@34
    82
slouken@34
    83
/* Find out what the actual audio device parameters are.
slouken@34
    84
   This function returns 1 if the audio has been opened, 0 otherwise.
slouken@34
    85
 */
slouken@40
    86
extern DECLSPEC int Mix_QuerySpec(int *frequency,Uint16 *format,int *channels);
slouken@34
    87
slouken@34
    88
/* Load a wave file or a music (.mod .s3m .it .xm) file */
slouken@40
    89
extern DECLSPEC Mix_Chunk *Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
slouken@34
    90
#define Mix_LoadWAV(file)	Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1)
slouken@40
    91
extern DECLSPEC Mix_Music *Mix_LoadMUS(const char *file);
slouken@34
    92
slouken@59
    93
#if 0 /* This hasn't been hooked into music.c yet */
slouken@59
    94
/* Load a music file from an SDL_RWop object (MikMod-specific currently)
slouken@59
    95
   Matt Campbell (matt@campbellhome.dhs.org) April 2000 */
slouken@59
    96
extern DECLSPEC Mix_Music *Mix_LoadMUS_RW(SDL_RWops *rw);
slouken@59
    97
#endif
slouken@59
    98
slouken@34
    99
/* Load a wave file of the mixer format from a memory buffer */
slouken@40
   100
extern DECLSPEC Mix_Chunk *Mix_QuickLoad_WAV(Uint8 *mem);
slouken@34
   101
slouken@34
   102
/* Free an audio chunk previously loaded */
slouken@40
   103
extern DECLSPEC void Mix_FreeChunk(Mix_Chunk *chunk);
slouken@40
   104
extern DECLSPEC void Mix_FreeMusic(Mix_Music *music);
slouken@34
   105
slouken@34
   106
/* Set a function that is called after all mixing is performed.
slouken@34
   107
   This can be used to provide real-time visual display of the audio stream
slouken@34
   108
   or add a custom mixer filter for the stream data.
slouken@34
   109
*/
slouken@40
   110
extern DECLSPEC void Mix_SetPostMix(void (*mix_func)
slouken@34
   111
                             (void *udata, Uint8 *stream, int len), void *arg);
slouken@34
   112
slouken@34
   113
/* Add your own music player or additional mixer function.
slouken@34
   114
   If 'mix_func' is NULL, the default music player is re-enabled.
slouken@34
   115
 */
slouken@40
   116
extern DECLSPEC void Mix_HookMusic(void (*mix_func)
slouken@34
   117
                          (void *udata, Uint8 *stream, int len), void *arg);
slouken@34
   118
slouken@34
   119
/* Add your own callback when the music has finished playing.
slouken@34
   120
 */
slouken@40
   121
extern DECLSPEC void Mix_HookMusicFinished(void (*music_finished)(void));
slouken@34
   122
slouken@34
   123
/* Get a pointer to the user data for the current music hook */
slouken@40
   124
extern DECLSPEC void *Mix_GetMusicHookData(void);
slouken@34
   125
slouken@34
   126
/* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
slouken@34
   127
   them dynamically to the next sample if requested with a -1 value below.
slouken@34
   128
   Returns the number of reserved channels.
slouken@34
   129
 */
slouken@40
   130
extern DECLSPEC int Mix_ReserveChannels(int num);
slouken@34
   131
slouken@34
   132
/* Channel grouping functions */
slouken@34
   133
slouken@34
   134
/* Attach a tag to a channel. A tag can be assigned to several mixer
slouken@34
   135
   channels, to form groups of channels.
slouken@34
   136
   If 'tag' is -1, the tag is removed (actually -1 is the tag used to
slouken@34
   137
   represent the group of all the channels).
slouken@34
   138
   Returns true if everything was OK.
slouken@34
   139
 */
slouken@40
   140
extern DECLSPEC int Mix_GroupChannel(int which, int tag);
slouken@34
   141
/* Assign several consecutive channels to a group */
slouken@40
   142
extern DECLSPEC int Mix_GroupChannels(int from, int to, int tag);
slouken@34
   143
/* Finds the first available channel in a group of channels */
slouken@40
   144
extern DECLSPEC int Mix_GroupAvailable(int tag);
slouken@34
   145
/* Returns the number of channels in a group. This is also a subtle
slouken@34
   146
   way to get the total number of channels when 'tag' is -1
slouken@34
   147
 */
slouken@40
   148
extern DECLSPEC int Mix_GroupCount(int tag);
slouken@34
   149
/* Finds the "oldest" sample playing in a group of channels */
slouken@40
   150
extern DECLSPEC int Mix_GroupOldest(int tag);
slouken@34
   151
/* Finds the "most recent" (i.e. last) sample playing in a group of channels */
slouken@40
   152
extern DECLSPEC int Mix_GroupNewer(int tag);
slouken@34
   153
slouken@34
   154
/* Play an audio chunk on a specific channel.
slouken@34
   155
   If the specified channel is -1, play on the first free channel.
slouken@34
   156
   If 'loops' is greater than zero, loop the sound that many times.
slouken@34
   157
   If 'loops' is -1, loop inifinitely (~65000 times).
slouken@34
   158
   Returns which channel was used to play the sound.
slouken@34
   159
*/
slouken@34
   160
#define Mix_PlayChannel(channel,chunk,loops) Mix_PlayChannelTimed(channel,chunk,loops,-1)
slouken@34
   161
/* The same as above, but the sound is played at most 'ticks' milliseconds */
slouken@40
   162
extern DECLSPEC int Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
slouken@40
   163
extern DECLSPEC int Mix_PlayMusic(Mix_Music *music, int loops);
slouken@34
   164
slouken@34
   165
/* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions */
slouken@40
   166
extern DECLSPEC int Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
slouken@34
   167
#define Mix_FadeInChannel(channel,chunk,loops,ms) Mix_FadeInChannelTimed(channel,chunk,loops,ms,-1)
slouken@40
   168
extern DECLSPEC int Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
slouken@34
   169
slouken@34
   170
/* Set the volume in the range of 0-128 of a specific channel or chunk.
slouken@34
   171
   If the specified channel is -1, set volume for all channels.
slouken@34
   172
   Returns the original volume.
slouken@34
   173
   If the specified volume is -1, just return the current volume.
slouken@34
   174
*/
slouken@40
   175
extern DECLSPEC int Mix_Volume(int channel, int volume);
slouken@40
   176
extern DECLSPEC int Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
slouken@40
   177
extern DECLSPEC int Mix_VolumeMusic(int volume);
slouken@34
   178
slouken@34
   179
/* Halt playing of a particular channel */
slouken@40
   180
extern DECLSPEC int Mix_HaltChannel(int channel);
slouken@40
   181
extern DECLSPEC int Mix_HaltGroup(int tag);
slouken@40
   182
extern DECLSPEC int Mix_HaltMusic(void);
slouken@34
   183
slouken@34
   184
/* Change the expiration delay for a particular channel.
slouken@34
   185
   The sample will stop playing after the 'ticks' milliseconds have elapsed,
slouken@34
   186
   or remove the expiration if 'ticks' is -1
slouken@34
   187
*/
slouken@40
   188
extern DECLSPEC int Mix_ExpireChannel(int channel, int ticks);
slouken@34
   189
slouken@34
   190
/* Halt a channel, fading it out progressively till it's silent
slouken@34
   191
   The ms parameter indicates the number of milliseconds the fading
slouken@34
   192
   will take.
slouken@34
   193
 */
slouken@40
   194
extern DECLSPEC int Mix_FadeOutChannel(int which, int ms);
slouken@40
   195
extern DECLSPEC int Mix_FadeOutGroup(int tag, int ms);
slouken@40
   196
extern DECLSPEC int Mix_FadeOutMusic(int ms);
slouken@34
   197
slouken@34
   198
/* Query the fading status of a channel */
slouken@40
   199
extern DECLSPEC Mix_Fading Mix_FadingMusic(void);
slouken@40
   200
extern DECLSPEC Mix_Fading Mix_FadingChannel(int which);
slouken@34
   201
slouken@34
   202
/* Pause/Resume a particular channel */
slouken@40
   203
extern DECLSPEC void Mix_Pause(int channel);
slouken@40
   204
extern DECLSPEC void Mix_Resume(int channel);
slouken@40
   205
extern DECLSPEC int  Mix_Paused(int channel);
slouken@34
   206
slouken@34
   207
/* Pause/Resume the music stream */
slouken@40
   208
extern DECLSPEC void Mix_PauseMusic(void);
slouken@40
   209
extern DECLSPEC void Mix_ResumeMusic(void);
slouken@40
   210
extern DECLSPEC void Mix_RewindMusic(void);
slouken@40
   211
extern DECLSPEC int  Mix_PausedMusic(void);
slouken@34
   212
slouken@34
   213
/* Check the status of a specific channel.
slouken@34
   214
   If the specified channel is -1, check all channels.
slouken@34
   215
*/
slouken@40
   216
extern DECLSPEC int Mix_Playing(int channel);
slouken@40
   217
extern DECLSPEC int Mix_PlayingMusic(void);
slouken@34
   218
slouken@34
   219
/* Stop music and set external music playback command */
slouken@40
   220
extern DECLSPEC int Mix_SetMusicCMD(const char *command);
slouken@34
   221
slouken@34
   222
/* Close the mixer, halting all playing audio */
slouken@40
   223
extern DECLSPEC void Mix_CloseAudio(void);
slouken@34
   224
slouken@34
   225
/* We'll use SDL for reporting errors */
slouken@34
   226
#define Mix_SetError	SDL_SetError
slouken@34
   227
#define Mix_GetError	SDL_GetError
slouken@34
   228
slouken@34
   229
/* Ends C function definitions when using C++ */
slouken@34
   230
#ifdef __cplusplus
slouken@34
   231
};
slouken@34
   232
#endif
slouken@40
   233
#include "close_code.h"
slouken@34
   234
slouken@34
   235
#endif /* _MIXER_H_ */