[Openal-devel] AL_EXT_source_distance_model

[Chris Robinson]

Here's an updated spec for the AL_EXT_source_distance_model extension, which 
addresses Dan's question.

Name

    EXT_source_distance_model

Name Strings

    AL_EXT_source_distance_model

Version

    1.0

Number

    ??

Dependancies

    This extension is written against the OpenAL 1.1 specification.

Overview

    This extension allows each source to specify a distance model, instead of
    being restricted to one distance model for every source in the context. It
    provides a mechanism for applications to apply different models to each
    source, without the burden of manually applying the attenuation through
    the the source gain.

Issues

    Q: What should this extension be called?
    A: EXT_source_distance_model is a bit clunky, but it does portray the
       intended functionality; allowing the distance model to be specfied for
       the source, instead of the context.

    Q: ALint and ALenum are being used inter-changeably. Is that OK? Are they
       always the same size (32 bits) on all platforms?
    A: Yes, and yes except on Win64, where int types are 64 bits. Both ALint
       and ALenum are typedef'd to int, and OpenAL already passes ALenum
       values through an ALint (such as when calling alGetInteger with
       AL_DISTANCE_MODEL), so there should be no problems passing a distance
       model enum through al[Get]Sourcei.

New Procedures and Functions

    None.

New Tokens

    None.

Additions to Specification

    Modify Table 3.1 (Numerical Query Definitions), p. 22

    Name                      Description
    -----------------         -----------------
    ...
    AL_DISTANCE_MODEL         The current default distance model


    Modify Section 3.4 (Attenuation By Distance), p. 24

    (modify starting from third paragraph)
    OpenAL currently supports three modes of operation with respect to
    distance attenuation, including one that is similar to the IASIG I3DL2
    model. The application can choose one of these models (or chooses to
    disable distance-dependent attenuation) on a per-source basis. The
    function

    void alDistanceModel(ALenum modelName);

    changes the distance model used by all sources in the current context, as
    well as specifies the default model new sources will be set to. Legal
    arguments are: ...


    Modify Section 4.3.2 (Source Attributes)

    (add to subsection Distance Model Attributes, p. 38)
    Table 4.x: DISTANCE_MODEL Attribute
    Name                Signature   Values      Default
    -----------------   ---------   ---------   ---------------------------
    AL_DISTANCE_MODEL   i, iv       any valid   AL_INVERSE_DISTANCE_CLAMPED
                                    modelName

    Description: the distance model used when calculating the source's
    distance-dependent attenuation. By default, new sources will be set to
    AL_INVERSE_DISTANCE_CLAMPED. Calling alDistanceModel, however, will modify
    the default value new sources are set to, as well as modify the current
    value of existing sources.


Errors

    None.