[Openal-devel] Another (last?) call for AL_EXT_loop_points

[Chris Robinson]

Haven't had any complaints about the latest update. Is there anything more 
that should be addressed, or can it be called "done"?

Name

    AL_EXT_loop_points

Contributors

    Chris Robinson
    Daniel Peacock

Contact

    Chris Robinson (chris.kcat 'at' gmail.com)

Status

    In progress

Dependencies

    This extension is written against the OpenAL 1.1 specification.

Overview

    This extension allows an application to specify the offsets at which a
    buffer loops. Unextended OpenAL only allows for a source to loop a whole
    buffer, or all buffers of a queue, which is not desirable for sounds that
    may want a lead-in or lead-out along with the looping portion.

Issues

    Q: How are are the loop points specified?
    A: Loop points are specified as a buffer attribute, using uncompressed
       sample offsets. The sample offsets are in relation to the sample rate
       provided to alBufferData, similar to the source's AL_SAMPLE_OFFSET
       attribute.

    Q: Why sample offsets and not compressed byte offsets?
    A: Sample offsets allow more precision when dealing with compressed
       formats, like IMA4 which can have multiple samples per byte.

    Q: Can the loop points be modified while the source is playing or paused?
    A: No. The buffer object is typically unmodifiable once it's attached to a
       source, and there is no apparent need to.

    Q: How does this interact with buffer queues?
    A: The loop points are ignored when the buffer is set on a source using
       alSourceQueueBuffers (ie. a source that is not an AL_STATIC type).

    Q: What should happen if the loop start offset is greater than or equal to
       the loop end offset?
    A: An AL_INVALID_VALUE error is generated. There is no reason for such
       offsets to be specified.

New Procedures and Functions

    None.

New Tokens

    Accepted by the <paramName> parameter of alBufferiv and alGetBufferiv:

        AL_LOOP_POINTS                           0x2015

Additions to Specification

    Append to Section 5.3.1, Buffer Attributes

    Table 5.x. Buffer AL_LOOP_POINTS Attribute

    Name              Signature  Values          Default
    ----------------  ---------  --------------  --------
    AL_LOOP_POINTS    iv         [0, MAX_INT]    {0, 0}

    Specifies the two offsets the playing source will use to loop, expressed
    in uncompressed samples. This only has an affect when the source it's
    attached to is of an AL_STATIC type and its AL_LOOPING attribute is set to
    AL_TRUE. The first value specifies the offset the source will loop to when
    it reaches the offset specified by the second value.

    If the source's current position within the buffer is not between the two
    offsets, it will not be moved. If the source then reaches the end of the
    buffer data, it will progress to an AL_STOPPED state.

    The offsets must be less than or equal to the number of samples in the
    buffer, and the second offset must be greater than the first offset, or an
    AL_INVALID_VALUE error is generated. An attempt to change the values while
    the buffer is attached or queued to a source will generate an
    AL_INVALID_OPERATION error.


    Modify Section 5.3.4, Specifying Buffer Content

    "... An invalid size will result in an AL_INVALID_VALUE error.

    When successfully filled with new data, the buffer's AL_LOOP_POINTS
    attribute will be set to 0 and the buffer's sample count, for the first
    and second offset respectively.

    Applications should always check for an error condition..."

Errors

    An AL_INVALID_VALUE error is generated if alBufferiv is called with a
    negative offset value for AL_LOOP_POINTS.

    An AL_INVALID_VALUE error is generated if alBufferiv is called with offset
    values for AL_LOOP_POINTS where the second value is not greater than the
    first value.

    An AL_INVALID_VALUE error is generated if alBufferiv is called with an
    offset value for AL_LOOP_POINTS that is greater than the buffer's sample
    count.

    An AL_INVALID_OPERATION error is generated if an attempt is made to modify
    the AL_LOOP_POINTS attribute while the buffer is attached or queued to a
    source.