3 <h3 id="TOP">Index</h3>
5 <ul><li><a href="#NAME">NAME</a></li>
6 <li><a href="#CATEGORY">CATEGORY</a></li>
7 <li><a href="#METHODS">METHODS</a>
8 <ul><li><a href="#load_MUS">load_MUS</a></li>
9 <li><a href="#hook_music">hook_music</a></li>
10 <li><a href="#hook_music_finished">hook_music_finished</a></li>
11 <li><a href="#get_music_hook_data">get_music_hook_data</a></li>
12 <li><a href="#play_music">play_music</a></li>
13 <li><a href="#fade_in_music">fade_in_music</a></li>
14 <li><a href="#fade_out_music">fade_out_music</a></li>
15 <li><a href="#fading_music">fading_music</a></li>
16 <li><a href="#volume_music">volume_music</a></li>
17 <li><a href="#halt_music">halt_music</a></li>
18 <li><a href="#pause_music">pause_music</a></li>
19 <li><a href="#resume_music">resume_music</a></li>
20 <li><a href="#rewind_music">rewind_music</a></li>
21 <li><a href="#set_music_position">set_music_position</a></li>
22 <li><a href="#paused_music">paused_music</a></li>
23 <li><a href="#playing_music">playing_music</a></li>
26 <li><a href="#AUTHOR">AUTHOR</a>
31 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
32 <div id="NAME_CONTENT">
33 <p>SDL::Mixer::Music - functions for music</p>
36 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
37 <div id="CATEGORY_CONTENT">
41 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
42 <div id="METHODS_CONTENT">
45 <h2 id="load_MUS">load_MUS</h2>
46 <div id="load_MUS_CONTENT">
47 <pre> my $music = SDL::Mixer::Music::load_MUS( $file );
50 <p><code>load_MUS</code> loads a music file into a <code>SDL::Mixer::MixMusic</code> structure. This can be passed to <a href="/SDL-Mixer-Music.html#play_music">SDL::Mixer::Music::play_music</a>.</p>
53 <h2 id="hook_music">hook_music</h2>
54 <div id="hook_music_CONTENT">
55 <pre> SDL::Mixer::Music::hook_music( $callback, $position );
58 <p>This sets up a custom music player function, so you can pass your own audio stream data into the SDL::Mixer.
59 The function will be called with <code>position</code> passed into the first parameter when the <code>callback</code> is called.
60 The audio stream buffer has to be filled with length bytes of music (2nd parameter).
61 The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called.
62 All the music playing and stopping functions have no effect on music after this. Pause and resume will work.
63 Using a custom music player and the internal music player is not possible, the custom music player takes priority. </p>
64 <p>To stop the custom music player call <code>hook_music()</code> without arguments.</p>
65 <p><strong>Note</strong>: NEVER call <code>SDL::Mixer</code> functions, nor <a href="/SDL-Audio.html#lock">SDL::Audio::lock</a>, from a callback function.</p>
66 <p><strong>Note</strong>: At program termination also call <code>SDL::Mixer::Music::hook_music()</code> to stop this callback.</p>
70 my $position = shift; # position (first time its 0, on each call $length is added)
71 my $length = shift; # length of bytes we have to put in stream
74 printf("position=%8d, stream length=%6d\n", $position, $length);
76 for(my $i = 0; $i < $length; $i++)
78 push(@stream, (($i + $position) & 0xFF));
84 SDL::Mixer::Music::hook_music( 'main::callback', 0 );
89 <h2 id="hook_music_finished">hook_music_finished</h2>
90 <div id="hook_music_finished_CONTENT">
91 <pre> SDL::Mixer::Music::hook_music_finished( 'main::callback' );
94 <p>This callback is called when music called by e.g. <a href="/SDL-Mixer-Music.html#play_music">SDL::Mixer::Music::play_music</a> or <a href="/SDL-Mixer-Music.html#fade_in_music">SDL::Mixer::Music::fade_in_music</a> stops naturally.
95 This happens when the music is over or is fading out.</p>
96 <p><strong>Note</strong>: If you play music via <a href="/SDL-Mixer-Music.html#hook_music">SDL::Mixer::Music::hook_music</a>, this callback will never be called.</p>
98 <pre> my $music_is_playing = 0;
99 my @music = qw(first.mp3 next.mp3 other.mp3 last.mp3);
102 $music_is_playing = 0;
105 SDL::Mixer::Music::hook_music_finished( 'main::callback' );
107 foreach my $this_song ( @music )
109 SDL::Mixer::Music::play_music( $this_song, 0 );
110 $music_is_playing = 1;
112 SDL::delay( 100 ) while( $music_is_playing );
115 SDL::Mixer::Music::hook_music_finished(); # cleanup
120 <h2 id="get_music_hook_data">get_music_hook_data</h2>
121 <div id="get_music_hook_data_CONTENT">
122 <pre> my $position = SDL::Mixer::Music::get_music_hook_data();
125 <p>Returns the <code>position</code> (first) parameter that will be passed to <a href="/SDL-Mixer-Music.html#hook_music">SDL::Mixer::Music::hook_music</a>'s callback.</p>
128 <h2 id="play_music">play_music</h2>
129 <div id="play_music_CONTENT">
130 <pre> my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
133 <p><code>play_music</code> plays a given <code>SDL::Mixer::MixMusic</code>.
134 Passing -1 to <code>$loops</code> will loop the music infinitely. </p>
136 <pre> my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
138 unless(SDL::Mixer::Music::play_music($sample_music, -1))
140 print("Something went wrong!\n");
146 <h2 id="fade_in_music">fade_in_music</h2>
147 <div id="fade_in_music_CONTENT">
148 <pre> my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
151 <p>Same as <a href="/SDL-Mixer-Music.html#play_music">SDL::Mixer::Music::play_music</a> but you can specify the fade-in time by <code>$ms</code>.</p>
154 <h2 id="fade_out_music">fade_out_music</h2>
155 <div id="fade_out_music_CONTENT">
156 <pre> my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
159 <p><code>fade_out_music</code> fades out the music with a duration specified in <code>ms</code> in milliseconds.</p>
160 <p>Returns the the number of channels that will be faded out.</p>
163 <h2 id="fading_music">fading_music</h2>
164 <div id="fading_music_CONTENT">
165 <pre> my $fading_music = SDL::Mixer::Music::fading_music();
168 <p>Returns one of the following:</p>
170 <li>MIX_NO_FADING </li>
171 <li>MIX_FADING_OUT </li>
172 <li>MIX_FADING_IN</li>
177 <h2 id="volume_music">volume_music</h2>
178 <div id="volume_music_CONTENT">
179 <pre> my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
182 <p><code>volume_music</code> set the volume in <code>$new_volume</code> and returns the volume that was set before.
183 Passing <code>-1</code> as argument causes only to return the current volume.</p>
184 <p>Volume is between <code>0</code> (silence) and <code>MIX_MAX_VOLUME = 128</code>.</p>
186 <pre> # set the music volume to 1/2 maximum, and then check it
187 printf( "volume was : %d\n", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
188 printf( "volume is now : %d\n", SDL::Mixer::Music::volume_music( -1 ) );
193 <h2 id="halt_music">halt_music</h2>
194 <div id="halt_music_CONTENT">
195 <pre> SDL::Mixer::Music::halt_music();
198 <p>Halts the music.</p>
201 <h2 id="pause_music">pause_music</h2>
202 <div id="pause_music_CONTENT">
203 <pre> SDL::Mixer::Music::pause_music();
206 <p>Pauses the music.</p>
209 <h2 id="resume_music">resume_music</h2>
210 <div id="resume_music_CONTENT">
211 <pre> SDL::Mixer::Music::resume_music();
214 <p>Resumes the music.</p>
217 <h2 id="rewind_music">rewind_music</h2>
218 <div id="rewind_music_CONTENT">
219 <pre> SDL::Mixer::Music::rewind_music();
222 <p>Rewinds the music.</p>
225 <h2 id="set_music_position">set_music_position</h2>
226 <div id="set_music_position_CONTENT">
227 <pre> SDL::Mixer::Music::set_music_position( $position );
230 <p>Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the
231 music sources listed below.</p>
235 <p>The double is cast to Uint16 and used for a pattern number in the module.
236 Passing zero is similar to rewinding the song. </p>
240 <p>Jumps to position seconds from the beginning of the song. </p>
244 <p>Jumps to position seconds from the current position in the stream.
245 So you may want to call <a href="/SDL-Mixer-Music.html#rewind_music">SDL::Mixer::Music::rewind_music</a> before this.
246 Does not go in reverse... negative values do nothing. </p>
249 <p>Returns: <code>0</code> on success, or <code>-1</code> if the codec doesn't support this function. </p>
252 <h2 id="paused_music">paused_music</h2>
253 <div id="paused_music_CONTENT">
254 <pre> my $paused = SDL::Mixer::Music::paused_music();
257 <p>Returns <code>1</code> if the music is paused, otherwise <code>0</code>.</p>
260 <h2 id="playing_music">playing_music</h2>
261 <div id="playing_music_CONTENT">
262 <pre> my $playing_music = SDL::Mixer::Music::playing_music();
265 <p>Returns <code>1</code> if the music is playing sound, otherwise <code>0</code>. It does'nt check if the music is paused.</p>
268 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
269 <div id="AUTHOR_CONTENT">
270 <p>Tobias Leich [FROGGS]</p>