Re: [AD] A5 Audio API issues

[Peter Wang <novalazy@xxxxxxxxxx>]

On 2009-12-30, Paul Suntsov <siegelords_abode@xxxxxxxxxx> wrote:
> Couple of issues I think we should fix in the audio API:
> 
> 1. API nomenclature:
> 
> a. Rename all things like al_load_sample_* to al_load_* to match the
> image addon nomenclature. I.e. al_load_wav, al_load_ogg_vorbis etc
> 
> b. Rename the stream loading functions to al_load_*_audio_stream to
> match the above fixes.

Makes sense.

> 2. Provide file stream loading/saving functions
> 
> Right now all we have al_save_sample_wav_pf. We should have all the
> other ones though, again to mimic the image addon.
>
> So, we'll have to add:
> al_load_{formats}_stream
> al_load_{formats}_audio_stream_stream <-- awkward, but that's how it is
> al_save_wav_stream

Ugh.  _pf would at least have been unambiguous.

> 3. Remove ALLEGRO_SAMPLE_ID, it's useless as is. Make al_play_sample
> return ALLEGRO_SAMPLE_INSTANCE* which ALLEGRO_SAMPLE_ID is a wrapper
> around anyway.

SAMPLE_ID basically solves a single problem, that the underlying
reserved SAMPLE_INSTANCE may be reused after the current sample is
finished.  The user should be able to reliably stop a sample he started,
even if the sample instance is reused for something else.

I agree with the intention to remove SAMPLE_ID though.  It seems
feasible.

> This will allow the user to fiddle with the instance as
> much as he pleases and thus make the easy audio API just as functional
> as the 'hard' audio API. Remove al_stop_sample since it will now do
> nothing.
> 
> These are all simple suggestions that one can implement pretty easily,
> I think. Any comments on these? Also, about the API nomenclature, we
> should go through the API sometime soon and make sure it at least
> follows the proper al_verb_adjective_noun form.

I tried to do that for 4.9.14 but there might be some remaining.
There were a couple of changes which I considered but didn't make
in the end, and no one seemed to notice.

e.g. neither of these seem really better to me:
    al_key_down -> al_is_key_down
    al_event_queue_is_empty -> al_is_event_queue_empty

Peter