The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

NewAPI/Sound/Proposed

From Allegro Wiki
Jump to: navigation, search

Proposed Sound API

The following is a proposal to simplify the audio API without resorting to an explicit "simple layer." The basic API should be simple by default. More complex usage should require the extra work.

This is not meant to be an exhaustive design. Anything not covered is assumed to be the same as the current API with the appropriate name changes.

Setup

ALLEGRO_AUDIO_DRIVER_AUTODETECT
ALLEGRO_AUDIO_DRIVER_OPENAL    
ALLEGRO_AUDIO_DRIVER_ALSA      
ALLEGRO_AUDIO_DRIVER_DSOUND    
ALLEGRO_AUDIO_DRIVER_OSS 

al_install_audio

int al_install_audio(ALLEGRO_AUDIO_DRIVER_ENUM mode);

Installs the audio driver.

al_uninstall_audio

void al_uninstall_audio(void)

Shuts down the audio driver and the default mixer (if created). Stops all samples that are playing in the reserved slots.

al_set_default_mixer

bool al_set_default_mixer(ALLEGRO_MIXER *mixer)

Sets the default mixer for playing audio samples via al_play_sample(). It must be attached to a voice for it to work. It should be called prior to al_reserve_samples() if you are using your own mixer. All samples currently playing via al_play_sample() will be stopped.

al_get_default_mixer

ALLEGRO_MIXER* al_get_default_mixer(void)

Returns the default mixer, or NULL if there is none.

al_restore_default_mixer

bool al_restore_default_mixer(void)

Restores the default mixer to Allegro's internal one. Returns true on success, false on error.

al_reserve_samples

bool al_reserve_samples(int reserve_samples)

Adjusts the number of reserved sample slots. If no default mixer is set, then it will be created. If reserve_samples is shrunk from a previous allocation, then some reserved samples may automatically be stopped.

Voices

Same as current API.

Mixers

Same as current API.

Samples

In short: rename the current ALLEGRO_SAMPLE_DATA to ALLEGRO_SAMPLE.

ALLEGRO_SAMPLE_ID

struct ALLEGRO_SAMPLE_ID 
{
   int _slot_index;
   int _id;
};

Represents a sample that has been played via one of the reserved slots. The internals are considered private. _slot_index contains the slot index of the internal 'simp_samples' vector. _id is used to prevent accidentally stopping the wrong sample in the event that the slot index now points to a new sample.

ALLEGRO_PLAYMODE

enum ALLEGRO_PLAYMODE
{
  ALLEGRO_PLAYMODE_ONCE   = 0x100,
  ALLEGRO_PLAYMODE_LOOP   = 0x101,
  ALLEGRO_PLAYMODE_BIDIR  = 0x102
};

al_load_sample

ALLEGRO_SAMPLE *al_load_sample(const char* filename)

Loads the sample from the filename. WAV support out of the box. Other formats can been registered via addons.

al_save_sample

bool al_save_sample(ALLEGRO_SAMPLE *spl, const char* filename)

Saves the sample to the file if a registered handle for the filename extension exists.

Returns true on success, false on error.

al_save_sample_wav

bool al_save_sample_wav(ALLEGRO_SAMPLE *spl, const char* filename)

Saves the sample to the file using the wav format. If the sample has a depth of 24-bit or 32-bit, it is saved as 16-bit. Otherwise, it is saved its native depth.

Returns true on success, false on error.

al_save_sample_wav_pf

bool al_save_sample_wav_pf(ALLEGRO_SAMPLE *spl, ALLEGRO_FS_ENTRY *pf)

Saves the sample to the packfile (whatever it's called now) using the wav format. See <<al_save_sample_wav>> for details.

Returns true on success, false on error.

al_play_sample

bool al_play_sample(ALLEGRO_SAMPLE *sample, float gain, float pan, float speed, ALLEGRO_PLAYMODE playmode, ALLEGRO_SAMPLE_ID &ret_id);

Plays the sample via the default mixer using one of the reserved slots. The ret_id can be used to stop the sample.

Returns true on success, false on error.

al_stop_sample

bool al_stop_sample(ALLEGRO_SAMPLE_ID sample_id)

Stops the single instance (as specified by the sample id) of the sample.

al_stop_samples

void al_stop_samples(void)

Stops all samples started with al_play_sample().

SAMPLE_INSTANCE

In short: rename the current ALLEGRO_SAMPLE to ALLEGRO_SAMPLE_INSTANCE.

Some API changes:

  • al_play_sample() => al_play_sample_instance()
  • al_stop_sample() => al_stop_sample_instance()
  • al_get_sample_XXX() => al_get_sample_instance_XXX()
  • al_set_sample_XXX() => al_set_sample_instance_XXX()

There would be very little use for these functions to be called directly by the user. They might be useful for setting advanced properties such as 3D "panning" for 5.1 configurations.

Examples

Average Joe

<highlightSyntax> al_install_audio(ALLEGRO_AUDIO_DRIVER_AUTODETECT); al_reserve_samples(32);

ALLEGRO_SAMPLE *zap = al_load_sample("zap.wav"); ALLEGRO_SAMPLE *theme = al_load_sample("theme.wav"); ALLEGRO_SAMPLE_ID theme_id; al_play_sample(theme, 1.0, 0.5, 1.0, ALLEGRO_PLAYMODE_LOOP, &theme_id);

while (playing) {

 if (shooting) al_play_sample(zap, 1.0, player_x / screen_w, 1.0, ALLEGRO_PLAYMODE_ONCE, NULL);

}

al_stop_sample(&theme_id); // not explicitly required

al_uninstall_audio(); // or automatically called via Allegro </highlightSyntax>

Advanced Joe

<highlightSyntax> al_install_audio(ALLEGRO_AUDIO_DRIVER_AUTODETECT);

ALLEGRO_VOICE *voice = al_create_voice(44100, ALLEGRO_AUDIO_DEPTH_UINT16, ALLEGRO_CHANNEL_CONF_5_1); ALLEGRO_MIXER *mixer = al_create_mixer(44100, ALLEGRO_AUDIO_DEPTH_FLOAT32, ALLEGRO_CHANNEL_CONF_5_1); al_attach_mixer_to_voice(voice, mixer);

// replace the default mixer with ours al_set_default_mixer(mixer); al_reserve_samples(32);

// load some fancy audio file ALLEGRO_SAMPLE *theme = al_load_sample("theme.3d"); ALLEGRO_SAMPLE_INSTACE *theme_instance = al_create_sample_instance(theme); al_attach_sample_to_mixer(voice, theme_instance); al_set_sample_instance_int(theme_instance, FOO, 1); al_start_sample_instance(theme_instance);

// basic samples can still be played via the default mixer ALLEGRO_SAMPLE *zap = al_load_sample("zap.wav");

while (playing) {

 if (shooting) al_play_sample(zap, 1.0, player_x / screen_w, 1.0, ALLEGRO_PLAYMODE_ONCE, NULL);

}

al_stop_sample_instance(theme_instance);

al_uninstall_audio(); // or automatically called via Allegro </highlightSyntax>