NewAPI/Sound

From Allegro Wiki

This article is incomplete and needs some revision or has some pending TODOs. Please help Allegro by editing and finishing it. When the article becomes complete, you may remove this tag.

The new mixer API is designed to handle a series of voices (which represent system-supplied sound card voices), that have an attached audio sample (predefined audio data that's fed as-needed) or a mixer (which generates audio data by mixing audio samples and/or other mixers attached to it and feeds it as-needed). Current implementation does signed 24-bit integer mixing, can handle input and output of 8, 16, and 24-bit (signed or unsigned), and handles up to 7.1 channels, with more possible.

Pre-defined sample data must have the same channel count and configuration as the sample it's given to. A mixer can be used to do software mixing, as well as provide a platform for post-mixed audio effects. A mixer must have the same frequency as the object it's attached to (a voice or another mixer). A sample attached to a voice must have the same depth, signedness, and frequency. Both mixers and samples must have the same channel configuration as the object they're attached to. A higher-level API is planned to help with these conversions.

The current code is here: audio api.

It contains a thrown-together mutex API (which should, hopefully, be identical to Allegro 4.9's), OpenAL and ALSA driver implementations, and a sample program. To compile it into a program you will need OpenAL (1.1 or later recommended; older versions may not work) and pthreads. Both are available for Windows and Unix.

PS. The use of the mixer in the sample program is something I did to help testing. The program can easily be made to play without it.

In the following AL_* constants have been renamed to ALLEGRO_*. The source code still calls them AL_*.

1 Overview
2 Audio API

Overview

Voices represent system-supplied sound card channels. Feeding data into voices causes sound to be output from speakers, or whatever else the operating system chooses to do with it.

Voices can be fed by attaching one of three objects:

samples: predefined audio data
streams: audio data generated on-the-fly
mixers

Mixers take the output of one or more samples or streams and generates data by mixing them together. Mixers can also take the output of other mixers as input. Mixer attachments cannot form a loop.

Pre-defined sample data must have the same channel count and configuration as the mixer it's given to. A mixer can be used to do software mixing, as well as provide a platform for post-mixed audio effects. A mixer must have the same frequency as the object it's attached to (a voice or another mixer). A sample attached to a voice must have the same depth, signedness, and frequency. Both mixers and samples must have the same channel configuration as the object they're attached to.

In the future, a higher-level API may help with sample data conversions.

Audio API

Constants

Sample depth and type


    ALLEGRO_AUDIO_8_BIT_INT
    ALLEGRO_AUDIO_16_BIT_INT
    ALLEGRO_AUDIO_24_BIT_INT
    ALLEGRO_AUDIO_32_BIT_FLOAT   - -1.0 to +1.0

    ALLEGRO_AUDIO_UNSIGNED

For convenience:


    ALLEGRO_AUDIO_8_BIT_UINT  =
            ALLEGRO_AUDIO_8_BIT_INT  | ALLEGRO_AUDIO_UNSIGNED

    ALLEGRO_AUDIO_16_BIT_UINT =
            ALLEGRO_AUDIO_16_BIT_INT | ALLEGRO_AUDIO_UNSIGNED

    ALLEGRO_AUDIO_24_BIT_UINT =
            ALLEGRO_AUDIO_24_BIT_INT | ALLEGRO_AUDIO_UNSIGNED

Speaker configuration

Speaker configuration (mono, stereo, 2.1, 3, etc). With regards to behavior, most of this code makes no distinction between, say, 4.1 and 5 speaker setups --- they both have 5 "channels". However, users would like the distinction, and later when the higher-level stuff is added, the differences will become more important.


    ALLEGRO_AUDIO_1_CH
    ALLEGRO_AUDIO_1_1_CH
    ALLEGRO_AUDIO_2_CH
    ALLEGRO_AUDIO_2_1_CH
    ALLEGRO_AUDIO_3_CH
    ALLEGRO_AUDIO_3_1_CH
    ALLEGRO_AUDIO_4_CH
    ALLEGRO_AUDIO_4_1_CH
    ALLEGRO_AUDIO_5_CH
    ALLEGRO_AUDIO_5_1_CH
    ALLEGRO_AUDIO_6_CH
    ALLEGRO_AUDIO_6_1_CH
    ALLEGRO_AUDIO_7_CH
    ALLEGRO_AUDIO_7_1_CH

XXX do we really need "1.1", "3", "3.1"?

XXX rename to ALLEGRO_AUDIO_CH_xxx?

Sample looping mode

    ALLEGRO_AUDIO_PLAY_ONCE
    ALLEGRO_AUDIO_ONE_DIR
    ALLEGRO_AUDIO_BI_DIR

Mixer quality

    ALLEGRO_AUDIO_POINT
    ALLEGRO_AUDIO_LINEAR

Audio object properties

    ALLEGRO_AUDIO_DEPTH
    ALLEGRO_AUDIO_CHANNELS
    ALLEGRO_AUDIO_FREQUENCY

    ALLEGRO_AUDIO_PLAYING
    ALLEGRO_AUDIO_ATTACHED

    ALLEGRO_AUDIO_LENGTH
    ALLEGRO_AUDIO_BUFFER

    ALLEGRO_AUDIO_LOOPMODE
    ALLEGRO_AUDIO_SPEED
    ALLEGRO_AUDIO_POSITION
    ALLEGRO_AUDIO_ORPHAN_BUFFER

    ALLEGRO_AUDIO_FRAGMENTS
    ALLEGRO_AUDIO_USED_FRAGMENTS

    ALLEGRO_AUDIO_QUALITY

    ALLEGRO_AUDIO_SETTINGS

    ALLEGRO_AUDIO_DEVICE

XXX I don't like this loose collection of constants

Bit-field flags for voice settings

This says whether the voice settings were required.

    ALLEGRO_AUDIO_REQUIRE

Types

ALLEGRO_SAMPLE

    typedef struct ALLEGRO_SAMPLE ALLEGRO_SAMPLE;

An ALLEGRO_SAMPLE object stores the data necessary for playing predefined digital audio. It holds information pertaining to data length, the looping mode, loop start/end points, playing position, playing frequency, channel configuration, etc. As such, you cannot have an ALLEGRO_SAMPLE object playing multiple times simultaneously. The object holds a user-specified PCM data buffer of the format the object is created with. Multiple objects may be created using the same data buffer.

To be played, an ALLEGRO_SAMPLE object must be attached to an ALLEGRO_VOICE object, or to a mixer chain which is attached to an ALLEGRO_VOICE object.

An ALLEGRO_SAMPLE object uses the following fields:

ALLEGRO_AUDIO_DEPTH (enum): Gets the bit depth format the object was created with. This may not be changed after the object is created.
ALLEGRO_AUDIO_CHANNELS (enum): Gets the channel configuration the object was created with. This may not be changed after the object is created.
ALLEGRO_AUDIO_FREQUENCY (long): Gets the frequency (in Hz) the object was created with. This may not be changed after the object is created. To change playback speed, see ALLEGRO_AUDIO_SPEED.
ALLEGRO_AUDIO_PLAYING (bool): Gets or sets the object's playing status. By default, it is stopped. Note that simply setting it true does not cause the object to play. It must also be attached to a voice, directly or indirectly (eg. sample->voice, sample->mixer->voice, sample->mixer->...->voice).
ALLEGRO_AUDIO_ATTACHED (bool): Gets the object's attachment status (true if it is attached to a something, false if not). Setting this to false detaches the object from whatever it is attached to. You may not directly set this to true.
ALLEGRO_AUDIO_LENGTH (long): Gets or sets the length of the object's data buffer, in samples-per-channel. When changing the length, you must make sure the current buffer is large enough. You may not change the length while the object is set to play.
ALLEGRO_AUDIO_BUFFER (ptr): Gets or sets the object's data buffer. You may not get or set this if the object is set to play, and you may not get this if the buffer was previously orphaned (see ALLEGRO_AUDIO_ORPHAN_BUFFER).
ALLEGRO_AUDIO_LOOPMODE (enum): Gets or sets the object's looping mode. Setting this may fail if the object is attached to a voice and the audio driver does not support the requested looping mode.
ALLEGRO_AUDIO_SPEED (float): Gets or sets the object's playing speed. Negative values will cause the object to play backwards. If the value is set too close to 0, this will fail to set. XXX I don't like the negative values thing.
ALLEGRO_AUDIO_POSITION (long): Gets or sets the object's playing position. The value is in samples-per-channel.
ALLEGRO_AUDIO_ORPHAN_BUFFER (bool): Setting this flag to true will cause the object's data buffer to be free()'d automatically when either the sample is destroyed, or the buffer is changed (setting an ALLEGRO_AUDIO_BUFFER value). If you set another ALLEGRO_AUDIO_BUFFER value, this will revert back to false. You may not directly set this to false. You must not orphan a buffer that is referenced outside of the object.

ALLEGRO_STREAM

    typedef struct ALLEGRO_STREAM ALLEGRO_STREAM;

An ALLEGRO_STREAM object is used to stream generated audio to the sound device, in real-time. As with ALLEGRO_SAMPLE objects, they store information necessary for playback, so you may not play one multiple times simultaneously. They also need to be attached to an #allegro_voice object, or to an [#allegro_mixer] object which, eventually, reaches an ALLEGRO_VOICE object.

While playing, you must periodically supply new buffer data by first checking ALLEGRO_AUDIO_USED_FRAGMENTS, then refilling the buffers via ALLEGRO_AUDIO_BUFFER. If you're late with supplying new data, the object will be silenced until new data is provided.

ALLEGRO_STREAM objects use the following fields:

ALLEGRO_AUDIO_DEPTH (enum): Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIO_CHANNELS (enum): Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIO_FREQUENCY (enum): Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIO_ATTACHED (bool): Same as ALLEGRO_SAMPLE
ALLEGRO_AUDIO_PLAYING (bool): Same as ALLEGRO_SAMPLE, with the exception that ALLEGRO_STREAM objects are set to play by default.
ALLEGRO_AUDIO_SPEED (float): Same as ALLEGRO_SAMPLE, with the added caveat that negative values aren't allowed.
ALLEGRO_AUDIO_LENGTH (long): This gets the length, in samples-per-channel, of the individual buffer fragments. You may not set this after the object is created.
ALLEGRO_AUDIO_BUFFER (ptr): This gets the next buffer fragment that needs to be filled. After the buffer is filled, this field must be set to the same pointer value to let the object know the new data is ready.
ALLEGRO_AUDIO_FRAGMENTS (long): This gets the total number of buffer fragments the object was created with. You may not set this after the object is created.
ALLEGRO_AUDIO_USED_FRAGMENTS (long): This gets the number of buffer fragments that are waiting to be refilled. This value is decreased when ALLEGRO_AUDIO_BUFFER is used to retrieve a waiting buffer fragment. You may not set this value.

ALLEGRO_MIXER

A mixer object. Mixers can have either samples, streams or other mixers attached to them. Mixer chains cannot form a loop.

ALLEGRO_VOICE

An ALLEGRO_VOICE represents a system-supplied sound card voice. Voices can have samples, streams or mixers attached to them.

ALLEGRO_AUDIO_DRIVER

An audio driver.

Sample routines

al_sample_get_long

    int al_sample_get_long(const ALLEGRO_SAMPLE *spl,
                           ALLEGRO_AUDIO_ENUM setting,
                           unsigned long *val);

Get the value of an integer property of a sample object. setting specifies which property, and may one of of:

ALLEGRO_AUDIO_FREQUENCY - the sample's frequency
ALLEGRO_AUDIO_LENGTH - the length of the sample
ALLEGRO_AUDIO_POSITION - return the position in the sample that playback is up to

Return value:

Returns zero on success. The value of the property will be stored in val.

XXX rename long to int everywhere?

See also: #al_sample_set_long.

al_sample_get_float

    int al_sample_get_float(const ALLEGRO_SAMPLE *spl,
                            ALLEGRO_AUDIO_ENUM setting,
                            float *val)

Get the value of a floating point property of a sample object. setting specifies which property, and may one of of:

ALLEGRO_AUDIO_SPEED - the playback speed

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_sample_set_float.

al_sample_get_enum

    int al_sample_get_enum(const ALLEGRO_SAMPLE *spl,
                           ALLEGRO_AUDIO_ENUM setting,
                           ALLEGRO_AUDIO_ENUM *val)

Get the value of an enumeration property of a sample object. setting specifies which property, and may one of of:

ALLEGRO_AUDIO_DEPTH - the sample depth and type
ALLEGRO_AUDIO_CHANNELS - the number of channels of the sample
ALLEGRO_AUDIO_LOOPMODE - the looping mode of the sample. Can be one of: ALLEGRO_AUDIO_PLAY_ONCE, ALLEGRO_AUDIO_ONE_DIR, ALLEGRO_AUDIO_BI_DIR.

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_sample_set_enum.

al_sample_get_bool

    int al_sample_get_bool(const ALLEGRO_SAMPLE *spl,
                           ALLEGRO_AUDIO_ENUM setting,
                           bool *val)

Get the value of an boolean property of a sample object. setting specifies which property, and may one of of:

ALLEGRO_AUDIO_PLAYING - whether the sample is currently playing
ALLEGRO_AUDIO_ATTACHED - whether the sample is attached to another object
ALLEGRO_AUDIO_ORPHAN_BUFFER - whether the sample will attempt to free its sample data buffer when the buffer pointer changes or the sample is destroyed

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_sample_set_bool.

al_sample_get_ptr

    int al_sample_get_ptr(const ALLEGRO_SAMPLE *spl,
                          ALLEGRO_AUDIO_ENUM setting,
                          void **val)

Get the value of a pointer property of a sample object. setting specifies which property, and may one of of:

ALLEGRO_AUDIO_BUFFER - the buffer containing audio data for the sample

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_sample_set_ptr.

al_sample_play

    void al_sample_play(AL_SAMPLE *spl);

Start playback of the sample. Equivalent to:

    al_sample_set_bool(spl, AL_AUDIO_PLAYING, 1);

XXX shouldn't this have a return value?

See also: #al_sample_set_bool, [#al_sample_stop].

al_sample_stop

    void al_sample_stop(AL_SAMPLE *spl);

Stop playback. Equivalent to:

    al_sample_set_bool(spl, AL_AUDIO_PLAYING, 0);

XXX shouldn't this have a return value?

See also: #al_sample_set_bool, [#al_sample_play].

al_sample_set_long

    int al_sample_set_long(ALLEGRO_SAMPLE *spl,
                           ALLEGRO_AUDIO_ENUM setting,
                           unsigned long val)

Set an integer property associated with a sample. setting specifies which property, and may be one of:

ALLEGRO_AUDIO_POSITION - change the position where the sample is at in its sample buffer.
ALLEGRO_AUDIO_LENGTH - can not be set while sample is playing. Must be equal or less than the length of the buffer associated with the sample.

Return value:

Returns zero on success, non-zero on error.

See also: #al_sample_get_long.

al_sample_set_float

    int al_sample_set_float(ALLEGRO_SAMPLE *spl,
                            ALLEGRO_AUDIO_ENUM setting,
                            float val)

Set a floating point property associated with a sample. setting specifies which property, and may be one of:

ALLEGRO_AUDIO_SPEED - can not be set if attached directly to a voice

Return value:

Returns zero on success, non-zero on error.

See also: #al_sample_get_float.

al_sample_set_enum

    int al_sample_set_enum(ALLEGRO_SAMPLE *spl,
                           ALLEGRO_AUDIO_ENUM setting,
                           ALLEGRO_AUDIO_ENUM val)

Set an enumeration property associated with a sample. setting specifies which property, and may be one of:

ALLEGRO_AUDIO_LOOPMODE - can not be set if attached directly to a voice

Return value:

Returns zero on success, non-zero on error.

See also: #al_sample_get_enum.

al_sample_set_bool

    int al_sample_set_bool(ALLEGRO_SAMPLE *spl,
                           ALLEGRO_AUDIO_ENUM setting,
                           bool val)

Set a boolean property associated with a sample. setting specifies which property, and may be one of:

ALLEGRO_AUDIO_PLAYING - start playback if val is true, stop playback if val is false.
ALLEGRO_AUDIO_ATTACHED - val must be false, which has the effect of detaching the sample from whatever it is attached to
ALLEGRO_AUDIO_ORPHAN_BUFFER - if set to true, Allegro will consider this sample to hold the last reference to the sample data buffer associated with the sample. When the buffer pointer for the sample is changed, or the sample is destroyed, Allegro will call `free()' on the buffer. XXX: I'm not sure about this feature as free() might not be for the right heap. On the other hand something like it could be useful.

Return value:

Returns zero on success, non-zero on error.

See also: #al_sample_get_bool.

al_sample_set_ptr

    int al_sample_set_ptr(ALLEGRO_SAMPLE *spl,
                          ALLEGRO_AUDIO_ENUM setting,
                          void *val)

Set a pointer property associated with a sample. setting specifies which property, and may be one of:

ALLEGRO_AUDIO_BUFFER - can not be set while the sample is playing.

Return value:

Returns zero on success, non-zero on error.

See also: #al_sample_get_ptr.

Stream functions

al_stream_create

    ALLEGRO_STREAM *al_stream_create(size_t buffer_count,
                                     unsigned long samples,
                                     unsigned long freq,
                                     ALLEGRO_AUDIO_ENUM depth,
                                     ALLEGRO_AUDIO_ENUM chan_conf);

Create a stream object with the given properties. The stream will be set to play by default.

Return value:

Returns the stream on success, NULL or failure.

See also:

al_stream_destroy

    void al_stream_destroy(ALLEGRO_STREAM *stream);

Free the resources associated with a stream. The stream will be automatically detached from anything it is attached to, if any. Does nothing if stream is NULL.

See also:

al_stream_get_long

    int al_stream_get_long(const ALLEGRO_STREAM *stream,
                           ALLEGRO_AUDIO_ENUM setting,
                           unsigned long *val)

setting can be:

AL_AUDIO_FREQUENCY - the stream frequency.
AL_AUDIO_LENGTH - the length, in samples-per-channel, of an individual buffer fragment.
AL_AUDIO_FRAGMENTS - the total number of buffer fragments the object was created with.
AL_AUDIO_USED_FRAGMENTS - the number of buffer fragments that are waiting to be refilled. This value is decreased when ALLEGRO_AUDIO_BUFFER is used to retrieve a waiting buffer fragment.

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_stream_set_long, [#al_stream_get_ptr].

al_stream_get_float

    int al_stream_get_float(const ALLEGRO_STREAM *stream,
                            ALLEGRO_AUDIO_ENUM setting,
                            float *val)

setting can be:

AL_AUDIO_SPEED - the playback speed

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_stream_set_float.

al_stream_get_enum

    int al_stream_get_enum(const ALLEGRO_STREAM *stream,
                           ALLEGRO_AUDIO_ENUM setting,
                           ALLEGRO_AUDIO_ENUM *val)

setting can be:

AL_AUDIO_DEPTH -
AL_AUDIO_CHANNELS -

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_stream_set_enum.

al_stream_get_bool

    int al_stream_get_bool(const ALLEGRO_STREAM *stream,
                           ALLEGRO_AUDIO_ENUM setting,
                           bool *val)

setting can be:

AL_AUDIO_PLAYING -
AL_AUDIO_ATTACHED -

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_stream_set_bool.

al_stream_get_ptr

    int al_stream_get_ptr(const ALLEGRO_STREAM *stream,
                          ALLEGRO_AUDIO_ENUM setting,
                          void **val)

setting can be:

AL_AUDIO_BUFFER - get an individual buffer fragment to refill. After the fragment has been fill with data, it should be put back info the stream with al_stream_set_ptr.

Return value:

Returns zero on success. The value of the property will be stored in val.

See also: #al_stream_set_ptr.

XXX I don't like the al_stream_get_ptr/al_stream_set_ptr interface for filling buffers as it is rather different and more complex than a simple key/value pair

al_stream_set_long

    int al_stream_set_long(AL_STREAM *stream,
                            AL_AUDIO_ENUM setting,
                            unsigned long *val)

Currently streams have no integer properties that can be set.

Return value:

Returns zero on success, non-zero on error.

See also: #al_stream_get_long.

al_stream_set_float

    int al_stream_set_float(AL_STREAM *stream,
                            AL_AUDIO_ENUM setting,
                            float val)

setting can be:

AL_AUDIO_SPEED - can not be set if the stream is attached to a voice

Return value:

Returns zero on success, non-zero on error.

See also: #al_stream_get_float.

al_stream_set_enum

    int al_stream_set_enum(AL_STREAM *stream,
                            AL_AUDIO_ENUM setting,
                            AL_AUDIO_ENUM val)

Currently streams have no enumeration properties that can be set.

Return value:

Returns zero on success, non-zero on error.

See also: #al_stream_get_enum.

al_stream_set_bool

    int al_stream_set_bool(AL_STREAM *stream,
                            AL_AUDIO_ENUM setting,
                            bool val)

setting can be:

AL_AUDIO_PLAYING
ALLEGRO_AUDIO_ATTACHED - val must be false, which has the effect of detaching the mixer from whatever it is attached to.

Return value:

Returns zero on success, non-zero on error.

See also: #al_stream_set_bool.

al_stream_set_ptr

    int al_stream_set_ptr(AL_STREAM *stream,
                            AL_AUDIO_ENUM setting,
                            void *val)

setting can be:

AL_AUDIO_BUFFER - see al_stream_get_ptr.

Return value:

Returns zero on success, non-zero on error.

See also: #al_stream_set_bool.

Mixer functions

al_mixer_create

    ALLEGRO_MIXER *al_mixer_create(unsigned long freq,
                                   ALLEGRO_AUDIO_ENUM depth,
                                   ALLEGRO_AUDIO_ENUM chan_conf);

Create a mixer stream, to attach sample streams or other mixers to. It will mix into a buffer at the requested frequency and channel count. Only 24-bit signed integer mixing is currently supported.

Return value:

See also:

al_mixer_destroy

    void al_mixer_destroy(ALLEGRO_MIXER *mixer);

Destroy a mixer stream. Does nothing if mixer is NULL.

Return value:

See also:

al_mixer_attach_sample

    int al_mixer_attach_sample(ALLEGRO_MIXER *mixer,
                               ALLEGRO_SAMPLE *sample);

Attach a sample to a mixer. The sample must not be be already attached elsewhere.

XXX other limitations exist, what are they?

XXX what is the limit of attachments on a mixer?

Return value:

Returns zero on success, non-zero on error.

See also: #al_mixer_attach_stream, [#al_mixer_attach_mixer].

al_mixer_attach_stream

    int al_mixer_attach_stream(ALLEGRO_MIXER *mixer,
                               ALLEGRO_STREAM *stream);

Attach a stream to a mixer. The sample must not be be already attached elsewhere.

Return value:

Returns zero on success, non-zero on error.

See also: #al_mixer_attach_sample, [#al_mixer_attach_mixer].

al_mixer_attach_mixer

    int al_mixer_attach_mixer(ALLEGRO_MIXER *mixer,
                              ALLEGRO_MIXER *stream);

Attach a mixer onto another mixer. The same rules as with al_mixer_attach_sample apply, with the additional restriction that both mixers must be the same frequency.

Return value:

Returns zero on success, non-zero on error.

See also: #al_mixer_attach_sample, [#al_mixer_attach_stream].

al_mixer_set_postprocess_callback

    int al_mixer_set_postprocess_callback(ALLEGRO_MIXER *mixer,
            void (*cb) (void *buf, unsigned long samples, void *data),
            void *data);

Set a post-processing filter function to be called after the attached streams have been mixed. The buffer's format will be whatever the mixer was created with. The sample count and user-data pointer will be passed to the callback.

To remove the post-processing filter, pass NULL in place of the callback function.

Return value:

Returns zero on success, non-zero on error.

See also:

al_mixer_get_long

    int al_mixer_get_long(const ALLEGRO_MIXER *mixer,
                            ALLEGRO_AUDIO_ENUM setting,
                            unsigned long *val)

setting can be:

ALLEGRO_AUDIO_FREQUENCY

Return value:

See also: #al_mixer_set_long.

al_mixer_get_enum

    int al_mixer_get_enum(const ALLEGRO_MIXER *mixer,
                            ALLEGRO_AUDIO_ENUM setting,
                            ALLEGRO_AUDIO_ENUM *val)

setting can be:

ALLEGRO_AUDIO_CHANNELS
ALLEGRO_AUDIO_DEPTH
ALLEGRO_AUDIO_QUALITY

Return value:

See also: #al_mixer_set_enum.

al_mixer_get_bool

    int al_mixer_get_bool(const ALLEGRO_MIXER *mixer,
                            ALLEGRO_AUDIO_ENUM setting,
                            bool *val)

setting can be:

ALLEGRO_AUDIO_PLAYING

Return value:

See also: #al_mixer_set_bool.

al_mixer_set_long

    int al_mixer_set_long(ALLEGRO_MIXER *mixer,
                            ALLEGRO_AUDIO_ENUM setting,
                            unsigned long val)

ALLEGRO_AUDIO_FREQUENCY - can not be set if the mixer is attached

Return value:

Returns zero on success, non-zero on error.

See also: #al_mixer_get_long.

al_mixer_set_enum

    int al_mixer_set_enum(ALLEGRO_MIXER *mixer,
                            ALLEGRO_AUDIO_ENUM setting,
                            ALLEGRO_AUDIO_ENUM val)

ALLEGRO_AUDIO_QUALITY - can be ALLEGRO_AUDIO_POINT, ALLEGRO_AUDIO_LINEAR.

Return value:

Returns zero on success, non-zero on error.

See also: #al_mixer_get_enum.

al_mixer_set_bool

    int al_mixer_set_bool(ALLEGRO_MIXER *mixer,
                            ALLEGRO_AUDIO_ENUM setting,
                            bool val)

ALLEGRO_AUDIO_PLAYING
ALLEGRO_AUDIO_ATTACHED - val must be false, which has the effect of detaching the mixer from whatever it is attached to

Return value:

Returns zero on success, non-zero on error.

See also: #al_mixer_get_bool.

Voice functions

al_voice_create

    ALLEGRO_VOICE *al_voice_create(ALLEGRO_AUDIO_DRIVER *driver,
                                   unsigned long freq,
                                   ALLEGRO_AUDIO_ENUM depth,
                                   ALLEGRO_AUDIO_ENUM chan_conf,
                                   ALLEGRO_AUDIO_ENUM settings);

Create a voice object and allocates a voice from the digital sound driver. The depth and chan_conf arguments select the desired sample format and channel configuration of the voice. These may not be honoured unless the ALLEGRO_AUDIO_REQUIRE bit is set in settings. In that case the function will fail if the desired settings could not be satisfied.

XXX the use of ALLEGRO_AUDIO_REQUIRE in settings is pretty confusing for the channel configuration and the code is not any clearer

Return value:

Returns the voice object on success or NULL on failure.

al_voice_destroy

    void al_voice_destroy(ALLEGRO_VOICE *voice);

Destroys the voice and deallocates it from the digital driver. Does nothing if voice is NULL.

al_voice_attach_sample

    int al_voice_attach_sample(ALLEGRO_VOICE *voice,
                               ALLEGRO_SAMPLE *sample);

Attach a sample to a voice and allow it to play. The sample's volume and loop mode will be ignored. The sample must have the same frequency and depth (including signed-ness) as the voice. This function may fail if the selected driver doesn't support preloading sample data.

The voice must not already have an attachment. The sample must not already be attached.

Return value:

Returns zero on success, non-zero on failure.

See also: #al_voice_attach_stream, [#al_voice_attach_mixer].

al_voice_attach_stream

    int al_voice_attach_stream(ALLEGRO_VOICE *voice,
                               ALLEGRO_STREAM *stream);

Attach an audio stream to a voice. The same rules as al_voice_attach_sample apply. This may fail if the driver can't create a voice with the buffer count and buffer size the stream uses.

The voice must not already have an attachment. The stream must not already be attached.

Return value:

Returns zero on success, non-zero on failure.

See also: #al_voice_attach_sample, [#al_voice_attach_mixer].

al_voice_attach_mixer

    int al_voice_attach_mixer(ALLEGRO_VOICE *voice,
                              ALLEGRO_MIXER *mixer);

Attach a mixer to a voice. The same rules as al_voice_attach_sample apply, except that the depth of the voice and mixer do not need to match.

The voice must not already have an attachment. The mixer must not already be attached.

Return value:

Returns zero on success, non-zero on failure.

See also: #al_voice_attach_sample, [#al_voice_attach_stream].

al_voice_detach

    void al_voice_detach(ALLEGRO_VOICE *voice);

Detach a sample or mixer stream from the voice.

XXX why are there no detach functions for other types?

al_voice_get_long

    int al_voice_get_long(const ALLEGRO_VOICE *voice,
                          ALLEGRO_AUDIO_ENUM setting,
                          unsigned long *val)

setting can be:

ALLEGRO_AUDIO_FREQUENCY -
ALLEGRO_AUDIO_POSITION -

Return value:

See also: #al_voice_set_long.

al_voice_get_enum

    int al_voice_get_enum(const ALLEGRO_VOICE *voice,
                          ALLEGRO_AUDIO_ENUM setting,
                          ALLEGRO_AUDIO_ENUM *val)

setting can be:

ALLEGRO_AUDIO_CHANNELS
ALLEGRO_AUDIO_DEPTH
ALLEGRO_AUDIO_SETTINGS

Return value:

See also: #al_voice_set_enum.

al_voice_get_bool

    int al_voice_get_bool(const ALLEGRO_VOICE *voice,
                          ALLEGRO_AUDIO_ENUM setting,
                          bool *val)

setting can be:

ALLEGRO_AUDIO_PLAYING -

Return value:

See also: #al_voice_set_bool.

al_voice_set_long

    int al_voice_set_long(ALLEGRO_VOICE *voice,
                            ALLEGRO_AUDIO_ENUM setting,
                            unsigned long val)

setting can be:

ALLEGRO_AUDIO_POSITION -

Return value:

Returns zero on success, non-zero on error.

See also: #al_voice_get_long.

al_voice_set_enum

    int al_voice_set_enum(ALLEGRO_VOICE *voice,
                          ALLEGRO_AUDIO_ENUM setting,
                          ALLEGRO_AUDIO_ENUM val)

Currently voices have no enumeration properties which can be set.

Return value:

Returns zero on success, non-zero on error.

See also: #al_voice_get_enum.

al_voice_set_bool

    int al_voice_set_bool(ALLEGRO_VOICE *voice,
                          ALLEGRO_AUDIO_ENUM setting,
                          bool val)

setting can be:

ALLEGRO_AUDIO_PLAYING - setting to true or false will start and stop the playback

Return value:

Returns zero on success, non-zero on error.

See also: #al_voice_get_bool.

Miscellaneous

XXX incomplete

al_get_audio_driver

    ALLEGRO_AUDIO_DRIVER *al_get_audio_driver(const char *name);

Return value:

See also:

al_audio_init_driver

    ALLEGRO_AUDIO_DRIVER *al_audio_init_driver(
            ALLEGRO_AUDIO_DRIVER *driver);

Return value:

See also:

al_audio_deinit_driver

    void al_audio_deinit_driver(ALLEGRO_AUDIO_DRIVER *driver);

Return value:

See also:

Ideas

Make ALLEGRO_SAMPLE an event source which generates an event when the sample finishes playing (for ALLEGRO_AUDIO_PLAY_ONCE only).
Do we have easy fire-and-forget API? Maybe on top of this?
Priority system. Perhaps built on top of this one.

Retrieved from "http://wiki.allegro.cc/index.php?title=NewAPI/Sound"

Categories: Incomplete | New API

NewAPI/Sound

From Allegro Wiki

Contents

Overview

Audio API

Constants

Sample depth and type

Speaker configuration

Sample looping mode

Mixer quality

Audio object properties

Bit-field flags for voice settings

Types

ALLEGRO_SAMPLE

ALLEGRO_STREAM

ALLEGRO_MIXER

ALLEGRO_VOICE

ALLEGRO_AUDIO_DRIVER

Sample routines

al_sample_get_long

al_sample_get_float

al_sample_get_enum

al_sample_get_bool

al_sample_get_ptr

al_sample_play

al_sample_stop

al_sample_set_long

al_sample_set_float

al_sample_set_enum

al_sample_set_bool

al_sample_set_ptr

Stream functions

al_stream_create

al_stream_destroy

al_stream_get_long

al_stream_get_float

al_stream_get_enum

al_stream_get_bool

al_stream_get_ptr

al_stream_set_long

al_stream_set_float

al_stream_set_enum

al_stream_set_bool

al_stream_set_ptr

Mixer functions

al_mixer_create

al_mixer_destroy

al_mixer_attach_sample

al_mixer_attach_stream

al_mixer_attach_mixer

al_mixer_set_postprocess_callback

al_mixer_get_long

al_mixer_get_enum

al_mixer_get_bool

al_mixer_set_long

al_mixer_set_enum

al_mixer_set_bool

Voice functions

al_voice_create

al_voice_destroy

al_voice_attach_sample

al_voice_attach_stream

al_voice_attach_mixer

al_voice_detach

al_voice_get_long

al_voice_get_enum

al_voice_get_bool

al_voice_set_long

al_voice_set_enum

al_voice_set_bool

Miscellaneous

al_get_audio_driver

al_audio_init_driver

al_audio_deinit_driver

Ideas

Views

Personal tools

Navigation

Search

Toolbox