Provided by: allegro5-doc_5.0.10-2_all bug


       al_create_audio_stream - Allegro 5 API


              #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)


       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.


       · 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

                     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.