SDL::Mixer - a SDL perl extension
+SDL::Mixer - Sound and music functions
$mixer = new SDL::Mixer -frequency => MIX_DEFAULT_FREQUENCY, - -format => MIX_DEFAULT_FORMAT, - -channels => MIX_DEFAULT_CHANNELS, - -size => 4096; - -- -
SDL::Mixer allows you access to the SDL mixer library, enablig sound and -music volume setting, playing, pausing and resuming, as well as fading -the sound and music in and out.
- -Mixer
$mixer = SDL::Mixer->new( -frequency => MIX_DEFAULT_FREQUENCY, - -format => MIX_DEFAULT_FORMAT, - -channels => MIX_DEFAULT_CHANNELS, - -size => 4096); +CONSTANTS
++-The constants are exported by default. You can avoid this by doing:
+use SDL::Mixer ();-Creates a new SDL::Mixer object.
- -$sizeis the buffer size in bytes.query_spec()
---my $specs = SDL::Mixer::query_spec(); +and access them directly:
+SDL::Mixer::MIX_DEFAULT_FREQUENCY;-Returns a hash reference, containing the following keys and their respective -values:
--status - -frequency - -channels - -format +or by choosing the export tags below:
+Export tag: ':init'
+MIX_INIT_FLAC + MIX_INIT_MOD + MIX_INIT_MP3 + MIX_INIT_OGG- -reserve_channels
---$mixer->reserve_channels(4); +Export tag: ':default'
+MIX_CHANNELS + MIX_DEFAULT_FORMAT + MIX_DEFAULT_FREQUENCY + MIX_DEFAULT_CHANNELS + MIX_MAX_VOLUME + MIX_CHANNEL_POST-Reserve so many channels.
- -allocate_channels()
---$mixer->reserve_channels(2); +Export tag: ':fading'
+MIX_NO_FADING + MIX_FADING_OUT + MIX_FADING_IN-Allocate so many channels.
- -group_channel(channel,group)
---Group the channel number
- -$channelinto group$group.group_channels(from,to,group)
---Groups a range of channels
- -group_available(group)
---Return true when the group is available.
- -group_count(group)
---Returns the number of channels in the group
- -group_oldest()
-- - - - - --group_newer()
-- - - +-Export tag: ':type'
+MUS_NONE + MUS_CMD + MUS_WAV + MUS_MOD + MUS_MID + MUS_OGG + MUS_MP3 + MUS_MP3_MAD + MUS_MP3_FLAC +play_channel()
-- - - - +DESCRIPTION
++-SDL::Mixer allows you to enable sound, alter music volume settings, and lets you play, pause and resume, as well as fading the sound and music +in and out.
play_music()
--Play
+$music$looptimes.METHODS
+-fade_in_channel(channel,chunk,loops,ms,ticks)
--Fades a channel in
+init
++-my $init_flags = SDL::Mixer::init( $flags ); -fade_in_music(music,loops,ms)
---Fades the music in over a number of ms, looping as it does
+ +Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together. +It returns the flags successfully initialized, or 0 on failure.
+Example:
+use SDL::Mixer; -channel_volume(channel,volume)
---Sets the volume for a single channel
+ my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG ); -mucis_volume(volume)
---Set the volume for the music.
+ print("We have MP3 support!\n") if $init_flags & MIX_INIT_MP3; + print("We have MOD support!\n") if $init_flags & MIX_INIT_MOD; + print("We have FLAC support!\n") if $init_flags & MIX_INIT_FLAC; + print("We have OGG support!\n") if $init_flags & MIX_INIT_OGG; -halt_channel(channel)
---Stops a specific channel
+ +Flags:
++
-- MIX_INIT_MP3
+- MIX_INIT_MOD
+- MIX_INIT_FLAC
+- MIX_INIT_OGG
+halt_group(group)
---Stops a group of channels
+Note: Only available for SDL_mixer >= 1.2.10
halt_music()
--Stops the music
+quit
++-SDL::Mixer::quit(); -channel_expire(channel,ticks)
---Ignores the channel after
+ +tickshas expiredThis function unloads the liraries previously loaded with init().
+Note: Only available for SDL_mixer >= 1.2.10
fade_out_channel(channel,ms)
--Fade the channel number
+$channelin$msms out.linked_version
++-$version = SDL::Mixer::linked_version(); -fade_out_group(group,ms)
---Fade the channel group
+ +$groupin$msms out.+
linked_versiongives you the major-, minor-, and patchlevel for SDL_mixer. This way you can check if e.g. init() and quit() +are available.Example:
+use SDL::Mixer; + use SDL::Version; -fade_out_music(ms)
---Fade the music in
+ my $version = SDL::Mixer::linked_version(); -$msms out.fading_music()
---Return true when the music is currently fading in or out.
+ printf("%d.%d.%d\n", $version->major, $version->minor, $version->patch); # prints "1.2.8" for me -fading_channel()
---Return true when the channel number
+$channelis currently fading in or out.pause( channel )
--Pause the channel
+$channel.open_audio
++-my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize ); -resume(channel)
---Resume the channel
+ +$channel.+
open_audiowill initialize SDL_mixer if it is not yet initialized, see note. SDL_mixer may not be able to provide the exact specifications +your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using +query_spec.Returns 0 on success, -1 on error.
+Note: You must not use
+AUDIO_S16,AUDIO_U16,AUDIO_S16LSB, orAUDIO_U16LSB.They are not portable, and SDL will not return an +error code when they fail. The result will be a horrible staticy noise. You can usually useAUDIO_S16SYS, though not always. Future versions +of SDL should take this parameter only as a hint, then read back the value that the OS (for example, OSS or ALSA) has chosen to use in case the +desired audio type is not supported.Note: When already initialized, this function will not re-initialize SDL_mixer, nor fail. It will merely increment the number of times +SDL::Mixer::close_audio must be called to actually get it to uninitialize. This serves as a very simplistic method for multiple application +components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the +latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting.
+Example:
+use SDL; + use SDL::Mixer; + + printf("Error initializing SDL_mixer: %s\n", SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0; -paused()
---Return true when the channel is currently paused.
+pause_music()
--Pause the music play.
+close_audio
++-SDL::Mixer::close_audio(); -resume_music()
---Resume the music play.
+ +Close the mixer and halting all playing audio. This function does not return anything.
rewind_music()
--\ No newline at end of fileResets the music file to the beginning
+query_spec
++-my @query_spec = @{ SDL::Mixer::query_spec() }; -music_paused()
---Return true when the music is currently paused.
+ +Find out what the actual audio device parameters are. +This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.
+Example:
+use SDL::Mixer; -playing()
---Return true when the channel is currently playing.
+ my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() }; -playing_music ()
---Return true when the music is currently playing.
+ printf("%s, %s, %s, %s\n", $status, $freq, $format, $channels); -set_panning($channel, $left, $right)
--Sets the volume for the left or right channels. To do true panning:
+AUTHORS
-David J. Goehrig, basic doc added by Tels <http://bloodgate.com>.
+Tobias Leich [FROGGS]
SEE ALSO
-perl, SDL::Music and SDL::Sound.
+perl, SDL::Mixer::Channels, SDL::Mixer::Effects, SDL::Mixer::Groups, SDL::Mixer::Music.