pods::SDL::Mixer::MusiUser Contributed Perl Documentpods::SDL::Mixer::Music(3)NAME
SDL::Mixer::Music - functions for music
CATEGORY
Mixer
METHODS
load_MUS
my $music = SDL::Mixer::Music::load_MUS( $file );
"load_MUS" loads a music file into a "SDL::Mixer::MixMusic" structure.
This can be passed to play_music.
load_MUS_RW
my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );
"load_MUS_RW" does the same like "load_MUS" except that it accepts an
SDL::RWOps-object rather than a filename.
Example for loading music from a variable:
use SDL;
use SDL::Mixer;
use SDL::Mixer::Music;
use SDL::RWOps;
[...]
my $rwops = SDL::RWOps->new_const_mem( $scalar_holding_music );
my $music = SDL::Mixer::Music::load_MUS( $rwops );
Note: You need at least libSDL_mixer 1.2.7 for this feature.
hook_music
SDL::Mixer::Music::hook_music( $callback, $position );
This sets up a custom music player function, so you can pass your own
audio stream data into the SDL::Mixer. The function will be called
with "position" passed into the first parameter when the "callback" is
called. The audio stream buffer has to be filled with length bytes of
music (2nd parameter). 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 "hook_music()" without arguments.
Note: NEVER call "SDL::Mixer" functions, nor SDL::Audio::lock, from a
callback function.
Note: At program termination also call
"SDL::Mixer::Music::hook_music()" to stop this callback.
Example:
sub callback
{
my $position = shift; # position (first time its 0, on each call $length is added)
my $length = shift; # length of bytes we have to put in stream
my @stream = '';
printf("position=%8d, stream length=%6d\n", $position, $length);
for(my $i = 0; $i < $length; $i++)
{
push(@stream, (($i + $position) & 0xFF));
}
return @stream;
}
SDL::Mixer::Music::hook_music( 'main::callback', 0 );
hook_music_finished
SDL::Mixer::Music::hook_music_finished( 'main::callback' );
This callback is called when music called by e.g.
SDL::Mixer::Music::play_music or SDL::Mixer::Music::fade_in_music stops
naturally. This happens when the music is over or is fading out.
Note: If you play music via SDL::Mixer::Music::hook_music, this
callback will never be called.
Example:
my $music_is_playing = 0;
my @music = qw(first.mp3 next.mp3 other.mp3 last.mp3);
sub callback
{
$music_is_playing = 0;
}
SDL::Mixer::Music::hook_music_finished( 'main::callback' );
foreach my $this_song ( @music )
{
SDL::Mixer::Music::play_music( $this_song, 0 );
$music_is_playing = 1;
SDL::delay( 100 ) while( $music_is_playing );
}
SDL::Mixer::Music::hook_music_finished(); # cleanup
get_music_hook_data
my $position = SDL::Mixer::Music::get_music_hook_data();
Returns the "position" (first) parameter that will be passed to
SDL::Mixer::Music::hook_music's callback.
play_music
my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
"play_music" plays a given "SDL::Mixer::MixMusic". Passing -1 to
$loops will loop the music infinitely.
Example:
my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
unless(SDL::Mixer::Music::play_music($sample_music, -1))
{
print("Something went wrong!\n");
}
fade_in_music
my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
Same as SDL::Mixer::Music::play_music but you can specify the fade-in
time by $ms.
fade_out_music
my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
"fade_out_music" fades out the music with a duration specified in "ms"
in milliseconds.
Returns the the number of channels that will be faded out.
fading_music
my $fading_music = SDL::Mixer::Music::fading_music();
Returns one of the following:
· MIX_NO_FADING
· MIX_FADING_OUT
· MIX_FADING_IN
volume_music
my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
"volume_music" set the volume in $new_volume and returns the volume
that was set before. Passing "-1" as argument causes only to return
the current volume.
Volume is between 0 (silence) and "MIX_MAX_VOLUME = 128".
Example:
# set the music volume to 1/2 maximum, and then check it
printf( "volume was : %d\n", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
printf( "volume is now : %d\n", SDL::Mixer::Music::volume_music( -1 ) );
halt_music
SDL::Mixer::Music::halt_music();
Halts the music.
pause_music
SDL::Mixer::Music::pause_music();
Pauses the music.
resume_music
SDL::Mixer::Music::resume_music();
Resumes the music.
rewind_music
SDL::Mixer::Music::rewind_music();
Rewinds the music.
set_music_position
SDL::Mixer::Music::set_music_position( $position );
Set the position of the currently playing music. The position takes
different meanings for different music sources. It only works on the
music sources listed below.
MOD The double is cast to Uint16 and used for a pattern number in the
module. Passing zero is similar to rewinding the song.
OGG Jumps to position seconds from the beginning of the song.
MP3 Jumps to position seconds from the current position in the stream.
So you may want to call SDL::Mixer::Music::rewind_music before
this. Does not go in reverse... negative values do nothing.
Returns: 0 on success, or "-1" if the codec doesn't support this
function.
paused_music
my $paused = SDL::Mixer::Music::paused_music();
Returns 1 if the music is paused, otherwise 0.
playing_music
my $playing_music = SDL::Mixer::Music::playing_music();
Returns 1 if the music is playing sound, otherwise 0. It doesn't check
if the music is paused.
AUTHORS
See "AUTHORS" in SDL.
perl v5.18.1 2013-09-28 pods::SDL::Mixer::Music(3)
