[Openal-devel] Another extension..

[Chris Robinson]

An updated version of the spec. If there's no objections, I'll commit it to 
OpenAL Soft as AL_EXTX_buffer_sub_data, making sure to note the temporary and 
volatile nature of it. I'll still be able to change it if more issues are 
brought up or rethought, until it's accepted.

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: While streaming is arguably handled more effectively with buffer
       queues, this method is a departure from of other prominant sound APIs.
       In places where OpenAL is used as one of several output backends for a
       higher-level API, or used to provide the functionality of other sound
       APIs, 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.

    Q: No method is provided to retrieve the source's "write cursor". Should
       there be one?
    A: This is likely not necessary. Like other AL functions, async updates
       are blocked until the call completes. It is the responsibility of the
       implementation to make sure an update doesn't occur while a buffer is
       being modified.

    Q: How are compressed formats handled?
    A: When modifying compressed data, the sample offset and length specified
       must be block aligned (eg. for IMA4, they must be multiples of 65). In
       addition, the format must be the same format the buffer was created
       with. Complex compressed formats, like Vorbis or MP3, may not be
       modified this way.

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, use the function

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

    The named <buffer> is one which was previously created with a call to
    alBufferData. Calling alBufferSubDataEXT with a <buffer> which was not
    previously created results in an AL_INVALID_NAME error. <buffer> may be
    attached to a source (either queued or by the 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. For compressed formats, <length> and <offset> must be
    appropriately block aligned. Complex compressed formats (those with no
    constant compressed and uncompressed block lengths) may not be modified,
    and will result in an AL_INVALID_ENUM error.

    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 match the
    format used with alBufferData, or AL_INVALID_ENUM results. If <buffer> was
    created with a compressed format, the specified <format> must precisely
    match, or an AL_INVALID_ENUM error is generated.

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_ENUM is generated if <buffer> was created with a
    compressed format and <format> does not precisely match.

    The error AL_INVALID_ENUM is generated if <buffer> was created with a
    complex compressed format.

    The error AL_INVALID_NAME is generated if <buffer> was not previously
    created 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.