[Openal-devel] Another extension..

[Chris Robinson]

Here's another extension I came up with recently to help ease issues I've been 
having with a certain project using OpenAL. I'll understand if people don't 
think it's a good idea as a general extension, but unless there are 
alternative methods to updating random sections of a pre-defined playing 
buffer that I'm missing, I would like at least OpenAL Soft to have it..

BTW, any news on my last two proposals?


Name

    EXT_buffer_sub_data

Name Strings

    AL_EXT_buffer_sub_data

Version

    1.0

Number

    ??

Overview

    This extension allows an application to modify a section of buffered
    sample data while the buffer is in use.

Issues

    Q: What is the purpose of this extension? Buffer queues are already
       provided to handle real-time streaming.
    A: It is true that streaming is handled (arguably) more effectively with
       buffer queues. However, this method is a departure from methods of
       other prominant sound APIs, and in places where OpenAL is used as one
       of several output backend for a higher-level API, the flexibility
       provided by this method can make such integration easier.

    Q: The new function takes offset and length parameters in sample frames.
       How is this handled with implementations which resample/convert sample
       data when loaded?
    A: The sample frames are assumed to be relative to the frequency passed to
       alBufferData. For example, if an app calls alBufferData with a
       frequency of 44100, an offset of 22050 is a half-second from the
       beginning. It's the implementation's responsibility to cleanly resample
       and fit the data into the resampled buffer.

    Q: How does this extension interact with X-RAM?
    A: TDB. Ideally, it should behave the same irrespective of whether a
       buffer is placed in system memory or in the audio device's memory.
       However, if updating a buffer in the audio device's memory in real-time
       is not very feasible, it may need to be allowed to fail there.

New Procedures and Functions

    void alBufferSubDataEXT(ALuint buffer, ALenum format, const ALvoid *data,
                            ALsizei offset, ALsizei length);

New Tokens

    None.

Additions to Specification

    To update a section of buffered sample data, call the function

      void alBufferSubDataEXT(ALuint buffer, ALenum format,
                              const ALvoid *data, ALsizei offset,
                              ALsizei length);

    The named <buffer> is the buffer ID which had previously been used with a
    call to alBufferData. Calling alBufferSubDataEXT with a <buffer> which has
    not been used with alBufferData results in an AL_INVALID_NAME error.
    <buffer> may be attached to a source (either queued or with the source's
    AL_BUFFER property), and the source does not need to be stopped, paused,
    or in an initial state to be modified.

    The <offset> value is the number of sample frames from the start of the
    original data, and <length> is the number of sample frames to modify. If
    either <offset> or <length> is negative, or if the sum of <offset> and
    <length> reaches beyond the end of the buffer, an AL_INVALID_VALUE error
    is generated.

    The specified <format> is the sample format of the passed <data>. The
    passed format does not need to have the same bit-depth (the implementation
    will be expected to convert), but the channel configuration must be the
    same as the format used with alBufferData, or AL_INVALID_ENUM results.

Errors

    The error AL_INVALID_ENUM is generated if the channel configuration of
    <format> does not match the channel configuration of the format previously
    passed to alBufferData.

    The error AL_INVALID_NAME is generated if <buffer> was not previously used
    with alBufferData.

    The error AL_INVALID_VALUE is generated if <offset> or <length> is
    negative, or they specify a segment that is beyond the range of the
    buffer.