/lib/pods/SDL/Mixer.pod

  1
  2=pod
  3
  4=head1 NAME
  5
  6SDL::Mixer - Sound and music functions
  7
  8=head1 CATEGORY
  9
 10Mixer
 11
 12=head1 CONSTANTS
 13
 14The constants are exported by default. You can avoid this by doing:
 15
 16 use SDL::Mixer ();
 17
 18and access them directly:
 19
 20 SDL::Mixer::MIX_DEFAULT_FREQUENCY;
 21
 22or by choosing the export tags below:
 23
 24Export tag: ':init'
 25
 26 MIX_INIT_FLAC
 27 MIX_INIT_MOD
 28 MIX_INIT_MP3
 29 MIX_INIT_OGG
 30
 31Export tag: ':defaults'
 32
 33 MIX_CHANNELS
 34 MIX_DEFAULT_FORMAT
 35 MIX_DEFAULT_FREQUENCY
 36 MIX_DEFAULT_CHANNELS
 37 MIX_MAX_VOLUME
 38 MIX_CHANNEL_POST
 39
 40Export tag: ':fading'
 41
 42 MIX_NO_FADING
 43 MIX_FADING_OUT
 44 MIX_FADING_IN
 45
 46Export tag: ':type'
 47
 48 MUS_NONE
 49 MUS_CMD
 50 MUS_WAV
 51 MUS_MOD
 52 MUS_MID
 53 MUS_OGG
 54 MUS_MP3
 55 MUS_MP3_MAD
 56 MUS_MP3_FLAC
 57
 58Export tag: ':format'
 59
 60 AUDIO_U8
 61 AUDIO_S8
 62 AUDIO_U16LSB
 63 AUDIO_S16LSB
 64 AUDIO_U16MSB
 65 AUDIO_S16MSB
 66 AUDIO_U16
 67 AUDIO_S16 
 68 AUDIO_U16SYS
 69 AUDIO_S16SYS
 70
 71Export tag: ':status'
 72
 73 SDL_AUDIO_STOPPED
 74 SDL_AUDIO_PLAYING
 75 SDL_AUDIO_PAUSED
 76
 77=head1 DESCRIPTION
 78
 79SDL::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 
 80in and out.
 81
 82=head2 Supported Formats
 83
 84The SDL Mixer library is a multi-channel audio mixer. It supports I<8 channels> of B<16 bit> stereo audio, and a I<single channel for music>.
 85
 86You can use the channels to load samples (i.e. sound effects) in the following formats:
 87
 88=over 4
 89
 90=item * Microsoft WAVE files (WAV)
 91
 92=item * Creative Labs VOC files (VOC)
 93
 94=item * MIDI files (if compiled with Timidity)
 95
 96=back
 97
 98If 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
 99files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.
100
101The music channel can play the following formats:
102
103=over 4
104
105=item * AIFF
106
107=item * MOD (.mod .xm .s3m .669 .it .med and more - if compiled with libmikmod)
108
109=item * OggVorbis (.ogg - if compiled with ogg/vorbis libraries)
110
111=item * MP3 (if compiled with SMPEG or MAD libraries)
112
113=item * FLAC (if compiled with FLAC library)
114
115=back
116
117
118=head1 METHODS
119  
120=head2 init
121
122 my $init_flags = SDL::Mixer::init( $flags );
123
124Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together.
125It returns the flags successfully initialized, or 0 on failure.
126
127Example:
128
129 use SDL::Mixer;
130 
131 my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );
132 
133 print("We have MP3 support!\n")  if $init_flags & MIX_INIT_MP3;
134 print("We have MOD support!\n")  if $init_flags & MIX_INIT_MOD;
135 print("We have FLAC support!\n") if $init_flags & MIX_INIT_FLAC;
136 print("We have OGG support!\n")  if $init_flags & MIX_INIT_OGG;
137
138Flags:
139
140=over 4
141
142=item *
143
144MIX_INIT_MP3
145
146=item *
147
148MIX_INIT_MOD
149
150=item *
151
152MIX_INIT_FLAC
153
154=item *
155
156MIX_INIT_OGG
157
158=back
159
160B<Note>: Only available for SDL_mixer >= 1.2.10
161
162=head2 quit
163
164 SDL::Mixer::quit();
165
166This function unloads the libraries previously loaded with L<init()|/init>.
167
168B<Note>: Only available for SDL_mixer >= 1.2.10
169
170=head2 linked_version
171
172 $version = SDL::Mixer::linked_version();
173
174C<linked_version> gives you the major-, minor-, and patchlevel for SDL_mixer. This way you can check if e.g. L<init()|/init> and L<quit()|/quit> 
175are available.
176 
177Example:
178
179 use SDL::Mixer;
180 use SDL::Version;
181 
182 my $version = SDL::Mixer::linked_version();
183
184 printf("%d.%d.%d\n", $version->major, $version->minor, $version->patch); # prints "1.2.8" for me
185
186=head2 open_audio
187
188 my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );
189
190C<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 
191your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using 
192L<query_spec>. 
193
194Returns 0 on success, -1 on error.
195
196B<Note>: You must not use C<AUDIO_S16>, C<AUDIO_U16>, C<AUDIO_S16LSB>, or C<AUDIO_U16LSB.> They are not portable, and SDL will not return an 
197error code when they fail. The result will be a horrible staticy noise. You can usually use C<AUDIO_S16SYS>, though not always. Future versions 
198of 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 
199desired audio type is not supported. 
200
201B<Note>: When already initialized, this function will not re-initialize SDL_mixer, nor fail. It will merely increment the number of times 
202L<SDL::Mixer::close_audio|SDL::Mixer/"close_audio"> must be called to actually get it to uninitialize. This serves as a very simplistic method for multiple application 
203components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the 
204latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting. 
205
206Example:
207
208 use SDL;
209 use SDL::Mixer;
210 
211 printf("Error initializing SDL_mixer: %s\n", SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0;
212
213=head2 close_audio
214
215 SDL::Mixer::close_audio();
216
217Close the mixer and halting all playing audio. This function does not return anything.
218
219=head2 query_spec
220
221 my @query_spec = @{ SDL::Mixer::query_spec() };
222
223Find out what the actual audio device parameters are.
224This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.
225
226Example:
227
228 use SDL::Mixer;
229 
230 my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
231 
232 printf("%s, %s, %s, %s\n", $status, $freq, $format, $channels);
233
234=head1 SEE ALSO
235
236L<perl>, L<SDL::Mixer::Channels>, L<SDL::Mixer::Effects>, L<SDL::Mixer::Groups>, L<SDL::Mixer::Music>.
237
238=head1 AUTHORS
239
240See L<SDL/AUTHORS>.
241
242=cut