Samples
=======

These functions work with Mix_Chunk samples.

Mix_GetNumChunkDecoders
-----------------------

int Mix_GetNumChunkDecoders()

Get the number of sample chunk decoders available from the Mix_GetChunkDecoder function.  This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of sample chunk decoders available.

     // print the number of sample chunk decoders available
     printf("There are %d sample chunk deocoders available\n", Mix_GetNumChunkDecoders());

See Also:

Mix_GetNumMusicDecoders, Mix_GetChunkDecoder, Mix_HasChunkDecoder, Mix_LoadWAV

Mix_GetChunkDecoder
-------------------

const char *Mix_GetChunkDecoder(int INDEX)

index
     The index number of sample chunk decoder to get.

     In the range from 0(zero) to Mix_GetNumChunkDecoders()-1, inclusive.

Get the name of the INDEXed sample chunk decoder. You need to get the number of sample chunk decoders available using the Mix_GetNumChunkDecoders function.

Returns: The name of the INDEXed sample chunk decoder.  This string is owned by the SDL_mixer library, do not modify or free it.  It is valid until you call Mix_CloseAudio the final time.

     // print sample chunk decoders available
     int i,max=Mix_GetNumChunkDecoders();
     for(i=0; i<max; ++i)
     	printf("Sample chunk decoder %d is for %s",Mix_GetChunkDecoder(i));

See Also:

Mix_GetNumChunkDecoders, Mix_GetMusicDecoder, Mix_HasChunkDecoder, Mix_LoadWAV

Mix_HasChunkDecoder
-------------------

SDL_bool Mix_HasChunkDecoder(const char *NAME)

name
     The decoder name to check it's presence.

Check if the sample chunk decoder named as NAME presented in this library build.

Returns: SDL_TRUE if the requested codec name is available in this library build or SDL_FALSE if not.

See Also:

Mix_GetNumChunkDecoders, Mix_GetChunkDecoder, Mix_GetMusicDecoder, Mix_LoadWAV

Mix_LoadWAV
-----------

Mix_Chunk *Mix_LoadWAV(char *FILE)

file
     File name to load sample from.

Load FILE for use as a sample.  This is actually Mix_LoadWAV_RW(SDL_RWFromFile(FILE, "rb"), 1).  This can load WAVE, AIFF, RIFF, OGG, FLAC, MP3, and VOC files.

Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk.  NULL is returned on errors.

     // load sample.wav in to sample
     Mix_Chunk *sample;
     sample=Mix_LoadWAV("sample.wav");
     if(!sample) {
         printf("Mix_LoadWAV: %s\n", Mix_GetError());
         // handle error
     }

See Also:

Mix_LoadWAV_RW, Mix_QuickLoad_WAV, Mix_FreeChunk

Mix_LoadWAV_RW
--------------

Mix_Chunk *Mix_LoadWAV_RW(SDL_RWops *SRC, int FREESRC)

src
     The source SDL_RWops as a pointer.  The sample is loaded from this.

freesrc
     A non-zero value mean is will automatically close/free the SRC for you.

Load SRC for use as a sample.  This can load WAVE, AIFF, RIFF, OGG, FLAC, MP3, and VOC formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk.  NULL is returned on errors.

     // load sample.wav in to sample
     Mix_Chunk *sample;
     sample=Mix_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1);
     if(!sample) {
         printf("Mix_LoadWAV_RW: %s\n", Mix_GetError());
         // handle error
     }

See Also:

Mix_LoadWAV, Mix_QuickLoad_WAV, Mix_FreeChunk

Mix_QuickLoad_WAV
-----------------

Mix_Chunk *Mix_QuickLoad_WAV(Uint8 *MEM)

mem
     Memory buffer containing a WAVE file in output format.

Load MEM as a WAVE/RIFF file into a new sample.  The WAVE in MEM must be already in the output format.  It would be better to use Mix_LoadWAV_RW if you aren't sure.

Note: This function does very little checking.  If the format mismatches the output format, or if the buffer is not a WAVE, it will not return an error.  This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk.  NULL is returned on errors.

     // quick-load a wave from memory
     // Uint8 *wave; // I assume you have the wave loaded raw,
                     // or compiled in the program...
     Mix_Chunk *wave_chunk;
     if(!(wave_chunk=Mix_QuickLoad_WAV(wave))) {
         printf("Mix_QuickLoad_WAV: %s\n", Mix_GetError());
         // handle error
     }

See Also:

Mix_LoadWAV, Mix_QuickLoad_RAW, Mix_FreeChunk

Mix_QuickLoad_RAW
-----------------

Mix_Chunk *Mix_QuickLoad_RAW(Uint8 *MEM)

mem
     Memory buffer containing a WAVE file in output format.

Load MEM as a raw sample.  The data in MEM must be already in the output format.  If you aren't sure what you are doing, this is not a good function for you!

Note: This function does very little checking.  If the format mismatches the output format it will not return an error.  This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk.  NULL is returned on errors, such as when out of memory.

     // quick-load a raw sample from memory
     // Uint8 *raw; // I assume you have the raw data here,
                     // or compiled in the program...
     Mix_Chunk *raw_chunk;
     if(!(raw_chunk=Mix_QuickLoad_RAW(raw))) {
         printf("Mix_QuickLoad_RAW: %s\n", Mix_GetError());
         // handle error
     }

See Also:

Mix_LoadWAV, Mix_QuickLoad_WAV, Mix_FreeChunk

Mix_VolumeChunk
---------------

int Mix_VolumeChunk(Mix_Chunk *CHUNK, int VOLUME)

chunk
     Pointer to the Mix_Chunk to set the volume in.

volume
     The volume to use from 0 to MIX_MAX_VOLUME(128).

     If greater than MIX_MAX_VOLUME,
      then it will be set to MIX_MAX_VOLUME.

     If less than 0 then CHUNK->volume will not be set.

Set CHUNK->volume to VOLUME.

The volume setting will take effect when the chunk is used on a channel, being mixed into the output.

Returns: previous CHUNK->volume setting.  if you passed a negative value for VOLUME then this volume is still the current volume for the CHUNK.

     // set the sample's volume to 1/2
     // Mix_Chunk *sample;
     int previous_volume;
     previous_volume=Mix_VolumeChunk(sample, MIX_MAX_VOLUME/2);
     printf("previous_volume: %d\n", previous_volume);

See Also:

Mix_Chunk

Mix_FreeChunk
-------------

void Mix_FreeChunk(Mix_Chunk *CHUNK)

chunk
     Pointer to the Mix_Chunk to free.

Free the memory used in CHUNK, and free CHUNK itself as well. Do not use CHUNK after this without loading a new sample to it. Note: It's a bad idea to free a chunk that is still being played...

     // free the sample
     // Mix_Chunk *sample;
     Mix_FreeChunk(sample);
     sample=NULL; // to be safe...

See Also:

Mix_LoadWAV, Mix_LoadWAV_RW, Mix_QuickLoad_WAV,