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 sub set_panning {
 238   my($self, $channel, $left, $right) = @_;
 239         return SDL::MixSetPanning($channel, $left, $right);
 240 }
 241
 242 1;
 243
 244 __END__;
 245
 246 =pod
 247
 248 =head1 NAME
 249
 250 SDL::Mixer - a SDL perl extension
 251
 252 =head1 SYNOPSIS
 253
 254   $mixer = new SDL::Mixer       -frequency => MIX_DEFAULT_FREQUENCY,
 255                                 -format => MIX_DEFAULT_FORMAT,
 256                                 -channels => MIX_DEFAULT_CHANNELS,
 257                                 -size => 4096;
 258
 259 =head1 DESCRIPTION
 260
 261 SDL::Mixer allows you access to the SDL mixer library, enablig sound and
 262 music volume setting, playing, pausing and resuming, as well as fading
 263 the sound and music in and out.
 264
 265 =head1 METHODS
 266
 267 =head2 new()
 268
 269         $mixer = SDL::Mixer->new(       -frequency => MIX_DEFAULT_FREQUENCY,
 270                                         -format    => MIX_DEFAULT_FORMAT,
 271                                         -channels  => MIX_DEFAULT_CHANNELS,
 272                                         -size      => 4096);
 273
 274 Creates a new SDL::Mixer object. C<$size> is the buffer size in bytes.
 275
 276 =head2 query_spec()
 277
 278         my $specs = SDL::Mixer::query_spec();
 279
 280 Returns a hash reference, containing the following keys and their respective
 281 values:
 282
 283         -status
 284         -frequency
 285         -channels
 286         -format
 287
 288 =head2 reserve_channels
 289
 290         $mixer->reserve_channels(4);
 291
 292 Reserve so many channels.
 293
 294 =head2 allocate_channels()
 295
 296         $mixer->reserve_channels(2);
 297
 298 Allocate so many channels.
 299
 300 =head2 group_channel(channel,group)
 301
 302 Group the channel number C<$channel> into group C<$group>.
 303
 304 =head2 group_channels(from,to,group)
 305
 306 Groups a range of channels
 307
 308 =head2 group_available(group)
 309
 310 Return true when the group is available.
 311
 312 =head2 group_count(group)
 313
 314 Returns the number of channels in the group
 315
 316 =head2 group_oldest()
 317
 318
 319 =head2 group_newer()
 320
 321
 322 =head2 play_channel()
 323
 324
 325 =head2 play_music()
 326
 327 Play C<$music> C<$loop> times.
 328
 329 =head2 fade_in_channel(channel,chunk,loops,ms,ticks)
 330
 331 Fades a channel in
 332
 333 =head2 fade_in_music(music,loops,ms)
 334
 335 Fades the music in over a number of ms, looping as it does
 336
 337 =head2 channel_volume(channel,volume)
 338
 339 Sets the volume for a single channel
 340
 341 =head2 mucis_volume(volume)
 342
 343 Set the volume for the music.
 344
 345 =head2 halt_channel(channel)
 346
 347 Stops a specific channel
 348
 349 =head2 halt_group(group)
 350
 351 Stops a group of channels
 352
 353 =head2 halt_music()
 354
 355 Stops the music
 356
 357 =head2 channel_expire(channel,ticks)
 358
 359 Ignores the channel after C<ticks> has expired
 360
 361 =head2 fade_out_channel(channel,ms)
 362
 363 Fade the channel number C<$channel> in C<$ms> ms out.
 364
 365 =head2 fade_out_group(group,ms)
 366
 367 Fade the channel group C<$group> in C<$ms> ms out.
 368
 369 =head2 fade_out_music(ms)
 370
 371 Fade the music in C<$ms> ms out.
 372
 373 =head2 fading_music()
 374
 375 Return true when the music is currently fading in or out.
 376
 377 =head2 fading_channel()
 378
 379 Return true when the channel number C<$channel> is currently fading in or out.
 380
 381 =head2 pause( channel )
 382
 383 Pause the channel C<$channel>.
 384
 385 =head2 resume(channel)
 386
 387 Resume the channel C<$channel>.
 388
 389 =head2 paused()
 390
 391 Return true when the channel is currently paused.
 392
 393 =head2 pause_music()
 394
 395 Pause the music play.
 396
 397 =head2 resume_music()
 398
 399 Resume the music play.
 400
 401 =head2 rewind_music()
 402
 403 Resets the music file to the beginning
 404
 405 =head2 music_paused()
 406
 407 Return true when the music is currently paused.
 408
 409 =head2 playing()
 410
 411 Return true when the channel is currently playing.
 412
 413 =head2 playing_music ()
 414
 415 Return true when the music is currently playing.
 416
 417 =head1 set_panning($channel, $left, $right)
 418
 419 Sets the volume for the left or right channels. To do true panning:
 420
 421   $mixer->set_panning($channel, $left, 254 - $left);
 422
 423 =head1 AUTHORS
 424
 425 David J. Goehrig, basic doc added by Tels <http://bloodgate.com>.
 426
 427 =head1 SEE ALSO
 428
 429 L<perl>, L<SDL::Music> and L<SDL::Sound>.
 430
 431 =cut