[Openal-devel] Extension proposal
chris.kcat at gmail.com
Tue Sep 16 05:34:42 PDT 2008
Here's a proposal for a new distance model. I came up with it while trying to
modify an advanced Doom port to use OpenAL. An issue I ran into was that the
game uses a lookup table to provide attenuation values, and attempts to
replicate it using existing models has been somewhat fruitless. It would also
run into further issues for any mods that may have provided its own table.
I realize this is largely to "emulate" custom sound systems used by old
programs. However, with them being/becoming open source, updating them to use
newer and more robust APIs (such as OpenAL) is a typical goal. Being able to
provide what they need without having to resort to hacks would make it more
enticing to prospective developers.
The only other option would be to provide a callback, or similar method.. but
that's not really OpenAL's style. I could imagine some sort of "parameter
program" extension doing this better, but the needed ground work just isn't
there yet. And it's definitely not something I could come up with in a
reasonable time frame.
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.
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. Though per source rolloffs could have
some use, this wouldn't be the appropriate place to add it.
New Procedures and Functions
void alAttenuationTableEXT(Aenum target, ALsizei size, ALfloat *table);
Accepted by the <modelName> parameter of alDistanceModel, the <paramName>
parameter of alGetFloatv, and the <target> parameter of
Accepted by the <paramName> parameter of alGetInteger and alGetIntegerv:
Additions to Specification
void alAttenuationTableEXT(Aenum target, ALsizei size,
can be used to specify an attenuation table for the current context.
<target> must be AL_ATTENUATION_TABLE_EXT. 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
The value AL_ATTENUATION_TABLE_EXT may be passed to alDistanceModel to
enable attenuation according to the attenuation table. 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) /
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 while no table
is specified results in an AL_INVALID_OPERATION error.
To retrieve the current attenuation table, first query its size by calling
alGetInteger or alGetIntegerv using AL_ATTENUATION_TABLE_SIZE_EXT:
ALint tableSize = alGetInteger(AL_ATTENUATION_TABLE_SIZE_EXT);
/* or */
The returned value is the number of ALfloat values in the current table,
and the number of entries required for the storage array. Retrieve the
table using alGetFloatv:
ALfloat *table = malloc(tableSize * sizeof(ALfloat));
Attempting to retrieve a table after it's deleted or before it's set is a
The error AL_INVALID_OPERATION is generated if alAttenuationTableEXT is
called with a value of 0 passed to <size>, while the target is in use.
The error AL_INVALID_OPERATION is generated if alDistanceModel is called
with AL_ATTENUATION_TABLE_EXT, while no attenuation table is set.
More information about the Openal-devel