pods::SDL::Mixer(3) User Contributed Perl Documentation pods::SDL::Mixer(3)NAME
SDL::Mixer - Sound and music functions
CATEGORY
Mixer
CONSTANTS
The constants are exported by default. You can avoid this by doing:
use SDL::Mixer ();
and access them directly:
SDL::Mixer::MIX_DEFAULT_FREQUENCY;
or by choosing the export tags below:
Export tag: ':init'
MIX_INIT_FLAC
MIX_INIT_MOD
MIX_INIT_MP3
MIX_INIT_OGG
Export tag: ':defaults'
MIX_CHANNELS
MIX_DEFAULT_FORMAT
MIX_DEFAULT_FREQUENCY
MIX_DEFAULT_CHANNELS
MIX_MAX_VOLUME
MIX_CHANNEL_POST
Export tag: ':fading'
MIX_NO_FADING
MIX_FADING_OUT
MIX_FADING_IN
Export tag: ':type'
MUS_NONE
MUS_CMD
MUS_WAV
MUS_MOD
MUS_MID
MUS_OGG
MUS_MP3
MUS_MP3_MAD
MUS_MP3_FLAC
Export tag: ':format'
AUDIO_U8
AUDIO_S8
AUDIO_U16LSB
AUDIO_S16LSB
AUDIO_U16MSB
AUDIO_S16MSB
AUDIO_U16
AUDIO_S16
AUDIO_U16SYS
AUDIO_S16SYS
Export tag: ':status'
SDL_AUDIO_STOPPED
SDL_AUDIO_PLAYING
SDL_AUDIO_PAUSED
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.
Supported Formats
The SDL Mixer library is a multi-channel audio mixer. It supports 8
channels of 16 bit stereo audio, and a single channel for music.
You can use the channels to load samples (i.e. sound effects) in the
following formats:
· Microsoft WAVE files (WAV)
· Creative Labs VOC files (VOC)
· MIDI files (if compiled with Timidity)
If you use MIDI, you should note that the process of mixing MIDI files
to wave output is very CPU-intensive, so if playing regular WAVE files
sound great, but playing MIDI files sound choppy, try using 8-bit
audio, mono audio, or lower frequencies.
The music channel can play the following formats:
· AIFF
· MOD (.mod .xm .s3m .669 .it .med and more - if compiled with
libmikmod)
· OggVorbis (.ogg - if compiled with ogg/vorbis libraries)
· MP3 (if compiled with SMPEG or MAD libraries)
· FLAC (if compiled with FLAC library)
METHODS
init
my $init_flags = SDL::Mixer::init( $flags );
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;
my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );
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;
Flags:
· MIX_INIT_MP3
· MIX_INIT_MOD
· MIX_INIT_FLAC
· MIX_INIT_OGG
Note: Only available for SDL_mixer >= 1.2.10
quit
SDL::Mixer::quit();
This function unloads the libraries previously loaded with init().
Note: Only available for SDL_mixer >= 1.2.10
linked_version
$version = SDL::Mixer::linked_version();
"linked_version" gives 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;
my $version = SDL::Mixer::linked_version();
printf("%d.%d.%d\n", $version->major, $version->minor, $version->patch); # prints "1.2.8" for me
open_audio
my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );
"open_audio" will 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", or
"AUDIO_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 use "AUDIO_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;
close_audio
SDL::Mixer::close_audio();
Close the mixer and halting all playing audio. This function does not
return anything.
query_spec
my @query_spec = @{ SDL::Mixer::query_spec() };
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;
my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
printf("%s, %s, %s, %s\n", $status, $freq, $format, $channels);
SEE ALSO
perl, SDL::Mixer::Channels, SDL::Mixer::Effects, SDL::Mixer::Groups,
SDL::Mixer::Music.
AUTHORS
See "AUTHORS" in SDL.
perl v5.18.1 2013-09-28 pods::SDL::Mixer(3)
