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="#AUTHORS">AUTHORS</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">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( 'main::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
  95 <a href="/SDL-Mixer-Music.html#fade_in_music">SDL::Mixer::Music::fade_in_music</a> stops naturally.
  96 This happens when the music is over or is fading out.</p>
  97 <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 <p>Example:</p>
  99 <pre> my $music_is_playing = 0;
 100  my @music            = qw(first.mp3 next.mp3 other.mp3 last.mp3);
 101  sub callback
 102  {
 103      $music_is_playing = 0;
 104  }
 105
 106  SDL::Mixer::Music::hook_music_finished( 'main::callback' );
 107
 108  foreach my $this_song ( @music )
 109  {
 110      SDL::Mixer::Music::play_music( $this_song, 0 );
 111      $music_is_playing = 1;
 112
 113      SDL::delay( 100 ) while( $music_is_playing );
 114  }
 115
 116  SDL::Mixer::Music::hook_music_finished(); # cleanup
 117
 118 </pre>
 119
 120 </div>
 121 <h2 id="get_music_hook_data">get_music_hook_data</h2>
 122 <div id="get_music_hook_data_CONTENT">
 123 <pre> my $position = SDL::Mixer::Music::get_music_hook_data();
 124
 125 </pre>
 126 <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>
 127
 128 </div>
 129 <h2 id="play_music">play_music</h2>
 130 <div id="play_music_CONTENT">
 131 <pre> my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
 132
 133 </pre>
 134 <p><code>play_music</code> plays a given <code>SDL::Mixer::MixMusic</code>.
 135 Passing -1 to <code>$loops</code> will loop the music infinitely. </p>
 136 <p>Example:</p>
 137 <pre> my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
 138
 139  unless(SDL::Mixer::Music::play_music($sample_music, -1))
 140  {
 141      print(&quot;Something went wrong!\n&quot;);
 142  }
 143
 144 </pre>
 145
 146 </div>
 147 <h2 id="fade_in_music">fade_in_music</h2>
 148 <div id="fade_in_music_CONTENT">
 149 <pre> my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
 150
 151 </pre>
 152 <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>
 153
 154 </div>
 155 <h2 id="fade_out_music">fade_out_music</h2>
 156 <div id="fade_out_music_CONTENT">
 157 <pre> my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
 158
 159 </pre>
 160 <p><code>fade_out_music</code> fades out the music with a duration specified in <code>ms</code> in milliseconds.</p>
 161 <p>Returns the the number of channels that will be faded out.</p>
 162
 163 </div>
 164 <h2 id="fading_music">fading_music</h2>
 165 <div id="fading_music_CONTENT">
 166 <pre> my $fading_music = SDL::Mixer::Music::fading_music();
 167
 168 </pre>
 169 <p>Returns one of the following:</p>
 170 <ul>
 171                 <li>MIX_NO_FADING       </li>
 172                 <li>MIX_FADING_OUT      </li>
 173                 <li>MIX_FADING_IN</li>
 174 </ul>
 175
 176
 177 </div>
 178 <h2 id="volume_music">volume_music</h2>
 179 <div id="volume_music_CONTENT">
 180 <pre> my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
 181
 182 </pre>
 183 <p><code>volume_music</code> set the volume in <code>$new_volume</code> and returns the volume that was set before.
 184 Passing <code>-1</code> as argument causes only to return the current volume.</p>
 185 <p>Volume is between <code>0</code> (silence) and <code>MIX_MAX_VOLUME = 128</code>.</p>
 186 <p>Example:</p>
 187 <pre> # set the music volume to 1/2 maximum, and then check it
 188  printf( &quot;volume was    : %d\n&quot;, SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
 189  printf( &quot;volume is now : %d\n&quot;, SDL::Mixer::Music::volume_music( -1 ) );
 190
 191 </pre>
 192
 193 </div>
 194 <h2 id="halt_music">halt_music</h2>
 195 <div id="halt_music_CONTENT">
 196 <pre> SDL::Mixer::Music::halt_music();
 197
 198 </pre>
 199 <p>Halts the music.</p>
 200
 201 </div>
 202 <h2 id="pause_music">pause_music</h2>
 203 <div id="pause_music_CONTENT">
 204 <pre> SDL::Mixer::Music::pause_music();
 205
 206 </pre>
 207 <p>Pauses the music.</p>
 208
 209 </div>
 210 <h2 id="resume_music">resume_music</h2>
 211 <div id="resume_music_CONTENT">
 212 <pre> SDL::Mixer::Music::resume_music();
 213
 214 </pre>
 215 <p>Resumes the music.</p>
 216
 217 </div>
 218 <h2 id="rewind_music">rewind_music</h2>
 219 <div id="rewind_music_CONTENT">
 220 <pre> SDL::Mixer::Music::rewind_music();
 221
 222 </pre>
 223 <p>Rewinds the music.</p>
 224
 225 </div>
 226 <h2 id="set_music_position">set_music_position</h2>
 227 <div id="set_music_position_CONTENT">
 228 <pre> SDL::Mixer::Music::set_music_position( $position );
 229
 230 </pre>
 231 <p>Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the
 232 music sources listed below.</p>
 233 <dl>
 234         <dt>MOD</dt>
 235         <dd>
 236                 <p>The double is cast to Uint16 and used for a pattern number in the module.
 237 Passing zero is similar to rewinding the song. </p>
 238         </dd>
 239         <dt>OGG</dt>
 240         <dd>
 241                 <p>Jumps to position seconds from the beginning of the song. </p>
 242         </dd>
 243         <dt>MP3</dt>
 244         <dd>
 245                 <p>Jumps to position seconds from the current position in the stream.
 246 So you may want to call <a href="/SDL-Mixer-Music.html#rewind_music">SDL::Mixer::Music::rewind_music</a> before this.
 247 Does not go in reverse... negative values do nothing. </p>
 248         </dd>
 249 </dl>
 250 <p>Returns: <code>0</code> on success, or <code>-1</code> if the codec doesn't support this function. </p>
 251
 252 </div>
 253 <h2 id="paused_music">paused_music</h2>
 254 <div id="paused_music_CONTENT">
 255 <pre> my $paused = SDL::Mixer::Music::paused_music();
 256
 257 </pre>
 258 <p>Returns <code>1</code> if the music is paused, otherwise <code>0</code>.</p>
 259
 260 </div>
 261 <h2 id="playing_music">playing_music</h2>
 262 <div id="playing_music_CONTENT">
 263 <pre> my $playing_music = SDL::Mixer::Music::playing_music();
 264
 265 </pre>
 266 <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>
 267
 268 </div>
 269 <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 270 <div id="AUTHORS_CONTENT">
 271 <p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p>
 272
 273 </div>
 274 </div>