pages/SDL-Mixer-Music.html-inc

   1 <div class="pod">
   2 <!-- INDEX START -->
   3 <h3 id="TOP">Index</h3>
   4
   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>
  24 </ul>
  25 </li>
  26 <li><a href="#AUTHOR">AUTHOR</a>
  27 </li>
  28 </ul><hr />
  29 <!-- INDEX END -->
  30
  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>
  34
  35 </div>
  36 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
  37 <div id="CATEGORY_CONTENT">
  38 <p>Mixer</p>
  39
  40 </div>
  41 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  42 <div id="METHODS_CONTENT">
  43
  44 </div>
  45 <h2 id="load_MUS">load_MUS</h2>
  46 <div id="load_MUS_CONTENT">
  47 <pre> my $music = SDL::Mixer::Music::load_MUS( $file );
  48
  49 </pre>
  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>
  51
  52 </div>
  53 <h2 id="hook_music">hook_music</h2>
  54 <div id="hook_music_CONTENT">
  55 <pre> SDL::Mixer::Music::hook_music( $callback, $position );
  56
  57 </pre>
  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>
  67 <p>Example:</p>
  68 <pre> sub callback
  69  {
  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
  72      my @stream   = '';
  73
  74      printf(&quot;position=%8d, stream length=%6d\n&quot;, $position, $length);
  75
  76      for(my $i = 0; $i &lt; $length; $i++)
  77      {
  78          push(@stream, (($i + $position) &amp; 0xFF));
  79      }
  80
  81      return @stream;
  82  }
  83
  84  SDL::Mixer::Music::hook_music( 'main::callback', 0 );
  85
  86 </pre>
  87
  88 </div>
  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( $callback );
  92
  93 </pre>
  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>
  97 <p>Example:</p>
  98 <pre> my $music_is_playing = 0;
  99  my @music            = qw(first.mp3 next.mp3 other.mp3 last.mp3);
 100  sub callback
 101  {
 102      $music_is_playing = 0;
 103  }
 104
 105  SDL::Mixer::Music::hook_music_finished( 'main::callback' );
 106
 107  foreach my $this_song ( @music )
 108  {
 109      SDL::Mixer::Music::play_music( $this_song, 0 );
 110      $music_is_playing = 1;
 111
 112      SDL::delay( 100 ) while( $music_is_playing );
 113  }
 114
 115  SDL::Mixer::Music::hook_music_finished(); # cleanup
 116
 117 </pre>
 118
 119 </div>
 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();
 123
 124 </pre>
 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>
 126
 127 </div>
 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 );
 131
 132 </pre>
 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>
 135 <p>Example:</p>
 136 <pre> my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
 137
 138  unless(SDL::Mixer::Music::play_music($sample_music, -1))
 139  {
 140      print(&quot;Something went wrong!\n&quot;);
 141  }
 142
 143 </pre>
 144
 145 </div>
 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 );
 149
 150 </pre>
 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>
 152
 153 </div>
 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 );
 157
 158 </pre>
 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>
 161
 162 </div>
 163 <h2 id="fading_music">fading_music</h2>
 164 <div id="fading_music_CONTENT">
 165 <pre> my $fading_music = SDL::Mixer::Music::fading_music();
 166
 167 </pre>
 168 <p>Returns one of the following:</p>
 169 <ul>
 170                 <li>MIX_NO_FADING       </li>
 171                 <li>MIX_FADING_OUT      </li>
 172                 <li>MIX_FADING_IN</li>
 173 </ul>
 174
 175
 176 </div>
 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 );
 180
 181 </pre>
 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>
 185 <p>Example:</p>
 186 <pre> # set the music volume to 1/2 maximum, and then check it
 187  printf( &quot;volume was    : %d\n&quot;, SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
 188  printf( &quot;volume is now : %d\n&quot;, SDL::Mixer::Music::volume_music( -1 ) );
 189
 190 </pre>
 191
 192 </div>
 193 <h2 id="halt_music">halt_music</h2>
 194 <div id="halt_music_CONTENT">
 195 <pre> SDL::Mixer::Music::halt_music();
 196
 197 </pre>
 198 <p>Halts the music.</p>
 199
 200 </div>
 201 <h2 id="pause_music">pause_music</h2>
 202 <div id="pause_music_CONTENT">
 203 <pre> SDL::Mixer::Music::pause_music();
 204
 205 </pre>
 206 <p>Pauses the music.</p>
 207
 208 </div>
 209 <h2 id="resume_music">resume_music</h2>
 210 <div id="resume_music_CONTENT">
 211 <pre> SDL::Mixer::Music::resume_music();
 212
 213 </pre>
 214 <p>Resumes the music.</p>
 215
 216 </div>
 217 <h2 id="rewind_music">rewind_music</h2>
 218 <div id="rewind_music_CONTENT">
 219 <pre> SDL::Mixer::Music::rewind_music();
 220
 221 </pre>
 222 <p>Rewinds the music.</p>
 223
 224 </div>
 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 );
 228
 229 </pre>
 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>
 232 <dl>
 233         <dt>MOD</dt>
 234         <dd>
 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>
 237         </dd>
 238         <dt>OGG</dt>
 239         <dd>
 240                 <p>Jumps to position seconds from the beginning of the song. </p>
 241         </dd>
 242         <dt>MP3</dt>
 243         <dd>
 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>
 247                 <p>Returns: <code>0</code> on success, or <code>-1</code> if the codec doesn't support this function. </p>
 248
 249 </div>
 250 <h2 id="paused_music">paused_music</h2>
 251 <div id="paused_music_CONTENT">
 252 <pre> my $paused = SDL::Mixer::Music::paused_music();
 253
 254 </pre>
 255                 <p>Returns <code>1</code> if the music is paused, otherwise <code>0</code>.</p>
 256
 257 </div>
 258 <h2 id="playing_music">playing_music</h2>
 259 <div id="playing_music_CONTENT">
 260 <pre> my $playing_music = SDL::Mixer::Music::playing_music();
 261
 262 </pre>
 263                 <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>
 264
 265 </div>
 266 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
 267 <div id="AUTHOR_CONTENT">
 268                 <p>Tobias Leich [FROGGS]</p>
 269
 270 </div>
 271 </div>