/lib/pods/SDL/Audio.pod

  1
  2=pod
  3
  4=head1 NAME
  5
  6SDL::Audio - SDL Bindings for Audio
  7
  8=head1 CATEGORY
  9
 10Core, Audio
 11
 12=head1 CONSTANTS
 13
 14The constants are exported by default. You can avoid this by doing:
 15
 16 use SDL::Audio ();
 17
 18and access them directly:
 19
 20 SDL::Audio::AUDIO_S16SYS;
 21
 22or by choosing the export tags below:
 23
 24Export tag: ':format'
 25
 26 AUDIO_U8
 27 AUDIO_S8
 28 AUDIO_U16LSB
 29 AUDIO_S16LSB
 30 AUDIO_U16MSB
 31 AUDIO_S16MSB
 32 AUDIO_U16
 33 AUDIO_S16 
 34 AUDIO_U16SYS
 35 AUDIO_S16SYS
 36
 37Export tag: ':status'
 38
 39 SDL_AUDIO_STOPPED
 40 SDL_AUDIO_PLAYING
 41 SDL_AUDIO_PAUSED
 42
 43=head1 METHODS
 44
 45=head2 open
 46
 47  use SDL;
 48  use SDL::Audio;
 49  
 50  SDL::init(SDL_INIT_AUDIO);
 51
 52  my $desired = SDL::AudioSpec->new();
 53  
 54  my $obtained;
 55
 56  SDL::Audio::open( $desired, $obtained );
 57  
 58  # $obtained->... (A new SDL::AudioSpec now);
 59
 60This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by obtained. If obtained is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the hardware audio format if necessary. This function returns -1 if it failed to open the audio device, or couldn't set up the audio thread.
 61
 62To open the audio device a desired SDL::AudioSpec must be created.
 63
 64  my $desired = SDL::AudioSpec->new();
 65
 66You must then fill this structure with your desired audio specifications.
 67
 68=over 
 69
 70=item The desired audio frequency in samples-per-second. 
 71
 72    $desired->freq
 73
 74=item The desired audio format. See L<SDL::AudioSpec>
 75    
 76    $desired->format
 77
 78=item The desired channels (1 for mono, 2 for stereo, 4 for surround, 6 for surround with center and lfe). 
 79
 80    $desired->channels
 81
 82=item The desired size of the audio buffer in samples. This number should be a power of two, and may be adjusted by the audio driver to a value more suitable for the hardware. Good values seem to range between 512 and 8192 inclusive, depending on the application and CPU speed. Smaller values yield faster response time, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time. A stereo sample consists of both right and left channels in LR ordering. Note that the number of samples is directly related to time by the following formula: ms = (samples*1000)/freq 
 83
 84    $desired->samples
 85    
 86=item This should be set to a function that will be called when the audio device is ready for more data. It is passed a pointer to the audio buffer, and the length in bytes of the audio buffer. This function usually runs in a separate thread, and so you should protect data structures that it accesses by calling SDL::Audio::lock and SDL::Audio::unlock in your code. 
 87
 88THIS IS NOT READY YET
 89
 90    $desired->callback
 91
 92    my $callback = sub{ my ($userdata, $stream, $len) = @_;  };
 93
 94    $userdata is a reference stored in the userdata field of the SDL::AudioSpec. 
 95    $stream is a pointer to the audio buffer you want to fill with information and $len is the length of the audio buffer in bytes.
 96
 97    $desired->userdata
 98
 99    This pointer is passed as the first parameter to the callback function. 
100
101=back
102
103SDL::Audio::open reads these fields from the desired SDL::AudioSpec structure passed to the function and attempts to find an audio configuration matching your desired. As mentioned above, if the obtained parameter is NULL then SDL with convert from your desired audio settings to the hardware settings as it plays.
104
105If obtained is NULL then the desired SDL::AudioSpec is your working specification, otherwise the obtained SDL::AudioSpec becomes the working specification and the desired specification can be deleted. The data in the working specification is used when building L<SDL::AudioCVT>'s for converting loaded data to the hardware format.
106
107SDL::Audio::open calculates the size and silence fields for both the $desired and $obtained specifications. The size field stores the total size of the audio buffer in bytes, while the silence stores the value used to represent silence in the audio buffer
108
109The audio device starts out playing silence when it's opened, and should be enabled for playing by calling SDL::Audio::pause(0) when you are ready for your audio callback function to be called. Since the audio driver may modify the requested size of the audio buffer, you should allocate any local mixing buffers after you open the audio device. 
110
111=head2 pause
112
113 pause( $bool )
114
115This function pauses and unpauses the audio callback processing. It should be called with C<$bool = 0> after opening the audio device to 
116start playing sound. This is so you can safely initialize data for your callback function after opening the audio device. Silence will 
117be written to the audio device during the pause.
118
119=head2 get_status
120
121 int get_status();
122
123Returns either C<SDL_AUDIO_STOPPED>, C<SDL_AUDIO_PLAYING> or C<SDL_AUDIO_PAUSED> depending on the current audio state. 
124
125=head2 load_wav 
126
127 SDL::AudioSpec load_wav( $filename, $spec );
128
129This function loads a WAVE file into memory.
130
131If this function succeeds, it returns the given C<SDL::AudioSpec>, filled with the audio data format of the wave data, and sets C<buf> 
132to a buffer containing the audio data, and sets C<len> to the length of that audio buffer, in bytes. You need to free the audio buffer 
133with C<SDL::Audio::free_wav> when you are done with it.
134
135This function returns NULL and sets the SDL error message if the wave file cannot be opened, uses an unknown data format, or is corrupt. 
136Currently raw, MS-ADPCM and IMA-ADPCM WAVE files are supported.
137
138Example:
139
140 use SDL;
141 use SDL::Audio;
142 use SDL::AudioSpec;
143 
144 SDL::init(SDL_INIT_AUDIO);
145 
146 # Converting some WAV data to hardware format
147
148 my $desired  = SDL::AudioSpec->new();
149 my $obtained = SDL::AudioSpec->new();
150 
151 # Set desired format
152 $desired->freq(22050);
153 $desired->channels(1);
154 $desired->format(AUDIO_S16);
155 $desired->samples(8192);
156 
157 # Open the audio device
158 if( SDL::Audio::open($desired, $obtained) < 0 )
159 {
160     printf( STDERR "Couldn't open audio: %s\n", SDL::get_error() );
161     exit(-1);
162 }
163 
164 # Load the test.wav
165 my $wav_ref = SDL::Audio::load_wav('../../test/data/sample.wav', $obtained);
166 
167 unless( $wav_ref )
168 {
169     warn( "Could not open sample.wav: %s\n", SDL::get_error() );
170     SDL::Audio::close_audio();
171     SDL::quit;
172     exit(-1);
173 }
174 
175 my ( $wav_spec, $wav_buf, $wav_len ) = @{$wav_ref};
176
177=head2 free_wav 
178
179 free_wav( $buffer )
180
181After a WAVE file has been opened with C<load_wav> its data can eventually be freed with C<free_wav>. C<buffer> is the buffer created 
182by C<load_wav>. 
183
184=head2 convert
185
186 SDL::Audio->convert( cvt, data, len )
187 
188Converts audio data to a desired audio format.
189
190C<convert> takes as first parameter C<cvt>, which was previously initialized. Initializing a C<SDL::AudioCVT> is a two step process. 
191First of all, the structure must be created via C<SDL::AudioCVT-E<gt>build> along with source and destination format parameters. Secondly, 
192the C<data> and C<len> fields must be setup. C<data> should point to the audio data buffer being source and destination at 
193once and C<len> should be set to the buffer length in bytes. Remember, the length of the buffer pointed to by buf should be 
194C<len*len_mult> bytes in length.
195
196Once the C<SDL::AudioCVT> structure is initialized, we can pass it to C<convert>, which will convert the audio data pointed to 
197by C<data>. If C<convert> fails C<undef> is returned, otherwise the converted C<SDL::AudioCVT> structure.
198
199If the conversion completed successfully then the converted audio data can be read from C<cvt-E<gt>buf>. The amount of valid, converted, 
200audio data in the buffer is equal to C<cvt-E<gt>len*cvt-E<gt>len_ratio>. 
201
202Example:
203
204 use SDL;
205 use SDL::Audio;
206 use SDL::AudioSpec;
207 use SDL::AudioCVT;
208 
209 SDL::init(SDL_INIT_AUDIO);
210 
211 # Converting some WAV data to hardware format
212
213 my $desired  = SDL::AudioSpec->new();
214 my $obtained = SDL::AudioSpec->new();
215 
216 # Set desired format
217 $desired->freq(22050);
218 $desired->channels(1);
219 $desired->format(AUDIO_S16);
220 $desired->samples(8192);
221 
222 # Open the audio device
223 if( SDL::Audio::open($desired, $obtained) < 0 )
224 {
225     printf( STDERR "Couldn't open audio: %s\n", SDL::get_error() );
226     exit(-1);
227 }
228 
229 # Load the test.wav
230 my $wav_ref = SDL::Audio::load_wav('../../test/data/sample.wav', $obtained);
231 
232 unless( $wav_ref )
233 {
234     warn( "Could not open sample.wav: %s\n", SDL::get_error() );
235     SDL::Audio::close_audio();
236     SDL::quit;
237     exit(-1);
238 }
239 
240 my ( $wav_spec, $wav_buf, $wav_len ) = @{$wav_ref};
241 
242 # Build AudioCVT
243 my $wav_cvt = SDL::AudioCVT->build( $wav_spec->format, $wav_spec->channels, $wav_spec->freq,
244                                     $obtained->format, $obtained->channels, $obtained->freq); 
245
246 # Check that the convert was built
247 if( $wav_cvt == -1 )
248 {
249     warn( "Couldn't build converter!\n" );
250     SDL::Audio::close();
251     SDL::Audio::free_wav($wav_buf);
252     SDL::quit();
253     exit(-1);
254 }
255 
256 # And now we're ready to convert
257 SDL::Audio::convert($wav_cvt, $wav_buf, $wav_len);
258 
259 # We can free original WAV data now
260 SDL::Audio::free_wav($wav_buf);
261 
262B<TODO>: What to do with it? How to use callback? See http://www.libsdl.org/cgi/docwiki.cgi/SDL_ConvertAudio
263
264=head2 mix
265
266Mixes audio data
267
268B<Not implemented yet>. See: L<http://www.libsdl.org/cgi/docwiki.cgi/SDL_MixAudio>
269
270=head2 lock
271
272 lock();
273
274The lock manipulated by these functions protects the callback function. During a C<lock> period, you can be guaranteed that the callback 
275function is not running. Do not call this from the callback function or you will cause deadlock.
276
277=head2 unlock
278
279 unlock();
280
281Unlocks a previous C<lock> call.
282
283=head2 close 
284
285 close();
286
287Shuts down audio processing and closes the audio device.  
288
289=head1 AUTHORS
290
291See L<SDL/AUTHORS>.
292
293=cut
294