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

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