[Openal-devel] Extension proposal updated

[Chris Robinson]

Here's an updated extension proposal for attenuation tables. It adds the 
ability to define multiple tables, and clarifies the interaction with 
AL_EXT_source_distance_model (for handling per-source tables).

I didn't put in a method to define the type of "blending" used by the table. 
IMO, a seperate AL_EXT_hint extension should be added so other extensions 
that want the same functionality don't have to re-define it, or be forced to 
implement this extension. Such an extension could be written so that it 
interacts with this extension (ie. providing the "blend" quality for the 
given attenuation table target), without requiring it to be present.

I also removed the EXT and _EXT suffixes from the functions and tokens, 
respectively. Though OpenGL extensions would use them, most AL extensions 
don't (and honestly they do look kind of long and ugly).

Also, how should I go about implementing these extensions for OpenAL Soft? Do 
I need to wait for some kind of "extension approved" message from Creative, 
or should I just go ahead and add it when all the issues are ironed out (and 
put a copy on the OpenAL site's extension page)?

Thanks for any responses. :)


Name

    EXT_attenuation_table

Name Strings

    AL_EXT_attenuation_table

Version

    1.0

Number

    ??

Overview

    This extension provides support for custom rolloffs. It allows
    applications to provide an array of gains which would be used in place of
    normal attenuation algorithms. This could be useful, for example, for
    rolloffs that existing distance models can't emulate or that would be too
    processor intensive for a target system.

Issues

    Q: Should the table be per source or per context?
    A: Per context. Being per source could add a measurable memory footprint
       if the application uses a lot of sources and/or large tables. Most uses
       would likely have all sources using the same table, which would create
       a needless amount of memory use.

       Additionally, the proposed AL_EXT_source_distance_model extension can
       trivially handle assigning specific tables to specific sources if both
       extensions are supported by the implementation.

    Q: How does this extension interact with the proposed
       AL_EXT_source_distance_model extension?
    A: In no special way. The wording of the two extensions should be
       sufficiently clear on how it works when both are supported. Basically,
       an application would specify the table(s) it wanted, and then set a
       source to use a particular table:

           alAttenuationTable(AL_ATTENUATION_TABLE+i, tableSize, tableValues);
           alSourcei(sourceID, AL_DISTANCE_MODEL, AL_ATTENUATION_TABLE+i);

       Any table that could be set with alDistanceModel could be set with the
       source's AL_DISTANCE_MODEL property.

    Q: Should a method be provided to enable "blending" between table values
       as the source-listener distance changes?
    A: Yes, but not here. Providing a linear (or better) filter as the
       distance causes a move between entries is a requested feature, however
       it would be best-served through a more generic alHint-like system.
       Instead of burdening implementations with having to implement
       attenuation tables for hint-like functionality, or causing confusion
       between extensions that both add hint-like functionality, it would
       probably be best to make a seperate extension for it, that interacts
       with this one.

New Procedures and Functions

    void alAttenuationTable(Aenum target, ALsizei size, ALfloat *table);

New Tokens

    Accepted by the <modelName> parameter of alDistanceModel, the <paramName>
    parameter of alGetFloatv, and the <target> parameter of
    alAttenuationTable:

        AL_ATTENUATION_TABLE                      0xD010
        AL_ATTENUATION_TABLE0                     0xD010 (alias of
                                                  AL_ATTENUATION_TABLE)
        AL_ATTENUATION_TABLE1                     0xD011
        AL_ATTENUATION_TABLE2                     0xD012
        AL_ATTENUATION_TABLE3                     0xD013
        AL_ATTENUATION_TABLE4                     0xD014
        AL_ATTENUATION_TABLE5                     0xD015
        AL_ATTENUATION_TABLE6                     0xD016
        AL_ATTENUATION_TABLE7                     0xD017

    Accepted by the <paramName> parameter of alGetInteger and alGetIntegerv:

        AL_MAX_ATTENUATION_TABLES                 0xC004

        AL_ATTENUATION_TABLE_SIZE                 0xC010
        AL_ATTENUATION_TABLE0_SIZE                0xC010 (alias of
                                                  AL_ATTENUATION_TABLE_SIZE)
        AL_ATTENUATION_TABLE1_SIZE                0xC011
        AL_ATTENUATION_TABLE2_SIZE                0xC012
        AL_ATTENUATION_TABLE3_SIZE                0xC013
        AL_ATTENUATION_TABLE4_SIZE                0xC014
        AL_ATTENUATION_TABLE5_SIZE                0xC015
        AL_ATTENUATION_TABLE6_SIZE                0xC016
        AL_ATTENUATION_TABLE7_SIZE                0xC017

Additions to Specification

    To retrieve the maximum number of supported attenuation tables, call
    alGetInteger or alGetIntegerv with AL_MAX_ATTENUATION_TABLES. The number
    of supported attenuation tables is gauranteed to be at least one.

        ALint maxTables = alGetInteger(AL_MAX_ATTENUATION_TABLES);
        /* or */
        ALint maxTables;
        alGetIntegerv(AL_MAX_ATTENUATION_TABLES, &maxTables);

    The names AL_ATTENUATION_TABLE through AL_ATTENUATION_TABLE+maxTables-1
    will be valid attenuation table targets. The values
    AL_ATTENUATION_TABLE_SIZE through AL_ATTENUATION_TABLE_SIZE+maxTables-1
    will be valid queries for the corresponding table's size. The numbered
    defines for the first 8 of each are provided for convenience.


    To specify an attenuation table, use the function

        void alAttenuationTable(ALenum target, ALsizei size, ALfloat *table);

    <target> must be a valid attenuation table target, or an AL_INVALID_NAME
    error will result. An array of <size> ALfloats is passed through the
    <table> parameter, which can then be used as a lookup table by the
    Attenuation Table distance model. The value of <table> is ignored if
    <size> is 0.

    After specifying an attenuation table, any previous table for the target
    is discarded. Passing 0 for <size> effectively deletes the attenuation
    table. The error AL_INVALID_OPERATION is generated if an attempt is made
    to delete an attenuation table while it's in use. Changing the table while
    it's in use is not an error, and the change will take effect at the next
    update.


    The value AL_ATTENUATION_TABLE, or any other valid attenuation table, may
    be passed as a valid modelName to alDistanceModel, to enable attenuation
    using the given table according to the Attenuation Table model. Under this
    model, the calculated distance is clamped as if AL_LINEAR_DISTANCE_CLAMPED
    was used. The gain is then computed by:

        entry = AL_ROLLOFF_FACTOR * (distance–AL_REFERENCE_DISTANCE) /
                (AL_MAX_DISTANCE–AL_REFERENCE_DISTANCE) *
                (AL_ATTENUATION_TABLE_SIZE_EXT-1)
        gain = AttenuationTable[entry]

    If AL_MAX_DISTANCE is the same as AL_REFERENCE_DISTANCE, which would
    normally cause a divide-by-0, the first entry of the table is used.
    Attempting to enable the Attenuation Table distance model with a table
    that's not allocated results in an AL_INVALID_OPERATION error.


    To retrieve an attenuation table, first query its size by calling
    alGetInteger or alGetIntegerv using a valid attenuation table size query
    value:

        ALint tableSize = alGetInteger(AL_ATTENUATION_TABLE_SIZE+i);
        /* or */
        ALint tableSize;
        alGetIntegerv(AL_ATTENUATION_TABLE_SIZE+i, &tableSize);

    The returned value is the number of ALfloat values in the corresponding
    table, and the number of entries required for the storage array. Retrieve
    the table using alGetFloatv:

        ALfloat *table = malloc(tableSize * sizeof(ALfloat));
        alGetFloatv(AL_ATTENUATION_TABLE+i, table);

    Attempting to retrieve a table after it's deleted or before it's allocated
    is a valid no-op.

Errors

    The error AL_INVALID_OPERATION is generated if alAttenuationTable is
    called with a value of 0 passed to <size>, while the target is in use.

    The error AL_INVALID_NAME is generated if alAttenuationTable is called
    with an invalid attenuation table target.

    The error AL_INVALID_OPERATION is generated if alDistanceModel is called
    with an attenuation table target, while no attenuation table is set for
    that target.