docs for convert_audio and AudioCVT->build

[sdlgit/SDL-Site.git] / pages / SDL-Audio.html-inc

diff --git a/pages/SDL-Audio.html-inc b/pages/SDL-Audio.html-inc
index 64fc07e..269cefb 100644 (file)
--- a/pages/SDL-Audio.html-inc
+++ b/pages/SDL-Audio.html-inc
@@ -9,11 +9,9 @@
 <ul><li><a href="#open_audio">open_audio</a></li>
 <li><a href="#PauseAudio">PauseAudio </a></li>
 <li><a href="#GetAudioStatus">GetAudioStatus </a></li>
-<li><a href="#load_wav">load_wav </a></li>
+<li><a href="#LoadWAV">LoadWAV </a></li>
 <li><a href="#FreeWAV">FreeWAV </a></li>
-<li><a href="#AudioCVT">AudioCVT </a></li>
-<li><a href="#BuildAudioCVT">BuildAudioCVT </a></li>
-<li><a href="#ConvertAudio">ConvertAudio  </a></li>
+<li><a href="#convert_audio">convert_audio</a></li>
 <li><a href="#MixAudio">MixAudio </a></li>
 <li><a href="#LockAudio">LockAudio</a></li>
 <li><a href="#UnlockAudio">UnlockAudio</a></li>
@@ -61,8 +59,8 @@
 <p>Gets the current audio state</p>
 
 </div>
-<h2 id="load_wav">load_wav </h2>
-<div id="load_wav_CONTENT">
+<h2 id="LoadWAV">LoadWAV </h2>
+<div id="LoadWAV_CONTENT">
 <p>Loads a WAVE file</p>
 
 </div>
@@ -71,19 +69,77 @@
 <p>Frees previously opened WAV data</p>
 
 </div>
-<h2 id="AudioCVT">AudioCVT </h2>
-<div id="AudioCVT_CONTENT">
-<p>Audio Conversion Structure</p>
+<h2 id="convert_audio">convert_audio</h2>
+<div id="convert_audio_CONTENT">
+<pre> SDL::Audio-&gt;convert_audio( cvt, data, len )
 
-</div>
-<h2 id="BuildAudioCVT">BuildAudioCVT </h2>
-<div id="BuildAudioCVT_CONTENT">
-<p>Initializes a SDL_AudioCVT - structure for conversion</p>
-
-</div>
-<h2 id="ConvertAudio">ConvertAudio  </h2>
-<div id="ConvertAudio_CONTENT">
+</pre>
 <p>Converts audio data to a desired audio format.</p>
+<p><code>convert_audio</code> takes as first parameter <code>cvt</code>, which was previously initialized. Initializing a <code>SDL::AudioCVT</code> is a two step process. 
+First of all, the structure must be created via <code>SDL::AudioCVT-</code>build&gt; along with source and destination format parameters. Secondly, 
+the <code>data</code> and <code>len</code> fields must be setup. <code>data</code> should point to the audio data buffer beeing source and destination at 
+once and <code>len</code> should be set to the buffer length in bytes. Remember, the length of the buffer pointed to by buf should be 
+<code>len*len_mult</code> bytes in length.</p>
+<p>Once the <code>SDL::AudioCVT</code> structure is initialized, we can pass it to <code>convert_audio</code>, which will convert the audio data pointed to 
+by <code>data</code>. If <code>convert_audio</code> fails <code>undef</code> is returned, otherwise the converted <code>SDL::AudioCVT</code> structure.</p>
+<p>If the conversion completed successfully then the converted audio data can be read from <code>cvt-</code>buf&gt;. The amount of valid, converted, 
+audio data in the buffer is equal to <code>cvt-</code>len*cvt-&gt;len_ratio&gt;. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Audio;
+ use SDL::AudioSpec;
+ use SDL::AudioCVT;
+
+ # Converting some WAV data to hardware format
+
+ my $desired  = SDL::AudioSpec-&gt;new();
+ my $obtained = SDL::AudioSpec-&gt;new();
+
+ # Set desired format
+ $desired-&gt;freq(22050);
+ $desired-&gt;channels(1);
+ $desired-&gt;format(AUDIO_S16);
+ $desired-&gt;samples(8192);
+
+ # Open the audio device
+ if( SDL::Audio::open_audio($desired, $obtained) &lt; 0 )
+ {
+     printf( STDERR &quot;Couldn't open audio: %s\n&quot;, SDL::get_error() );
+     exit(-1);
+ }
+
+ # Load the test.wav
+ my $wav_ref = SDL::Audio::load_wav('C:/SDL_perl/test/data/sample.wav', $obtained);
+
+ unless( $wav_ref )
+ {
+     printf( STDERR &quot;Could not open sample.wav: %s\n&quot;, SDL::get_error() );
+     SDL::Audio::close_audio();
+     exit(-1);
+ }
+
+ my ( $wav_spec, $wav_buf, $wav_len ) = @{$wav_ref};
+
+ # Build AudioCVT
+ my $wav_cvt = SDL::AudioCVT-&gt;build( $wav_spec-&gt;format, $wav_spec-&gt;channels, $wav_spec-&gt;freq,
+                                     $obtained-&gt;format, $obtained-&gt;channels, $obtained-&gt;freq); 
+
+ # Check that the convert was built
+ unless( $wav_cvt )
+ {
+     printf( STDERR &quot;Couldn't build converter!\n&quot; );
+     SDL::Audio::close_audio();
+     SDL::Audio::free_wav($wav_buf);
+ }
+
+ # And now we're ready to convert
+ SDL::Audio::convert_audio($wav_cvt, $wav_buf, $wav_len);
+
+ # We can delete to original WAV data now
+ SDL::Audio::free_wav($wav_buf);
+
+</pre>
+<p><strong>TODO</strong>: What to do with it? How to use callback? See http://www.libsdl.org/cgi/docwiki.cgi/SDL_ConvertAudio</p>
 
 </div>
 <h2 id="MixAudio">MixAudio </h2>