lib/SDL/Mixer.pm

   1 #!/usr/bin/env perl
   2 #
   3 # Mixer.pm
   4 #
   5 # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org>
   6 #
   7 # ------------------------------------------------------------------------------
   8 #
   9 # This library is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public
  11 # License as published by the Free Software Foundation; either
  12 # version 2.1 of the License, or (at your option) any later version.
  13 #
  14 # This library is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with this library; if not, write to the Free Software
  21 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  22 #
  23 # ------------------------------------------------------------------------------
  24 #
  25 # Please feel free to send questions, suggestions or improvements to:
  26 #
  27 #       David J. Goehrig
  28 #       dgoehrig@cpan.org
  29 #
  30
  31 package SDL::Mixer;
  32
  33 use strict;
  34 use warnings;
  35 use Carp;
  36
  37 use SDL;
  38 use SDL::Sound;
  39 use SDL::Music;
  40
  41 BEGIN {
  42 }
  43
  44 $SDL::Mixer::initialized = 0;
  45
  46 sub new {
  47         my $proto = shift;
  48         my $class = ref($proto) || $proto;
  49         my $self = {};
  50         my %options = @_;
  51         my $frequency = $options{-frequency} || $options{-rate} || SDL::MIX_DEFAULT_FREQUENCY();
  52         my $format = $options{-format} || SDL::MIX_DEFAULT_FORMAT();
  53         my $channels = $options{-channels} || SDL::MIX_DEFAULT_CHANNELS();
  54         my $size = $options{-size} || 4096;
  55         unless ( $SDL::Mixer::initialized ) {
  56                 SDL::MixOpenAudio($frequency,$format,$channels,$size ) &&
  57                         croak SDL::GetError();
  58                 $SDL::Mixer::initialized = 1;
  59         } else {
  60                 ++$SDL::Mixer::initialized;
  61         }
  62         bless $self,$class;
  63         return $self;
  64 }
  65
  66 sub DESTROY {
  67         my $self = shift;
  68         --$SDL::Mixer::initialized;
  69         unless ($SDL::Mixer::initialized) {
  70                 SDL::MixCloseAudio();
  71         }
  72 }
  73
  74
  75 sub query_spec () {
  76         my ($status,$freq,$format,$channels) = SDL::MixQuerySpec();
  77         my %hash = ( -status => $status, -frequency => $freq,
  78                         -format => $format, -channels => $channels );
  79         return \%hash;
  80 }
  81
  82 sub reserve_channels ($$) {
  83         my ($self,$channels) = @_;
  84         return SDL::MixReserveChannels($channels);
  85 }
  86
  87 sub allocate_channels ($$) {
  88         my ($self,$channels) = @_;
  89         return SDL::MixAllocateChannels($channels);
  90 }
  91
  92 sub group_channel ($$$) {
  93         my ($self,$channel,$group) = @_;
  94         return SDL::MixGroupChannel($channel, $group);
  95 }
  96
  97 sub group_channels ($$$$) {
  98         my ($self,$from,$to,$group) = @_;
  99         return SDL::MixGroupChannels($from,$to,$group);
 100 }
 101
 102 sub group_available ($$) {
 103         my ($self,$group) = @_;
 104         return SDL::MixGroupAvailable($group);
 105 }
 106
 107 sub group_count ($$) {
 108         my ($self,$group) = @_;
 109         return SDL::MixGroupCount($group);
 110 }
 111
 112 sub group_oldest ($$) {
 113         my ($self,$group) = @_;
 114         return SDL::MixGroupOldest($group);
 115 }
 116
 117 sub group_newer ($$) {
 118         my ($self,$group) = @_;
 119         return SDL::MixGroupNewer($group);
 120 }
 121
 122 sub play_channel ($$$$;$) {
 123         my ($self,$channel,$chunk,$loops,$ticks) = @_;
 124         $ticks ||= -1;
 125         return SDL::MixPlayChannelTimed($channel,$$chunk,$loops,$ticks);
 126 }
 127
 128 sub play_music ($$$) {
 129         my ($self,$music,$loops) = @_;
 130         return SDL::MixPlayMusic($$music,$loops);
 131 }
 132
 133 sub fade_in_channel ($$$$$;$) {
 134         my ($self,$channel,$chunk,$loops,$ms,$ticks) = @_;
 135         $ticks ||= -1;
 136         return SDL::MixFadeInChannelTimed($channel,$$chunk,$loops,$ms,$ticks);
 137 }
 138
 139 sub fade_in_music ($$$$) {
 140         my ($self,$music,$loops,$ms) = @_;
 141         return SDL::MixFadeInMusic($$music,$loops,$ms);
 142 }
 143
 144 sub channel_volume ($$$) {
 145         my ($self,$channel,$volume) = @_;
 146         return SDL::MixVolume($channel,$volume);
 147 }
 148
 149 sub music_volume ($$) {
 150         my ($self,$volume) = @_;
 151         return SDL::MixVolumeMusic($volume);
 152 }
 153
 154 sub halt_channel ($$) {
 155         my ($self,$channel) = @_;
 156         return SDL::MixHaltChannel($channel);
 157 }
 158
 159 sub halt_group ($$) {
 160         my ($self,$group) = @_;
 161         return SDL::MixHaltGroup($group);
 162 }
 163
 164 sub halt_music (){
 165         return SDL::MixHaltMusic();
 166 }
 167
 168 sub channel_expire ($$$) {
 169         my ($self,$channel,$ticks) = @_;
 170         return SDL::MixExpireChannel($channel,$ticks);
 171 }
 172
 173 sub fade_out_channel ($$$) {
 174         my ($self,$channel,$ms) = @_;
 175         return SDL::MixFadeOutChannel($channel,$ms);
 176 }
 177
 178 sub fade_out_group ($$$) {
 179         my ($self,$group,$ms) = @_;
 180         return SDL::MixFadeOutGroup($group,$ms);
 181 }
 182
 183 sub fade_out_music ($$) {
 184         my ($self,$ms) = @_;
 185         return SDL::MixFadeOutMusic($ms);
 186 }
 187
 188 sub fading_music () {
 189         return SDL::MixFadingMusic();
 190 }
 191
 192 sub fading_channel ($$) {
 193         my ($self,$channel) = @_;
 194         return SDL::MixFadingChannel($channel);
 195 }
 196
 197 sub pause ($$) {
 198         my ($self,$channel) = @_;
 199         SDL::MixPause($channel);
 200 }
 201
 202 sub resume ($$) {
 203         my ($self,$channel) = @_;
 204         SDL::MixResume($channel);
 205 }
 206
 207 sub paused ($$) {
 208         my ($self,$channel) = @_;
 209         return SDL::MixPaused($channel);
 210 }
 211
 212 sub pause_music () {
 213         SDL::MixPauseMusic();
 214 }
 215
 216 sub resume_music () {
 217         SDL::MixResumeMusic();
 218 }
 219
 220 sub rewind_music (){
 221         SDL::MixRewindMusic();
 222 }
 223
 224 sub music_paused (){
 225         return SDL::MixPausedMusic();
 226 }
 227
 228 sub playing ($$) {
 229         my ($self,$channel) = @_;
 230         return SDL::MixPlaying($channel);
 231 }
 232
 233 sub playing_music () {
 234         return SDL::MixPlayingMusic();
 235 }
 236
 237 1;
 238
 239 __END__;
 240
 241 =pod
 242
 243 =head1 NAME
 244
 245 SDL::Mixer - a SDL perl extension
 246
 247 =head1 SYNOPSIS
 248
 249   $mixer = new SDL::Mixer       -frequency => MIX_DEFAULT_FREQUENCY,
 250                                 -format => MIX_DEFAULT_FORMAT,
 251                                 -channels => MIX_DEFAULT_CHANNELS,
 252                                 -size => 4096;
 253
 254 =head1 DESCRIPTION
 255
 256 SDL::Mixer allows you access to the SDL mixer library, enablig sound and
 257 music volume setting, playing, pausing and resuming, as well as fading
 258 the sound and music in and out.
 259
 260 =head1 METHODS
 261
 262 =head2 new()
 263
 264         $mixer = SDL::Mixer->new(       -frequency => MIX_DEFAULT_FREQUENCY,
 265                                         -format    => MIX_DEFAULT_FORMAT,
 266                                         -channels  => MIX_DEFAULT_CHANNELS,
 267                                         -size      => 4096);
 268
 269 Creates a new SDL::Mixer object. C<$size> is the buffer size in bytes.
 270
 271 =head2 query_spec()
 272
 273         my $specs = SDL::Mixer::query_spec();
 274
 275 Returns a hash reference, containing the following keys and their respective
 276 values:
 277
 278         -status
 279         -frequency
 280         -channels
 281         -format
 282
 283 =head2 reserve_channels
 284
 285         $mixer->reserve_channels(4);
 286
 287 Reserve so many channels.
 288
 289 =head2 allocate_channels()
 290
 291         $mixer->reserve_channels(2);
 292
 293 Allocate so many channels.
 294
 295 =head2 group_channel(channel,group)
 296
 297 Group the channel number C<$channel> into group C<$group>.
 298
 299 =head2 group_channels(from,to,group)
 300
 301 Groups a range of channels
 302
 303 =head2 group_available(group)
 304
 305 Return true when the group is available.
 306
 307 =head2 group_count(group)
 308
 309 Returns the number of channels in the group
 310
 311 =head2 group_oldest()
 312
 313
 314 =head2 group_newer()
 315
 316
 317 =head2 play_channel()
 318
 319
 320 =head2 play_music()
 321
 322 Play C<$music> C<$loop> times.
 323
 324 =head2 fade_in_channel(channel,chunk,loops,ms,ticks)
 325
 326 Fades a channel in
 327
 328 =head2 fade_in_music(music,loops,ms)
 329
 330 Fades the music in over a number of ms, looping as it does
 331
 332 =head2 channel_volume(channel,volume)
 333
 334 Sets the volume for a single channel
 335
 336 =head2 mucis_volume(volume)
 337
 338 Set the volume for the music.
 339
 340 =head2 halt_channel(channel)
 341
 342 Stops a specific channel
 343
 344 =head2 halt_group(group)
 345
 346 Stops a group of channels
 347
 348 =head2 halt_music()
 349
 350 Stops the music
 351
 352 =head2 channel_expire(channel,ticks)
 353
 354 Ignores the channel after C<ticks> has expired
 355
 356 =head2 fade_out_channel(channel,ms)
 357
 358 Fade the channel number C<$channel> in C<$ms> ms out.
 359
 360 =head2 fade_out_group(group,ms)
 361
 362 Fade the channel group C<$group> in C<$ms> ms out.
 363
 364 =head2 fade_out_music(ms)
 365
 366 Fade the music in C<$ms> ms out.
 367
 368 =head2 fading_music()
 369
 370 Return true when the music is currently fading in or out.
 371
 372 =head2 fading_channel()
 373
 374 Return true when the channel number C<$channel> is currently fading in or out.
 375
 376 =head2 pause( channel )
 377
 378 Pause the channel C<$channel>.
 379
 380 =head2 resume(channel)
 381
 382 Resume the channel C<$channel>.
 383
 384 =head2 paused()
 385
 386 Return true when the channel is currently paused.
 387
 388 =head2 pause_music()
 389
 390 Pause the music play.
 391
 392 =head2 resume_music()
 393
 394 Resume the music play.
 395
 396 =head2 rewind_music()
 397
 398 Resets the music file to the beginning
 399
 400 =head2 music_paused()
 401
 402 Return true when the music is currently paused.
 403
 404 =head2 playing()
 405
 406 Return true when the channel is currently playing.
 407
 408 =head2 playing_music ()
 409
 410 Return true when the music is currently playing.
 411
 412 =head1 AUTHORS
 413
 414 David J. Goehrig, basic doc added by Tels <http://bloodgate.com>.
 415
 416 =head1 SEE ALSO
 417
 418 L<perl>, L<SDL::Music> and L<SDL::Sound>.
 419
 420 =cut