mixer.h
author Stephane Peter
Sat, 30 Oct 1999 22:57:49 +0000
changeset 11 3939a99bf422
parent 10 2fbd0414a1fc
child 13 1e489d8b97d8
permissions -rw-r--r--
Various bugfixes for music looping
     1 /*
     2     MIXERLIB:  An audio mixer library based on the SDL library
     3     Copyright (C) 1997-1999  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     5635-34 Springhouse Dr.
    21     Pleasanton, CA 94588 (USA)
    22     slouken@devolution.com
    23 */
    24 
    25 #ifndef _MIXER_H_
    26 #define _MIXER_H_
    27 
    28 #include <SDL/SDL_types.h>
    29 #include <SDL/SDL_rwops.h>
    30 #include <SDL/SDL_audio.h>
    31 
    32 #include <SDL/begin_code.h>
    33 
    34 /* Set up for C function definitions, even when using C++ */
    35 #ifdef __cplusplus
    36 extern "C" {
    37 #endif
    38 
    39 /* The default mixer has 8 simultaneous mixing channels */
    40 #ifndef MIX_CHANNELS
    41 #define MIX_CHANNELS	8
    42 #endif
    43 
    44 /* Good default values for a PC soundcard */
    45 #define MIX_DEFAULT_FREQUENCY	22050
    46 #define MIX_DEFAULT_FORMAT	AUDIO_S16
    47 #define MIX_DEFAULT_CHANNELS	2
    48 #define MIX_MAX_VOLUME		128	/* Volume of a chunk */
    49 
    50 /* The internal format for an audio chunk */
    51 typedef struct {
    52 	int allocated;
    53 	Uint8 *abuf;
    54 	Uint32 alen;
    55 	Uint8 volume;		/* Per-sample volume, 0-128 */
    56 } Mix_Chunk;
    57 
    58 /* The different fading types supported */
    59 typedef enum {
    60 	MIX_NO_FADING,
    61 	MIX_FADING_OUT,
    62 	MIX_FADING_IN
    63 } Mix_Fading;
    64 
    65 /* The internal format for a music chunk interpreted via mikmod */
    66 typedef struct _Mix_Music Mix_Music;
    67 
    68 /* Open the mixer with a certain audio format */
    69 extern int Mix_OpenAudio(int frequency, Uint16 format, int channels,
    70 							int chunksize);
    71 
    72 /* Dynamically change the number of channels managed by the mixer.
    73    If decreasing the number of channels, the upper channels are
    74    stopped.
    75    This function returns the new number of allocated channels.
    76  */
    77 extern int Mix_AllocateChannels(int numchans);
    78 
    79 /* Find out what the actual audio device parameters are.
    80    This function returns 1 if the audio has been opened, 0 otherwise.
    81  */
    82 extern int Mix_QuerySpec(int *frequency, Uint16 *format, int *channels);
    83 
    84 /* Load a wave file or a music (.mod .s3m .it .xm) file */
    85 extern Mix_Chunk *Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
    86 #define Mix_LoadWAV(file)	Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1)
    87 extern Mix_Music *Mix_LoadMUS(const char *file);
    88 
    89 /* Load a wave file of the mixer format from a memory buffer */
    90 extern Mix_Chunk *Mix_QuickLoad_WAV(Uint8 *mem);
    91 
    92 /* Free an audio chunk previously loaded */
    93 extern void Mix_FreeChunk(Mix_Chunk *chunk);
    94 extern void Mix_FreeMusic(Mix_Music *music);
    95 
    96 /* Add your own music player or additional mixer function.
    97    If 'mix_func' is NULL, the default music player is re-enabled.
    98  */
    99 extern void Mix_HookMusic(void (*mix_func)(void *udata, Uint8 *stream, int len),
   100                                                                 void *arg);
   101 
   102 /* Get a pointer to the user data for the current music hook */
   103 extern void *Mix_GetMusicHookData(void);
   104 
   105 /* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
   106    them dynamically to the next sample if requested with a -1 value below.
   107    Returns the number of reserved channels.
   108  */
   109 extern int Mix_ReserveChannels(int num);
   110 
   111 /* Channel grouping functions */
   112 
   113 /* Attach a tag to a channel. A tag can be assigned to several mixer
   114    channels, to form groups of channels.
   115    If 'tag' is -1, the tag is removed (actually -1 is the tag used to
   116    represent the group of all the channels).
   117    Returns true if everything was OK.
   118  */
   119 extern int Mix_GroupChannel(int which, int tag);
   120 /* Assign several consecutive channels to a group */
   121 extern int Mix_GroupChannels(int from, int to, int tag);
   122 /* Finds the first available channel in a group of channels */
   123 extern int Mix_GroupAvailable(int tag);
   124 /* Returns the number of channels in a group. This is also a subtle
   125    way to get the total number of channels when 'tag' is -1
   126  */
   127 extern int Mix_GroupCount(int tag);
   128 /* Finds the "oldest" sample playing in a group of channels */
   129 extern int Mix_GroupOldest(int tag);
   130 /* Finds the "most recent" (i.e. last) sample playing in a group of channels */
   131 extern int Mix_GroupNewer(int tag);
   132 
   133 /* Play an audio chunk on a specific channel.
   134    If the specified channel is -1, play on the first free channel.
   135    If 'loops' is greater than zero, loop the sound that many times.
   136    If 'loops' is -1, loop inifinitely (~65000 times).
   137    Returns which channel was used to play the sound.
   138 */
   139 #define Mix_PlayChannel(channel,chunk,loops) Mix_PlayChannelTimed(channel,chunk,loops,-1)
   140 /* The same as above, but the sound is played at most 'ticks' milliseconds */
   141 extern int Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
   142 extern int Mix_PlayMusic(Mix_Music *music, int loops);
   143 
   144 /* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions */
   145 extern int Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
   146 #define Mix_FadeInChannel(channel,chunk,loops,ms) Mix_FadeInChannelTimed(channel,chunk,loops,ms,-1)
   147 extern int Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
   148 
   149 /* Fades out the currently playing music, and progressively fades in a new music,
   150    all in the background. The 'ms' period is half for fading out the music and
   151    fading in the new one */
   152 extern int Mix_FadeOutInMusic(Mix_Music *music, int loops, int ms);
   153 
   154 /* Set the volume in the range of 0-128 of a specific channel or chunk.
   155    If the specified channel is -1, set volume for all channels.
   156    Returns the original volume.
   157    If the specified volume is -1, just return the current volume.
   158 */
   159 extern int Mix_Volume(int channel, int volume);
   160 extern int Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
   161 extern int Mix_VolumeMusic(int volume);
   162 
   163 /* Halt playing of a particular channel */
   164 extern int Mix_HaltChannel(int channel);
   165 extern int Mix_HaltGroup(int tag);
   166 extern int Mix_HaltMusic(void);
   167 
   168 /* Change the expiration delay for a particular channel.
   169    The sample will stop playing after the 'ticks' milliseconds have elapsed,
   170    or remove the expiration if 'ticks' is -1
   171 */
   172 extern int Mix_ExpireChannel(int channel, int ticks);
   173 
   174 /* Halt a channel, fading it out progressively till it's silent 
   175    The ms parameter indicates the number of milliseconds the fading
   176    will take.
   177  */
   178 extern int Mix_FadeOutChannel(int which, int ms);
   179 extern int Mix_FadeOutGroup(int tag, int ms);
   180 extern int Mix_FadeOutMusic(int ms);
   181 
   182 /* Query the fading status of a channel */
   183 extern Mix_Fading Mix_FadingMusic(void);
   184 extern Mix_Fading Mix_FadingChannel(int which);
   185 
   186 /* Pause/Resume a particular channel */
   187 extern void Mix_Pause(int channel);
   188 extern void Mix_Resume(int channel);
   189 
   190 /* Pause/Resume the music stream */
   191 extern void Mix_PauseMusic(void);
   192 extern void Mix_ResumeMusic(void);
   193 extern void Mix_RewindMusic(void);
   194 
   195 /* Check the status of a specific channel.
   196    If the specified channel is -1, check all channels.
   197 */
   198 extern int Mix_Playing(int channel);
   199 extern int Mix_PlayingMusic(void);
   200 
   201 /* Stop music and set external music playback command */
   202 extern int Mix_SetMusicCMD(const char *command);
   203 
   204 /* Close the mixer, halting all playing audio */
   205 extern void Mix_CloseAudio(void);
   206 
   207 /* We'll use SDL for reporting errors */
   208 #define Mix_SetError	SDL_SetError
   209 #define Mix_GetError	SDL_GetError
   210 
   211 /* Ends C function definitions when using C++ */
   212 #ifdef __cplusplus
   213 };
   214 #endif
   215 #include <SDL/close_code.h>
   216 
   217 #endif /* _MIXER_H_ */