trusty (3) al_create_audio_stream.3alleg5.gz

NAME

       al_create_audio_stream - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro_audio.h>

              ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t fragment_count,
                 unsigned int frag_samples, unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,
                 ALLEGRO_CHANNEL_CONF chan_conf)

DESCRIPTION

       Creates an ALLEGRO_AUDIO_STREAM(3alleg5).  The stream will be set to play by default.  It will feed audio
       data from a buffer, which is split into a number of fragments.

       Parameters:

       • fragment_count - How many fragments to use for the  audio  stream.   Usually  only  two  fragments  are
         required - splitting the audio buffer in two halves.  But it means that the only time when new data can
         be supplied is whenever one half has finished playing.  When using many fragments, you usually will use
         fewer samples for one, so there always will be (small) fragments available to be filled with new data.

       • frag_samples - The size of a fragment in samples.  See note below.

       • freq - The frequency, in Hertz.

       • depth - Must be one of the values listed for ALLEGRO_AUDIO_DEPTH(3alleg5).

       • chan_conf - Must be one of the values listed for ALLEGRO_CHANNEL_CONF(3alleg5).

       The  choice  of  fragment_count, frag_samples and freq directly influences the audio delay.  The delay in
       seconds can be expressed as:

              delay = fragment_count * frag_samples / freq

       This is only the delay due to Allegro's streaming, there may be additional delay caused by sound  drivers
       and/or hardware.

              Note: If you know the fragment size in bytes, you can get the size in samples like this:

                     sample_size = al_get_channel_count(chan_conf) * al_get_audio_depth_size(depth);
                     samples = bytes_per_fragment / sample_size;

              The size of the complete buffer is:

                     buffer_size = bytes_per_fragment * fragment_count

              Note: unlike many Allegro objects, audio streams are not implicitly destroyed when Allegro is shut
              down.  You must destroy them  manually  with  al_destroy_audio_stream(3alleg5)  before  the  audio
              system is shut down.