SDL::Mixer::Music -- SDL_Mixer music functions and bindings
+SDL::Mixer::Music - functions for music
Mixer
-Same as SDL::Audio::mix()
- -has to be implemented
- -my $music = SDL::Mixer::Music::load_MUS( $file );-
load_MUS loads a music file into a SDL::Music::MixMusic structure. This can be passed to play_music.
load_MUS loads a music file into a SDL::Mixer::MixMusic structure. This can be passed to SDL::Mixer::Music::play_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 );
+
+
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
+
+
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.
my $play_music = SDL::Mixer::Music::play_music( $mix_music, $repeats ); +my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );+Passing -1 to
play_musicplays a givenSDL::Mixer::MixMusic. -Passing -1 to$repeatswill loop the music infinitely.$loopswill loop the music infinitely.Example:
my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' ); @@ -102,35 +140,29 @@ Passing -1 to$repeatswill loop the music infinitely. print("Something went wrong!\n"); } - - -
SDL::Mixer::Music::halt_music(); +my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );-Halts the music.
+Same as SDL::Mixer::Music::play_music but you can specify the fade-in time by
$ms.
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.
my $fading_music = SDL::Mixer::Channels::fading_music(); +my $fading_music = SDL::Mixer::Music::fading_music();Returns one of the following:
@@ -142,6 +174,30 @@ Passing -1 to$repeatswill loop the music infinitely.
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 ) ); + ++ +
SDL::Mixer::Music::halt_music(); + ++
Halts the music.
+ + SDL::Mixer::Music::pause_music();
@@ -152,10 +208,7 @@ Passing -1 to $repeats will loop the music infinitely.
- - - SDL::Mixer::Music::resume_music(); +SDL::Mixer::Music::resume_music();Resumes the music.
@@ -163,13 +216,37 @@ Passing -1 to$repeatswill loop the music infinitely.
+SDL::Mixer::Music::rewind_music(); ++Rewinds the music.
- SDL::Mixer::Music::rewind_music(); +
SDL::Mixer::Music::set_music_position( $position );-
Rewinds the music.
+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.
+The double is cast to Uint16 and used for a pattern number in the module. +Passing zero is similar to rewinding the song.
+Jumps to position seconds from the beginning of the song.
+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.
$repeats will loop the music infinitely.
Returns 1 if the music is playing sound, otherwise 0. It does'nt check if the music is paused.
See AUTHORS in SDL.
+ +