<ul><li><a href="#NAME">NAME</a></li>
<li><a href="#CATEGORY">CATEGORY</a></li>
-<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a>
-<ul><li><a href="#PerlMixMusicHook">PerlMixMusicHook</a></li>
-<li><a href="#mix_audio">mix_audio</a></li>
-<li><a href="#load_WAV">load_WAV</a></li>
-<li><a href="#load_MUS">load_MUS</a></li>
-<li><a href="#free_music">free_music</a></li>
+<ul><li><a href="#load_MUS">load_MUS</a></li>
<li><a href="#hook_music">hook_music</a></li>
<li><a href="#hook_music_finished">hook_music_finished</a></li>
<li><a href="#get_music_hook_data">get_music_hook_data</a></li>
<li><a href="#play_music">play_music</a></li>
<li><a href="#fade_in_music">fade_in_music</a></li>
-<li><a href="#volume_music">volume_music</a></li>
-<li><a href="#halt_music">halt_music</a></li>
<li><a href="#fade_out_music">fade_out_music</a></li>
<li><a href="#fading_music">fading_music</a></li>
+<li><a href="#volume_music">volume_music</a></li>
+<li><a href="#halt_music">halt_music</a></li>
<li><a href="#pause_music">pause_music</a></li>
<li><a href="#resume_music">resume_music</a></li>
<li><a href="#rewind_music">rewind_music</a></li>
+<li><a href="#set_music_position">set_music_position</a></li>
<li><a href="#paused_music">paused_music</a></li>
-<li><a href="#playing_music">playing_music</a>
-</li>
+<li><a href="#playing_music">playing_music</a></li>
</ul>
</li>
+<li><a href="#AUTHOR">AUTHOR</a>
+</li>
</ul><hr />
<!-- INDEX END -->
<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
-<p>SDL::Mixer::Music -- SDL_Mixer music functions and bindings</p>
+<p>SDL::Mixer::Music - functions for music</p>
</div>
<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
<p>Mixer</p>
</div>
-<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="DESCRIPTION_CONTENT">
-
-</div>
<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="METHODS_CONTENT">
</div>
-<h2 id="PerlMixMusicHook">PerlMixMusicHook</h2>
-<div id="PerlMixMusicHook_CONTENT">
-
-</div>
-<h2 id="mix_audio">mix_audio</h2>
-<div id="mix_audio_CONTENT">
-<p>Same as SDL::Audio::mix()</p>
-
-</div>
-<h2 id="load_WAV">load_WAV</h2>
-<div id="load_WAV_CONTENT">
-<p>has to be implemented</p>
-
-</div>
<h2 id="load_MUS">load_MUS</h2>
<div id="load_MUS_CONTENT">
<pre> my $music = SDL::Mixer::Music::load_MUS( $file );
</pre>
-<p><code>load_MUS</code> loads a music file into a <code>SDL::Music::MixMusic</code> structure. This can be passed to <a href="http://search.cpan.org/perldoc?play_music">play_music</a>.</p>
-
-</div>
-<h2 id="free_music">free_music</h2>
-<div id="free_music_CONTENT">
+<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>
</div>
<h2 id="hook_music">hook_music</h2>
<div id="hook_music_CONTENT">
+<pre> SDL::Mixer::Music::hook_music( $callback, $position );
+
+</pre>
+<p>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 <code>position</code> passed into the first parameter when the <code>callback</code> 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. </p>
+<p>To stop the custom music player call <code>hook_music()</code> without arguments.</p>
+<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>
+<p><strong>Note</strong>: At program termination also call <code>SDL::Mixer::Music::hook_music()</code> to stop this callback.</p>
+<p>Example:</p>
+<pre> 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 );
+
+</pre>
</div>
<h2 id="hook_music_finished">hook_music_finished</h2>
<div id="hook_music_finished_CONTENT">
+<pre> SDL::Mixer::Music::hook_music_finished( 'main::callback' );
+
+</pre>
+<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.
+This happens when the music is over or is fading out.</p>
+<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>
+<p>Example:</p>
+<pre> 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
+
+</pre>
</div>
<h2 id="get_music_hook_data">get_music_hook_data</h2>
<div id="get_music_hook_data_CONTENT">
+<pre> my $position = SDL::Mixer::Music::get_music_hook_data();
+
+</pre>
+<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>
</div>
<h2 id="play_music">play_music</h2>
<div id="play_music_CONTENT">
-<pre> my $play_music = SDL::Mixer::Music::play_music( $mix_music, $repeats );
+<pre> my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
</pre>
<p><code>play_music</code> plays a given <code>SDL::Mixer::MixMusic</code>.
-Passing -1 to <code>$repeats</code> will loop the music infinitely. </p>
+Passing -1 to <code>$loops</code> will loop the music infinitely. </p>
<p>Example:</p>
<pre> my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
print("Something went wrong!\n");
}
-
-
-
</pre>
</div>
<h2 id="fade_in_music">fade_in_music</h2>
<div id="fade_in_music_CONTENT">
-
-</div>
-<h2 id="volume_music">volume_music</h2>
-<div id="volume_music_CONTENT">
-
-</div>
-<h2 id="halt_music">halt_music</h2>
-<div id="halt_music_CONTENT">
-<pre> SDL::Mixer::Music::halt_music();
+<pre> my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
</pre>
-<p>Halts the music.</p>
+<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>
</div>
<h2 id="fade_out_music">fade_out_music</h2>
<div id="fade_out_music_CONTENT">
+<pre> my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
+
+</pre>
+<p><code>fade_out_music</code> fades out the music with a duration specified in <code>ms</code> in milliseconds.</p>
+<p>Returns the the number of channels that will be faded out.</p>
</div>
<h2 id="fading_music">fading_music</h2>
<div id="fading_music_CONTENT">
-<pre> my $fading_music = SDL::Mixer::Channels::fading_music();
+<pre> my $fading_music = SDL::Mixer::Music::fading_music();
</pre>
<p>Returns one of the following:</p>
</div>
+<h2 id="volume_music">volume_music</h2>
+<div id="volume_music_CONTENT">
+<pre> my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
+
+</pre>
+<p><code>volume_music</code> set the volume in <code>$new_volume</code> and returns the volume that was set before.
+Passing <code>-1</code> as argument causes only to return the current volume.</p>
+<p>Volume is between <code>0</code> (silence) and <code>MIX_MAX_VOLUME = 128</code>.</p>
+<p>Example:</p>
+<pre> # 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 ) );
+
+</pre>
+
+</div>
+<h2 id="halt_music">halt_music</h2>
+<div id="halt_music_CONTENT">
+<pre> SDL::Mixer::Music::halt_music();
+
+</pre>
+<p>Halts the music.</p>
+
+</div>
<h2 id="pause_music">pause_music</h2>
<div id="pause_music_CONTENT">
<pre> SDL::Mixer::Music::pause_music();
</div>
<h2 id="resume_music">resume_music</h2>
<div id="resume_music_CONTENT">
-<pre>
-
-
- SDL::Mixer::Music::resume_music();
+<pre> SDL::Mixer::Music::resume_music();
</pre>
<p>Resumes the music.</p>
</div>
<h2 id="rewind_music">rewind_music</h2>
<div id="rewind_music_CONTENT">
-<pre>
+<pre> SDL::Mixer::Music::rewind_music();
+</pre>
+<p>Rewinds the music.</p>
- SDL::Mixer::Music::rewind_music();
+</div>
+<h2 id="set_music_position">set_music_position</h2>
+<div id="set_music_position_CONTENT">
+<pre> SDL::Mixer::Music::set_music_position( $position );
</pre>
-<p>Rewinds the music.</p>
+<p>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.</p>
+<dl>
+ <dt>MOD</dt>
+ <dd>
+ <p>The double is cast to Uint16 and used for a pattern number in the module.
+Passing zero is similar to rewinding the song. </p>
+ </dd>
+ <dt>OGG</dt>
+ <dd>
+ <p>Jumps to position seconds from the beginning of the song. </p>
+ </dd>
+ <dt>MP3</dt>
+ <dd>
+ <p>Jumps to position seconds from the current position in the stream.
+So you may want to call <a href="/SDL-Mixer-Music.html#rewind_music">SDL::Mixer::Music::rewind_music</a> before this.
+Does not go in reverse... negative values do nothing. </p>
+ </dd>
+</dl>
+<p>Returns: <code>0</code> on success, or <code>-1</code> if the codec doesn't support this function. </p>
</div>
<h2 id="paused_music">paused_music</h2>
<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>
</div>
+<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="AUTHOR_CONTENT">
+<p>Tobias Leich [FROGGS]</p>
+
+</div>
</div>
\ No newline at end of file
projects / sdlgit/SDL-Site.git / blobdiff