/lib/pods/SDL/Mixer/Music.pod

http://github.com/PerlGameDev/SDL · Unknown · 249 lines · 144 code · 105 blank · 0 comment · 0 complexity · df6e8f4a78a83a23bb5edbd296341c50 MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDL::Mixer::Music - functions for music
  4. =head1 CATEGORY
  5. Mixer
  6. =head1 METHODS
  7. =head2 load_MUS
  8. my $music = SDL::Mixer::Music::load_MUS( $file );
  9. C<load_MUS> loads a music file into a C<SDL::Mixer::MixMusic> structure. This can be passed to L<play_music|SDL::Mixer::Music/"play_music">.
  10. =head2 load_MUS_RW
  11. my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );
  12. C<load_MUS_RW> does the same like C<load_MUS> except that it accepts an L<SDL::RWOps>-object rather than a filename.
  13. Example for loading music from a variable:
  14. use SDL;
  15. use SDL::Mixer;
  16. use SDL::Mixer::Music;
  17. use SDL::RWOps;
  18. [...]
  19. my $rwops = SDL::RWOps->new_const_mem( $scalar_holding_music );
  20. my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );
  21. B<Note:> You need at least libSDL_mixer 1.2.7 for this feature.
  22. =head2 hook_music
  23. SDL::Mixer::Music::hook_music( $callback, $position );
  24. This sets up a custom music player function, so you can pass your own audio stream data into the SDL::Mixer.
  25. The function will be called with C<position> passed into the first parameter when the C<callback> is called.
  26. The audio stream buffer has to be filled with length bytes of music (2nd parameter).
  27. The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called.
  28. All the music playing and stopping functions have no effect on music after this. Pause and resume will work.
  29. Using a custom music player and the internal music player is not possible, the custom music player takes priority.
  30. To stop the custom music player call C<hook_music()> without arguments.
  31. B<Note>: NEVER call C<SDL::Mixer> functions, nor L<SDL::Audio::lock|SDL::Audio/"lock">, from a callback function.
  32. B<Note>: At program termination also call C<SDL::Mixer::Music::hook_music()> to stop this callback.
  33. Example:
  34. sub callback
  35. {
  36. my $position = shift; # position (first time its 0, on each call $length is added)
  37. my $length = shift; # length of bytes we have to put in stream
  38. my @stream = '';
  39. printf("position=%8d, stream length=%6d\n", $position, $length);
  40. for(my $i = 0; $i < $length; $i++)
  41. {
  42. push(@stream, (($i + $position) & 0xFF));
  43. }
  44. return @stream;
  45. }
  46. SDL::Mixer::Music::hook_music( 'main::callback', 0 );
  47. =head2 hook_music_finished
  48. SDL::Mixer::Music::hook_music_finished( 'main::callback' );
  49. This callback is called when music called by e.g. L<SDL::Mixer::Music::play_music|SDL::Mixer::Music/"play_music"> or
  50. L<SDL::Mixer::Music::fade_in_music|SDL::Mixer::Music/"fade_in_music"> stops naturally.
  51. This happens when the music is over or is fading out.
  52. B<Note>: If you play music via L<SDL::Mixer::Music::hook_music|SDL::Mixer::Music/"hook_music">, this callback will never be called.
  53. Example:
  54. my $music_is_playing = 0;
  55. my @music = qw(first.mp3 next.mp3 other.mp3 last.mp3);
  56. sub callback
  57. {
  58. $music_is_playing = 0;
  59. }
  60. SDL::Mixer::Music::hook_music_finished( 'main::callback' );
  61. foreach my $this_song ( @music )
  62. {
  63. SDL::Mixer::Music::play_music( $this_song, 0 );
  64. $music_is_playing = 1;
  65. SDL::delay( 100 ) while( $music_is_playing );
  66. }
  67. SDL::Mixer::Music::hook_music_finished(); # cleanup
  68. =head2 get_music_hook_data
  69. my $position = SDL::Mixer::Music::get_music_hook_data();
  70. Returns the C<position> (first) parameter that will be passed to L<SDL::Mixer::Music::hook_music|SDL::Mixer::Music/"hook_music">'s callback.
  71. =head2 play_music
  72. my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
  73. C<play_music> plays a given C<SDL::Mixer::MixMusic>.
  74. Passing -1 to C<$loops> will loop the music infinitely.
  75. Example:
  76. my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
  77. unless(SDL::Mixer::Music::play_music($sample_music, -1))
  78. {
  79. print("Something went wrong!\n");
  80. }
  81. =head2 fade_in_music
  82. my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
  83. Same as L<SDL::Mixer::Music::play_music|SDL::Mixer::Music/"play_music"> but you can specify the fade-in time by C<$ms>.
  84. =head2 fade_out_music
  85. my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
  86. C<fade_out_music> fades out the music with a duration specified in C<ms> in milliseconds.
  87. Returns the the number of channels that will be faded out.
  88. =head2 fading_music
  89. my $fading_music = SDL::Mixer::Music::fading_music();
  90. Returns one of the following:
  91. =over 4
  92. =item *
  93. MIX_NO_FADING
  94. =item *
  95. MIX_FADING_OUT
  96. =item *
  97. MIX_FADING_IN
  98. =back
  99. =head2 volume_music
  100. my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
  101. C<volume_music> set the volume in C<$new_volume> and returns the volume that was set before.
  102. Passing C<-1> as argument causes only to return the current volume.
  103. Volume is between C<0> (silence) and C<MIX_MAX_VOLUME = 128>.
  104. Example:
  105. # set the music volume to 1/2 maximum, and then check it
  106. printf( "volume was : %d\n", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
  107. printf( "volume is now : %d\n", SDL::Mixer::Music::volume_music( -1 ) );
  108. =head2 halt_music
  109. SDL::Mixer::Music::halt_music();
  110. Halts the music.
  111. =head2 pause_music
  112. SDL::Mixer::Music::pause_music();
  113. Pauses the music.
  114. =head2 resume_music
  115. SDL::Mixer::Music::resume_music();
  116. Resumes the music.
  117. =head2 rewind_music
  118. SDL::Mixer::Music::rewind_music();
  119. Rewinds the music.
  120. =head2 set_music_position
  121. SDL::Mixer::Music::set_music_position( $position );
  122. Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the
  123. music sources listed below.
  124. =over 4
  125. =item MOD
  126. The double is cast to Uint16 and used for a pattern number in the module.
  127. Passing zero is similar to rewinding the song.
  128. =item OGG
  129. Jumps to position seconds from the beginning of the song.
  130. =item MP3
  131. Jumps to position seconds from the current position in the stream.
  132. So you may want to call L<SDL::Mixer::Music::rewind_music|SDL::Mixer::Music/"rewind_music"> before this.
  133. Does not go in reverse... negative values do nothing.
  134. =back
  135. Returns: C<0> on success, or C<-1> if the codec doesn't support this function.
  136. =head2 paused_music
  137. my $paused = SDL::Mixer::Music::paused_music();
  138. Returns C<1> if the music is paused, otherwise C<0>.
  139. =head2 playing_music
  140. my $playing_music = SDL::Mixer::Music::playing_music();
  141. Returns C<1> if the music is playing sound, otherwise C<0>. It doesn't check if the music is paused.
  142. =head1 AUTHORS
  143. See L<SDL/AUTHORS>.
  144. =cut