From: Tobias Leich Date: Thu, 26 Nov 2009 00:18:48 +0000 (+0100) Subject: docs for convert_audio and AudioCVT->build X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=sdlgit%2FSDL-Site.git;a=commitdiff_plain;h=2ace59cf26fb88d05566c1697ab2cf236fef3791 docs for convert_audio and AudioCVT->build --- diff --git a/pages/SDL-Audio.html-inc b/pages/SDL-Audio.html-inc index ff25844..269cefb 100644 --- a/pages/SDL-Audio.html-inc +++ b/pages/SDL-Audio.html-inc @@ -11,9 +11,7 @@
  • GetAudioStatus
  • LoadWAV
  • FreeWAV
    • -
  • AudioCVT
    • -
  • BuildAudioCVT
    • -
  • ConvertAudio
    • +
  • convert_audio
  • MixAudio
  • LockAudio
  • UnlockAudio
    • @@ -71,19 +69,77 @@

    Frees previously opened WAV data

    -

    AudioCVT

    -
    -

    Audio Conversion Structure

    +

    convert_audio

    +
    +
     SDL::Audio->convert_audio( cvt, data, len )
 
-
    -

    BuildAudioCVT

    -
    -

    Initializes a SDL_AudioCVT - structure for conversion

    - -
    -

    ConvertAudio

    -
    +

    Converts audio data to a desired audio format.

    +

    convert_audio takes as first parameter cvt, which was previously initialized. Initializing a SDL::AudioCVT is a two step process. +First of all, the structure must be created via SDL::AudioCVT-build> along with source and destination format parameters. Secondly, +the data and len fields must be setup. data should point to the audio data buffer beeing source and destination at +once and len should be set to the buffer length in bytes. Remember, the length of the buffer pointed to by buf should be +len*len_mult bytes in length.

    +

    Once the SDL::AudioCVT structure is initialized, we can pass it to convert_audio, which will convert the audio data pointed to +by data. If convert_audio fails undef is returned, otherwise the converted SDL::AudioCVT structure.

    +

    If the conversion completed successfully then the converted audio data can be read from cvt-buf>. The amount of valid, converted, +audio data in the buffer is equal to cvt-len*cvt->len_ratio>.

    +

    Example:

    +
     use SDL;
+ use SDL::Audio;
+ use SDL::AudioSpec;
+ use SDL::AudioCVT;
+
+ # Converting some WAV data to hardware format
+
+ my $desired  = SDL::AudioSpec->new();
+ my $obtained = SDL::AudioSpec->new();
+
+ # Set desired format
+ $desired->freq(22050);
+ $desired->channels(1);
+ $desired->format(AUDIO_S16);
+ $desired->samples(8192);
+
+ # Open the audio device
+ if( SDL::Audio::open_audio($desired, $obtained) < 0 )
+ {
+     printf( STDERR "Couldn't open audio: %s\n", 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 "Could not open sample.wav: %s\n", 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->build( $wav_spec->format, $wav_spec->channels, $wav_spec->freq,
+                                     $obtained->format, $obtained->channels, $obtained->freq); 
+
+ # Check that the convert was built
+ unless( $wav_cvt )
+ {
+     printf( STDERR "Couldn't build converter!\n" );
+     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);
+
+
    +

    TODO: What to do with it? How to use callback? See http://www.libsdl.org/cgi/docwiki.cgi/SDL_ConvertAudio

    MixAudio

    diff --git a/pages/SDL-AudioCVT.html-inc b/pages/SDL-AudioCVT.html-inc index c87b527..90a9475 100644 --- a/pages/SDL-AudioCVT.html-inc +++ b/pages/SDL-AudioCVT.html-inc @@ -3,19 +3,114 @@

    Index

    NAME

    Top

    -

    SDL::AudioCVT -- Bindings to SDL structure SDL_AudioCVT

    +

    SDL::AudioCVT -- Audio Conversion Structure

    CATEGORY

    Top

    -

    TODO, Core, Audio

    +

    Core, Audio, Structure

    + +
    +

    SYNOPSIS

    Top

    +
    + +
    +

    DESCRIPTION

    Top

    +
    +

    The SDL::AudioCVT is used to convert audio data between different formats. A SDL::AudioCVT structure is created with the +SDL::AudioCVT-build> function, while the actual conversion is done by the SDL::Audio::convert_audio function.

    + +
    +

    METHODS

    Top

    +
    + +
    +

    new

    +
    +

    This constructor returns an empty SDL::AudioCVT structure.

    + +
    +

    new

    +
    +
     $cvt = SDL::AudioCVT->build( $src_format, $src_channels, $src_rate
+                              $dst_format, $dst_channels, $dst_rate );
+
+
    +

    Before an SDL::AudioCVT structure can be used to convert audio data it must be initialized with source and destination information.

    +

    src_format and dst_format are the source and destination format of the conversion. (For information on audio formats see +SDL::AudioSpec). src_channels and dst_channels are the number of channels in the source and destination formats. +Finally, src_rate and dst_rate are the frequency or samples-per-second of the source and destination formats. Once again, +see SDL::AudioSpec.

    +

    Currently (SDL-1.2.11) only rate conversions of 2x and (1/2)x with x > 0 are done, nearing the requested rate conversion.

    +

    See SDL::Audio::convert_audio.

    + +
    +

    needed

    +
    +

    Set to one if the conversion is possible

    + +
    +

    src_format

    +
    +

    Audio format of the source

    + +
    +

    dest_format

    +
    +

    Audio format of the destination

    + +
    +

    rate_incr

    +
    +

    Rate conversion increment

    + +
    +

    len

    +
    +

    Length of the original audio buffer in bytes

    + +
    +

    len_cvt

    +
    +

    Length of converted audio buffer in bytes (calculated)

    + +
    +

    len_mult

    +
    +

    buf must be len*len_mult bytes in size (calculated)

    + +
    +

    len_ratio

    +
    +

    Final audio size is len*len_ratio

    + +
    +

    AUTHOR

    Top

    +
    +

    Tobias Leich

    \ No newline at end of file diff --git a/pages/SDL-Mixer-MixChunk.html-inc b/pages/SDL-Mixer-MixChunk.html-inc index 84c7988..5dd20c7 100644 --- a/pages/SDL-Mixer-MixChunk.html-inc +++ b/pages/SDL-Mixer-MixChunk.html-inc @@ -22,7 +22,7 @@

    CATEGORY

    Top

    -

    Mixer, Structure

    +

    Core, Mixer, Structure

    SYNOPSIS

    Top

    diff --git a/pages/documentation.html-inc b/pages/documentation.html-inc index dc4dc09..2c8d895 100644 --- a/pages/documentation.html-inc +++ b/pages/documentation.html-inc @@ -1,2 +1,2 @@
    -

    Documentation (latest development branch)

    Core
    thumbSDL Simple DirectMedia Layer for Perl
    Structure
    thumbSDL::AudioSpec- SDL Bindings for structure SDL::AudioSpec
    CDROM
    thumbSDL::CDROM- SDL Bindings for the CDROM device
    Structure
    thumbSDL::CD- SDL Bindings for structure SDL_CD
    thumbSDL::CDTrack- SDL Bindings for structure SDL_CDTrack
    Events
    thumbSDL::Events Bindings to the Events Category in SDL API
    Structure
    thumbSDL::Event General event structure
    Joystick
    thumbSDL::Joystick- SDL Bindings for the Joystick device
    Mouse
    thumbSDL::Mouse- SDL Bindings for the Mouse device
    Structure
    thumbSDL::Cursor- Mouse cursor structure
    MultiThread
    thumbSDL::MultiThread Bindings to the MultiThread category in SDL API
    Structure
    thumbSDL::Version- SDL Bindings for structure SDL_Version
    Video
    thumbSDL::Video Bindings to the video category in SDL API
    Structure
    thumbSDL::Color Format independent color description
    thumbSDL::Overlay YUV Video overlay
    thumbSDL::PixelFormat Stores surface format information
    thumbSDL::Rect Defines a rectangular area
    thumbSDL::Surface
    thumbSDL::VideoInfo Video Target Information

    Cookbook
    thumbSDL::Cookbook
    thumbSDL::Cookbook::PDL

    Extension
    thumbSDL::App a SDL perl extension

    Mixer
    thumbSDL::Mixer a SDL perl extension
    Structure
    thumbSDL::Mixer::MixChunk- SDL Bindings for structure SDL_MixChunk
    TODO
    Core
    Audio
    thumbSDL::Audio- SDL Bindings for Audio
    thumbSDL::AudioCVT- Bindings to SDL structure SDL_AudioCVT
    Structure
    thumbSDL::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic
    Structure
    thumbSDL::RWOps- SDL Bindings to SDL_RWOPs

    Tutorials
    thumbSDL::Tutorial introduction to Perl SDL
    thumbSDL::Tutorial::Animation
    thumbSDL::Tutorial::Images
    thumbSDL::Tutorial::LunarLander a small tutorial on Perl SDL
    thumbSDL::Tutorial::Pong
    thumbSDL::Tutorial::Tetris

    UNCATEGORIZED
    thumbSDL::Font a SDL perl extension
    thumbSDL::Game::Palette a perl extension
    thumbSDL::MPEG a SDL perl extension
    thumbSDL::Music a perl extension
    thumbSDL::OpenGL a perl extension
    thumbSDL::Palette a perl extension
    thumbSDL::SFont a perl extension
    thumbSDL::SMPEG a SDL perl extension
    thumbSDL::Sound a perl extension
    thumbSDL::TTFont a SDL perl extension
    thumbSDL::Timer a SDL perl extension for managing timers.
    thumbSDL::Tool::Font a perl extension
    thumbSDL::Tool::Graphic
    thumbSDL::old-cdrom a SDL perl extension for managing CD-ROM drives
    +

    Documentation (latest development branch)

    Core
    thumbSDL Simple DirectMedia Layer for Perl
    Structure
    thumbSDL::AudioCVT- Audio Conversion Structure
    thumbSDL::AudioSpec- SDL Bindings for structure SDL::AudioSpec
    CDROM
    thumbSDL::CDROM- SDL Bindings for the CDROM device
    Structure
    thumbSDL::CD- SDL Bindings for structure SDL_CD
    thumbSDL::CDTrack- SDL Bindings for structure SDL_CDTrack
    Events
    thumbSDL::Events Bindings to the Events Category in SDL API
    Structure
    thumbSDL::Event General event structure
    Joystick
    thumbSDL::Joystick- SDL Bindings for the Joystick device
    Structure
    thumbSDL::Mixer::MixChunk- SDL Bindings for structure SDL_MixChunk
    Mouse
    thumbSDL::Mouse- SDL Bindings for the Mouse device
    Structure
    thumbSDL::Cursor- Mouse cursor structure
    MultiThread
    thumbSDL::MultiThread Bindings to the MultiThread category in SDL API
    Structure
    thumbSDL::Version- SDL Bindings for structure SDL_Version
    Video
    thumbSDL::Video Bindings to the video category in SDL API
    Structure
    thumbSDL::Color Format independent color description
    thumbSDL::Overlay YUV Video overlay
    thumbSDL::PixelFormat Stores surface format information
    thumbSDL::Rect Defines a rectangular area
    thumbSDL::Surface
    thumbSDL::VideoInfo Video Target Information

    Cookbook
    thumbSDL::Cookbook
    thumbSDL::Cookbook::PDL

    Extension
    thumbSDL::App a SDL perl extension

    Mixer
    thumbSDL::Mixer a SDL perl extension
    TODO
    Core
    Audio
    thumbSDL::Audio- SDL Bindings for Audio
    Structure
    thumbSDL::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic
    Structure
    thumbSDL::RWOps- SDL Bindings to SDL_RWOPs

    Tutorials
    thumbSDL::Tutorial introduction to Perl SDL
    thumbSDL::Tutorial::Animation
    thumbSDL::Tutorial::Images
    thumbSDL::Tutorial::LunarLander a small tutorial on Perl SDL
    thumbSDL::Tutorial::Pong
    thumbSDL::Tutorial::Tetris

    UNCATEGORIZED
    thumbSDL::Font a SDL perl extension
    thumbSDL::Game::Palette a perl extension
    thumbSDL::MPEG a SDL perl extension
    thumbSDL::Music a perl extension
    thumbSDL::OpenGL a perl extension
    thumbSDL::Palette a perl extension
    thumbSDL::SFont a perl extension
    thumbSDL::SMPEG a SDL perl extension
    thumbSDL::Sound a perl extension
    thumbSDL::TTFont a SDL perl extension
    thumbSDL::Timer a SDL perl extension for managing timers.
    thumbSDL::Tool::Font a perl extension
    thumbSDL::Tool::Graphic
    thumbSDL::old-cdrom a SDL perl extension for managing CD-ROM drives