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