/ 
SDL2-FFI-0.08
River stage zero No dependents
/ SDL2::Mixer 
    IMG_Quit => [ [] ],
    #
    IMG_LoadTyped_RW => [ [ 'SDL_RWops', 'int', 'string' ], 'SDL_Surface' ],
    IMG_Load         => [ ['string'],                       'SDL_Surface' ],
    IMG_Load_RW      => [ [ 'SDL_RWops', 'int' ],           'SDL_Surface' ],
    #
    IMG_LoadTexture         => [ [ 'SDL_Renderer', 'string' ], 'SDL_Texture' ],
    IMG_LoadTexture_RW      => [ [ 'SDL_Renderer', 'SDL_RWops', 'int' ], 'SDL_Texture' ],
    IMG_LoadTextureTyped_RW =>
        [ [ 'SDL_Renderer', 'SDL_RWops', 'int', 'string' ], 'SDL_Texture' ],

    # Functions to detect a file type, given a seekable source
    IMG_isICO  => [ ['SDL_RWops'], 'int' ],
    IMG_isCUR  => [ ['SDL_RWops'], 'int' ],
    IMG_isBMP  => [ ['SDL_RWops'], 'int' ],
    IMG_isGIF  => [ ['SDL_RWops'], 'int' ],
    IMG_isJPG  => [ ['SDL_RWops'], 'int' ],
    IMG_isLBM  => [ ['SDL_RWops'], 'int' ],
    IMG_isPCX  => [ ['SDL_RWops'], 'int' ],
    IMG_isPNG  => [ ['SDL_RWops'], 'int' ],
    IMG_isPNM  => [ ['SDL_RWops'], 'int' ],
    IMG_isSVG  => [ ['SDL_RWops'], 'int' ],
    IMG_isTIF  => [ ['SDL_RWops'], 'int' ],
    IMG_isXCF  => [ ['SDL_RWops'], 'int' ],
    IMG_isXPM  => [ ['SDL_RWops'], 'int' ],
    IMG_isXV   => [ ['SDL_RWops'], 'int' ],
    IMG_isWEBP => [ ['SDL_RWops'], 'int' ],

    # Individual loading functions
    IMG_LoadICO_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadCUR_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadBMP_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadGIF_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadJPG_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadLBM_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadPCX_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadPNG_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadPNM_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadSVG_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadTGA_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadTIF_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadXCF_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadXPM_RW  => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadXV_RW   => [ ['SDL_RWops'], 'SDL_Surface' ],
    IMG_LoadWEBP_RW => [ ['SDL_RWops'], 'SDL_Surface' ],
    #
    IMG_ReadXPMFromArray => [
        ['string_array'],
        'SDL_Surface' => sub ( $inner, @lines ) {
            $inner->( ref $lines[0] eq 'ARRAY' ? @lines : \@lines );
        }
    ],

    # Individual saving functions
    IMG_SavePNG    => [ [ 'SDL_Surface', 'string' ],                  'int' ],
    IMG_SavePNG_RW => [ [ 'SDL_Surface', 'SDL_RWops', 'int' ],        'int' ],
    IMG_SaveJPG    => [ [ 'SDL_Surface', 'string', 'int' ],           'int' ],
    IMG_SaveJPG_RW => [ [ 'SDL_Surface', 'SDL_RWops', 'int', 'int' ], 'int' ]
};
if ( SDL_IMAGE_VERSION_ATLEAST( 2, 0, 6 ) ) {

    # Currently on Github but not in a stable dist
    # https://github.com/libsdl-org/SDL_image/issues/182
    package SDL2::Image::Animation {
        use SDL2::Utils;
        use experimental 'signatures';
        #
        our $TYPE = has
            w       => 'int',
            h       => 'int',
            count   => 'int',
            _frames => 'opaque',    # SDL_Surface **
            _delays => 'opaque'     # int *
            ;

        sub frames ($s) {
            [ map { ffi->cast( 'opaque', 'SDL_Surface', $_ ) }
                    @{ ffi->cast( 'opaque', 'opaque[' . $s->count . ']', $s->_frames ) } ];
        }

        sub delays ($s) {
            ffi->cast( 'opaque', 'int[' . $s->count . ']', $s->_delays );
        }
    };
    attach image => {
        IMG_LoadAnimation         => [ ['string'],             'SDL_Image_Animation' ],
        IMG_LoadAnimation_RW      => [ [ 'SDL_RWops', 'int' ], 'SDL_Image_Animation' ],
        IMG_LoadAnimationTyped_RW =>
            [ [ 'SDL_RWops', 'int', 'string' ], 'SDL_Image_Animation' ],
        IMG_FreeAnimation       => [ ['SDL_Image_Animation'] ],
        IMG_LoadGIFAnimation_RW => [ ['SDL_RWops'], 'SDL_Image_Animation' ]
    };
}

NAME

SDL2::Mixer - SDL Audio Library

SYNOPSIS

use SDL2::Mixer;

DESCRIPTION

SDL2::Mixer wraps the SDL_mixer library, a simple multi-channel audio mixer.

It supports 8 channels of 16 bit stereo audio, plus a single channel of music, mixed by the popular MikMod MOD, Timidity MIDI and SMPEG MP3 libraries.

The mixer can currently load Microsoft WAVE files and Creative Labs VOC files as audio samples, and can load MIDI files via Timidity and the following music formats via MikMod: .MOD .S3M .IT .XM. It can load Ogg Vorbis streams as music if built with the Ogg Vorbis libraries, and finally it can load MP3 music using the SMPEG library.

The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.

Conflicts

When using SDL_mixer functions you need to avoid the following functions from SDL:

SDL_OpenAudio( )

Use Mix_OpenAudio instead.

SDL_CloseAudio( )

Use Mix_CloseAudio instead.

SDL_PauseAudio( )

Use Mix_Pause( -1 ) and Mix_PauseMusic( ) instead, to pause.

Use Mix_Resume( -1 ) and Mix_ResumeMusic( ) instead, to unpause.

SDL_LockAudio( )

This is just not needed since SDL_mixer handles this for you.

Using it may cause problems as well.

SDL_UnlockAudio( )

This is just not needed since SDL_mixer handles this for you.

Using it may cause problems as well.

You may call the following functions freely:

SDL_AudioDriverName( ... )

This will still work as usual.

SDL_GetAudioStatus( )

This will still work, though it will likely return SDL_AUDIO_PLAYING even though SDL_mixer is just playing silence.

It is also a BAD idea to call SDL_mixer and SDL audio functions from a callback. Callbacks include Effects functions and other SDL_mixer audio hooks.

Functions

These may be imported by name or with the :all tag.

SDL_MIXER_VERSION( ... )

Macro to determine compile-time version of the SDL_mixer library.

Expected parameters include:

x - a pointer to a SDL2::Version struct to initialize

SDL_MIXER_VERSION_ATLEAST( ... )

Evaluates to true if compiled with SDL_mixer at least major.minor.patch.

if ( SDL_MIXER_VERSION_ATLEAST( 2, 0, 5 ) ) {
	# Some feature that requires 2.0.5+
}

Expected parameters include:

major
minor
patch

Mix_Linked_Version( )

This function gets the version of the dynamically linked SDL_mixer library.

my $link_version = Mix_Linked_Version();
printf "running with SDL_mixer version: %d.%d.%d\n",
    $link_version->major, $link_version->minor, $link_version->patch;

It should NOT be used to fill a version structure, instead you should use the SDL_MIXER_VERSION( ... ) macro.

Returns a SDL2::Version object.

Mix_Init( ... )

Loads dynamic libraries and prepares them for use.

if ( !( Mix_Init(MIX_INIT_MP3) & MIX_INIT_MP3 ) ) {
    printf( "could not initialize sdl2_image: %s\n", IMG_GetError() );
    return !1;
}

You may call this multiple times, which will actually require you to call IMG_Quit( ) just once to clean up. You may call this function with a flags of 0 to retrieve whether support was built-in or not loaded yet.

Expected parameters include:

flags

Flags should be one or more flags from MIX_InitFlags OR'd together.

MIX_INIT_FLAC
MIX_INIT_FLAC
MIX_INIT_MP3
MIX_INIT_OGG
MIX_INIT_MID
MIX_INIT_OPUS

Returns the flags successfully initialized, or 0 on failure.

Mix_Quit( )

Unloads libraries loaded with Mix_Init( ... ).

Mix_OpenAudio( ... )

Initialize the mixer API.

# start SDL with audio support
if ( SDL_Init(SDL_INIT_AUDIO) == -1 ) {
    printf "SDL_Init: %s\n", SDL_GetError();
    exit 1;
}

# open 44.1KHz, signed 16bit, system byte order,
#      stereo audio, using 1024 byte chunks
if ( Mix_OpenAudio( 44100, MIX_DEFAULT_FORMAT, 2, 1024 ) == -1 ) {
    printf "Mix_OpenAudio: %s\n", Mix_GetError();
    exit 2;
}

This must be called before using other functions in this library.

SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050, because 44100 requires too much CPU power on older computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS( 8 ) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio( ) just as many times for the device to actually close. The format will not changed on subsequent calls until fully closed. So you will have to close all the way before trying to open with different format parameters.

Expected parameters include:

frequency - output sampling frequency in samples per second (Hz).

You might use MIX_DEFAULT_FREQUENCY (22050) since that is a good value for most games.

format - output sample format

This is based on SDL audio support. Here are the values listed in SDL_audio.h:

AUDIO_U8

Unsigned 8-bit samples

AUDIO_S8

Signed 8-bit samples

AUDIO_U16LSB

Unsigned 16-bit samples, in little-endian byte order

AUDIO_S16LSB

Signed 16-bit samples, in little-endian byte order

AUDIO_U16MSB

Unsigned 16-bit samples, in big-endian byte order

AUDIO_S16MSB

Signed 16-bit samples, in big-endian byte order

AUDIO_U16

same as AUDIO_U16LSB (for backwards compatibility probably)

AUDIO_S16

same as AUDIO_S16LSB (for backwards compatibility probably)

AUDIO_U16SYS

Unsigned 16-bit samples, in system byte order

AUDIO_S16SYS

Signed 16-bit samples, in system byte order

MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.

channels - number of sound channels to output

Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.

chunksize - bytes used per output sample

Returns 0 on success; -1 on errors.

Mix_OpenAudioDevice( ... )

Open the mixer with specific device and certain audio format

Expected parameters include:

frequency - output sampling frequency in samples per second (Hz).

You might use MIX_DEFAULT_FREQUENCY (22050) since that is a good value for most games.

format - output sample format
channels - number of sound channels to output

Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.

chunksize - bytes used per output sample
device - name of device to open
allowed_changes - 0 or one or more flags OR'd together

These values include the following:

SDL_AUDIO_ALLOW_FREQUENCY_CHANGE
SDL_AUDIO_ALLOW_FORMAT_CHANGE
SDL_AUDIO_ALLOW_CHANNELS_CHANGE
SDL_AUDIO_ALLOW_ANY_CHANGE

Returns a valid device ID that is <>0> on success or 0 on failure.

Mix_AllocateChannels( ... )

Set the number of channels being mixed.

Mix_AllocateChannels( 16 );

This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though.

If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

Expected parameters include:

numchans - number of channels to allocate for mixing

A negative number will not do anything. Use this to find out how many channels are currently allocated without modifying the count.

Returns the number of channels allocated. This should never fail but a high number of channels can segfault if you run out of memory.

Mix_QuerySpec( ... )

Find out what the actual audio device parameters are.

This may or may not match the parameters you passed to Mix_OpenAudio( ... ).

# get and print the audio format in use
my $numtimesopened = Mix_QuerySpec( \my ( $frequency, $format, $channels ) );
if ( !$numtimesopened ) {
    printf( "Mix_QuerySpec: %s\n", Mix_GetError() );
}
else {
    my $format_str
        = $format == AUDIO_U8   ? 'U8' :
        $format == AUDIO_S8     ? 'S8' :
        $format == AUDIO_U16LSB ? 'U16LSB' :
        $format == AUDIO_S16LSB ? 'S16LSB' :
        $format == AUDIO_U16MSB ? 'U16MSB' :
        $format == AUDIO_S16MSB ? 'S16MSB' :
        'Unknown';
    printf( "opened=%d times  frequency=%dHz  format=%s  channels=%d",
        $numtimesopened, $frequency, $format_str, $channels );
}

Expected parameters include:

frequency - pointer to an int where the frequency actually used by the opened audio device will be stored
format - pointer to a Uint16 where the output format actually being used by the audio device will be stored
channels - pointer to an int where the number of audio channels will be stored

2 will mean stereo, 1 will mean mono

Returns 0 on error. If the device was open, the number of times it was opened will be returned. The values of the arguments variables are not set on an error.

Mix_LoadWAV_RW( ... )

Load src for use as a sample.

my $sample = Mix_LoadWAV_RW( SDL_RWFromFile( $wav, 'rb' ), 1 );
if ( !$sample ) {
    printf( "Mix_LoadWAV_RW: %s\n", Mix_GetError() );
    # handle error
}

This can load WAVE, AIFF, RIFF, OGG, and VOC formats. Using SDL2::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.

Expected parameters include:

src - the source SDL2::RWops to load the sample from
freesrc - a non-zero value means we will automatically close/free the src for you

Returns a pointer to the sample as a SDL2::Mixer::Chunk object. undef is returned on errors.

Mix_LoadWAV( ... )

Load file for use as a sample.

# load sample.wav in to sample
my $sample = Mix_LoadWAV( 'sample.wav' );
if( !$sample ) {
	printf( "Mix_LoadWAV: %s\n", Mix_GetError() );
	# handle error
}

This is actually Mix_LoadWAV_RW( SDL_RWFromFile( $file, 'rb' ), 1 ). This can load WAVE, AIFF, RIFF, OGG, 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 SDL2::Mixer::Chunk object. undef is returned on errors.

Mix_LoadMUS( ... )

Load music file to use.

# load the MP3 file "music.mp3" to play as music
my $music = Mix_LoadMUS( 'music.mp3' );
if( !$music ) {
	printf( "Mix_LoadMUS( 'music.mp3' ): %s\n", Mix_GetError() );
	# this might be a critical error...
}

This can load WAVE, MOD, MIDI, OGG, MP3, FLAC, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD( ... ) before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD( undef ) to use the built-in players again.

Expected parameters include:

file - name of music file to use

Returns a pointer to the sample as a SDL2::Mixer::Music object. undef is returned on errors.

Mix_LoadMUS_RW( ... )

Load a music src from an SDL2::RWops object.

my $music = Mix_LoadMUS_RW( SDL_RWFromFile( $mp3, 'rb' ), 1 );
if ( !$music ) {
    printf( "Mix_LoadMUS_RW: %s\n", Mix_GetError() );
    # handle error
}

This can load WAVE, MOD, MIDI, OGG, MP3, FLAC, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD( ... ) before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD( undef ) to use the built-in players again.

Expected parameters include:

src - the source SDL2::RWops to load the music from
freesrc - a non-zero value means we will automatically close/free the src for you

Returns a pointer to the music as a SDL2::Mixer::Music object. undef is returned on errors.

Mix_LoadMUSType_RW( ... )

Load a music src from an SDL2::RWops object assuming a specific format.

my $music = Mix_LoadMUSType_RW( SDL_RWFromFile( $mp3, 'rb' ), MUS_MP3, 1 );
if ( !$music ) {
    printf( "Mix_LoadMUSType_RW: %s\n", Mix_GetError() );
    # handle error
}

This can load WAVE, MOD, MIDI, OGG, MP3, FLAC, and any file that you use a command to play with. If you are using an external command to play the music, you must call Mix_SetMusicCMD( ... ) before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD( undef ) to use the built-in players again.

Expected parameters include:

src - the source SDL2::RWops to load the music from
type - a specific format
freesrc - a non-zero value means we will automatically close/free the src for you

Returns a pointer to the music as a SDL2::Mixer::Music object. undef is returned on errors.

Mix_QuickLoad_WAV( ... )

Load mem as a WAVE/RIFF file into a new sample.

    # quick-load a wave from memory
    my $wave = ...; # I assume you have the wave loaded raw,
					# or compiled in the program...
					# or otherwise generated...
    if ( !( my $wave_chunk = Mix_QuickLoad_WAV($wave) ) ) {
        printf( "Mix_QuickLoad_WAV: %s\n", Mix_GetError() );

        # handle error
    }

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 SDL2::Mixer::Chunk object. undef is returned on errors.

Mix_QuickLoad_RAW( ... )

Load mem as a raw sample.

    # quick-load a wave from memory
    my $wave = ...; # I assume you have the wave loaded raw,
					# or compiled in the program...
					# or otherwise generated...
    if ( !( my $wave_chunk = Mix_QuickLoad_RAW($wave, length $wave) ) ) {
        printf( "Mix_QuickLoad_RAW: %s\n", Mix_GetError() );

        # handle error
    }

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, 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 SDL2::Mixer::Chunk object. undef is returned on errors.

Mix_FreeChunk( ... )

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_FreeChunk( $sample );
$sample = undef; # to be safe..

Expected parameters include:

chunk - pointer to the SDL2::Mixer::Chunk to free

Mix_FreeMusic( ... )

Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

# free music
Mix_FreeMusic( $music );
$music = undef; # to be safe..

Expected parameters include:

music - pointer to the SDL2::Mixer::Music to free

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.

printf("There are %d sample chunk deocoders available\n", Mix_GetNumChunkDecoders());

Returns the number of sample chunk decoders available.

Mix_GetChunkDecoder( ... )

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.

# print sample chunk decoders available
for my $i ( 0 .. Mix_GetNumChunkDecoders() - 1 ) {
	printf( "Sample chunk decoder %d is for %s", Mix_GetChunkDecoder($i) );
}

Appearing in this list doesn't promise your specific audio file will decode but it's handy to know if you have, say, a functioning Timidity install.

Expected parameters include:

index - the index number of sample chunk decoder to get

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

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.

Mix_HasChunkDecoder( ... )

Find out if you have a named chunk decoder.

Expected parameters include:

name - decoder name to query

Returns a true value if the given decoder is defined.

Mix_GetNumMusicDecoders( )

Get the number of music decoders available from the Mix_GetMusicDecoder( ... ) 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.

printf("There are %d music deocoders available\n", Mix_GetNumMusicDecoders());

Returns the number of music decoders available.

Mix_GetMusicDecoder( ... )

Get the name of the indexed sample music decoder. You need to get the number of sample music decoders available using the Mix_GetNumMusicDecoders( ) function.

# print sample music decoders available
for my $i ( 0 .. Mix_GetNumMusicDecoders() - 1 ) {
	printf( "Music decoder %d is for %s", Mix_GetMusicDecoder($i) );
}

Appearing in this list doesn't promise your specific audio file will decode but it's handy to know if you have, say, a functioning Timidity install.

Expected parameters include:

index - the index number of sample music decoder to get

In the range from 0 .. Mix_GetNumMusicDecoders()-1, inclusive.

Returns the name of the indexed sample music 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.

Mix_HasMusicDecoder( ... )

Find out if you have a named music decoder.

Expected parameters include:

name - decoder name to query

Returns a true value if the given decoder is defined.

Mix_GetMusicTitle( ... )

Get music title from meta-tag if possible. If title tag is empty, filename will be returned.

my $title = Mix_GetMusicTitle( $music );

Expected parameters include:

music - SDL2::Mixer::Music structure to query

Returns the title as a string.

Mix_GetMusicTitleTag( ... )

Get music title from meta-tag if possible.

my $title = Mix_GetMusicTitleTag( $music );

Expected parameters include:

music - SDL2::Mixer::Music structure to query

Returns the title as a string.

Mix_GetMusicArtistTag( ... )

Get music artist from meta-tag if possible.

my $artist = Mix_GetMusicArtistTag( $music );

Expected parameters include:

music - SDL2::Mixer::Music structure to query

Returns the artist as a string.

Mix_GetMusicAlbumTag( ... )

Get music album from meta-tag if possible.

my $album = Mix_GetMusicAlbumTag( $music );

Expected parameters include:

music - SDL2::Mixer::Music structure to query

Returns the artist as a string.

Mix_GetMusicCopyrightTag( ... )

Get music copyright from meta-tag if possible.

my $copyright = Mix_GetMusicCopyrightTag( $music );

Expected parameters include:

music - SDL2::Mixer::Music structure to query

Returns the artist as a string.

Mix_SetPostMix( ... )

Set a function that is called after all mixing is performed.

Mix_SetPostMix(
    sub { # Add a little background white noise to whatever is playing
        my ( $udata, $stream, $len ) = @_;
        $$stream->[$_] += rand $udata->{amp} for 0 .. $len;
    },
    { amp => 10 }
);

This can be used to provide real-time visual display of the audio stream or altering the stream to add an echo or other effects.

Expected parameters include:

mix_func - a function pointer for the postmix processor; undef unregisters the current postmixer
args - a pointer to data to pass into the mix_func's udata parameter.

It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.

This may be undef, depending on the processor.

There can only be one postmix function used at a time through this method. Use Mix_RegisterEffect( MIX_CHANNEL_POST, mix_func, undef, arg ) to use multiple postmix processors.

Note: This postmix processor is run after all the registered postmixers set up by Mix_RegisterEffect( ... ).

Mix_HookMusic( ... )

Set a custom music player function.

	my @ff = ...; # Some predefined music
    Mix_HookMusic(
        sub {
            my ( $udata, $stream, $len ) = @_;

            # fill buffer with...uh...music...
            $$stream->[$_] = $ff[ $_ + $udata->{pos} ] for 0 .. $len;

            # set udata for next time
            $udata->{pos} += $len;
        },
        { pos => 0 }
    );

This can be used to provide real-time visual display of the audio stream or altering the stream to add an echo or other effects.

Expected parameters include:

mix_func - a function pointer for the postmix processor; undef unregisters the current postmixer
args - a pointer to data to pass into the mix_func's udata parameter.

It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.

This may be undef, depending on the processor.

The function will be called with args passed into the udata parameter when the mix_func is called. The stream parameter passes in the audio stream buffer to be filled with len bytes of music. The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called. All the music playing and stopping functions have no effect on music after this. Pause and resume will work. Using a custom music player and the internal music player is not possible, the custom music player takes priority. To stop the custom music player call Mix_HookMusic(undef, undef).

Mix_HookMusicFinished( ... )

Add your own callback for when the music has finished playing or when it is stopped from a call to Mix_HaltMusic( ).

Mix_HookMusicFinished( sub { print "Music stopped.\n" } );

Any time music stops, the music_finished function will be called. Call with undef to remove the callback.

Expected parameters include:

music_finished - a function that should not expect any parameters or return anything

Mix_GetMusicHookData( )

Get the arg passed into Mix_HookMusic( ... ).

my $data = Mix_GetMusicHookData( );

Returns the arg pointer.

Mix_ChannelFinished( ... )

When channel playback is halted, then the specified channel_finished function is called. The channel parameter will contain the channel number that has finished.

Expected parameters include:

channel_finished - function to call when any channel finishes playback

Pass undef to disable callback.

The callback may be called from the mixer's audio callback or it could be called as a result of Mix_HaltChannel(), etc. do not call SDL_LockAudio( ) from this callback; you will either be inside the audio callback, or SDL_mixer will explicitly lock the audio before calling your callback.

Effects Functions

These functions are for special effects processing. Not all effects are all that special. All effects are post processing routines that are either built-in to SDL_mixer or created by you. Effects can be applied to individual channels, or to the final mixed stream which contains all the channels including music.

The built-in processors: Mix_SetPanning( ... ), Mix_SetPosition( ... ), Mix_SetDistance( ... ), and Mix_SetReverseStereo( ... ), all look for an environment variable, MIX_EFFECTSMAXSPEED to be defined. If the environment variable is defined these processors may use more memory or reduce the quality of the effects, all for better speed.

These functions may be imported by name or with the :effects tag.

Mix_RegisterEffect( ... )

Effects

These functions are for special effects processing. Not all effects are all that special. All effects are post processing routines that are either built-in to SDL_mixer or created by you. Effects can be applied to individual channels, or to the final mixed stream which contains all the channels including music.

Mix_SetError( ... )

Wrapper around SDL_SetError( ... ).

Mix_GetError( )

Wrapper around SDL_GetError( ).

Defined values and Enumerations

These might actually be useful and may be imported with the listed tags.

Version information

SDL_MIXER_MAJOR_VERSION
SDL_MIXER_MINOR_VERSION
SDL_MIXER_PATCHLEVEL
SDL_MIXER_COMPILEDVERSION - Version number for the current SDL_mixer version

MIX_InitFlags

MIX_INIT_FLAC
MIX_INIT_MOD
MIX_INIT_MP3
MIX_INIT_OGG
MIX_INIT_MID
MIX_INIT_OPUS

Mix_Fading

Enumeration of the different fading types supported by SDL_mixer.

MIX_NO_FADING
MIX_FADING_OUT
MIX_FADING_IN

Mix_MusicType

Enumeration of types of music files (not libraries used to load them).

MUS_NONE
MUS_CMD
MUS_WAV
MUS_MOD
MUS_MID
MUS_OGG
MUS_MP3
MUS_MP3_MAD_UNUSED
MUS_FLAC
MUS_MODPLUG_UNUSED
MUS_OPUS

Good default values

These are good default values for a PC soundcard. They may be imported by name or with the :defaults tag.

MIX_CHANNELS

The default mixer has 8 simultaneous mixing channels.

MIX_DEFAULT_FREQUENCY

44100 is a good default value for a PC soundcard.

MIX_DEFAULT_FORMAT

Based on your platform, this is AUDIO_S16.

MIX_DEFAULT_CHANNELS
MIX_MAX_VOLUME

Mix_Func

This is a callback which must expect the following parameters:

udata
stream - pointer to the stream data
len - length of the stream

channel_finished

This is a callback which must expect the following parameters:

channel - the channel number that has finished

MIX_CHANNEL_POST

In some built-in effects, setting channel to MIX_CHANNEL_POST registers the effect as a posteffect where it will be applied to the final mixed stream before passing it on to the audio device.

Mix_EffectFunc

This is the format of a special effect callback:

sub myeffect($chan, $stream, $len, $udata) { ... }

The callback should expect the following parameters:

chan - the channel number that your effect is affecting.
stream - the buffer of data to work upon
len - the size of stream
udata - a user-defined bit of data, which you pass as the last arg of Mix_RegisterEffect( ... ), and is passed back unmolested to your callback

Your effect changes the contents of stream based on whatever parameters are significant, or just leaves it be, if you prefer. You can do whatever you like to the buffer, though, and it will continue in its changed state down the mixing pipeline, through any other effect functions, then finally to be mixed with the rest of the channels and music for the final output stream.

DO NOT EVER call SDL_LockAudio( ) from your callback function!

Mix_EffectDone

This is a callback that signifies that a channel has finished all its loops and has completed playback. This gets called if the buffer plays out normally, or if you call Mix_HaltChannel( ... ), implicitly stop a channel via Mix_AllocateChannels( ... ), or unregister a callback while it's still playing.

Your callback should expect the following parameters:

chan - the channel number that this effect is effecting now
udata - user data pointer that was passed in to Mix_RegisterEffect( ... ) when registering this effect processor function

DO NOT EVER call SDL_LockAudio() from your callback function!

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>