[Openal-devel] Another extension..

[Chris Robinson]

Added the new AL_*_RW_OFFSETS_EXT tokens, and rewrote the issue dealing with 
X-RAM/hardware buffers. In particular, I'd like to make sure the new tokens 
don't clash with existing ones (I tried to use the next available source 
property values, though it's difficult to say if the values are duplicates 
since the existing enums in the headers aren't ordered). Any other issues?

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 extension 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 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.

    Q: Should there be a method to retrieve the source's "write cursor"?
    A: Yes. When updating buffers that play on a hardware voice, it would be
       desireable to make sure the section currently being read by the
       hardware isn't modified. The section being read is given by the new
       AL_*_RW_OFFSETS_EXT read-only source properties.

    Q: How does this extension interact with hardware storage/streaming?
    A: Updating a buffer is allowed regardless of where it is stored. However,
       applications should take care to not modify the data between the
       reported read/write offsets, or else an asyncronous update may try to
       read from data that's being modified.

New Procedures and Functions

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

New Tokens

    Accepted by the <paramName> parameter of alGetSourceiv and alGetSourcefv:

        AL_BYTE_RW_OFFSETS_EXT                   0x1031
        AL_SAMPLE_RW_OFFSETS_EXT                 0x1032
        AL_SEC_RW_OFFSETS_EXT                    0x1033

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 defined with a call to
    alBufferData. Calling alBufferSubDataEXT with a <buffer> which was not
    previously defined 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
    defined with a compressed format, the specified <format> must precisely
    match, or an AL_INVALID_ENUM error is generated.


    When modifying a playing source's buffer, an application must take care to
    not modify the section that is currently being played. The read-only
    source attributes

      AL_BYTE_RW_OFFSETS_EXT
      AL_SAMPLE_RW_OFFSETS_EXT
      AL_SEC_RW_OFFSETS_EXT

    may be specified as the <paramName> parameter to alGetSourceiv and
    alGetSourcefv to retrieve two offset values. The first is the read offset,
    which is identical to the value given by AL_BYTE_OFFSET, AL_SAMPLE_OFFSET,
    and AL_SEC_OFFSET, respectively. The second value is the offset an
    application may safely write to, expressed in compressed bytes,
    uncompressed sample frames, and seconds, respectively.

    If the source is not in an AL_PLAYING state, the read and write offsets
    will be the identical. Behavior is undefined if an attempt is made to
    modify buffer data between the read and write offsets.

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.