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