/lib/pods/SDL/Mixer.pod
Unknown | 242 lines | 144 code | 98 blank | 0 comment | 0 complexity | e3d9c35526c03d121c4e986e75c3780f MD5 | raw file
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