[Openal-devel] Extension proposal updated
Daniel PEACOCK
dpeacock at creativelabs.com
Fri Sep 19 08:11:45 PDT 2008
Hi Chris,
I don't really like the fact that each Attenuation Table needs a new enum
value, or that there should be any limit on the number you can create,
apart from memory.
So how about ...
We treat an Attenuation Table as an object ...
alGenAttenuationTables(ALsizei n, ALuint *tables);
alDeleteAttenuationTables(ALsizei n, ALuint *tables);
alIsAttenuationTable(ALuint table);
The IDs returned will be assigned by the implementation, which will be
responsible for using values that do not collide with the standard defined
enum values for the distance models (AL_NONE, AL_INVERSE_DISTANCE_CLAMPED,
etc ...)
To add entries to a table ...
void alAttenuationTable(ALuint atid, ALsizei size, ALfloat *table);
(and possibly ... )
void alGetAttenuationTable(ALuint atid, ALsizei size, ALfloat *table);
where size is the number of floats pointed to by table
To use a particular attenuation table on a Source ...
alSourcei(sourceID, AL_DISTANCE_MODEL, atid);
Or set one for the whole context ...
alDistanceModel(atid);
In this formula ...
entry = AL_ROLLOFF_FACTOR * (distance–AL_REFERENCE_DISTANCE) /
(AL_MAX_DISTANCE–AL_REFERENCE_DISTANCE) *
(AL_ATTENUATION_TABLE_SIZE_EXT-1);
entry will need to be clamped in range here (AL_ROLLOFF_FACTOR can be > 1)
gain = AttenuationTable[entry]
ISSUES ... ALuint, ALint and ALenum are being used inter-changeably (sp?).
Is that OK? Are they always the same size (32bit) on all platforms?
Dan
Creative Labs (UK) Ltd.
Notice
The information in this message is confidential and may be legally
privileged. It is intended solely for the addressee. Access to this
message by anyone else is unauthorized. If you are not the intended
recipient, any disclosure, copying or distribution of the message, or
any action taken by you in reliance on it, is prohibited and may be
unlawful. If you have received this message in error, please delete it
and contact the sender immediately. Thank you.
Chris Robinson
<chris.kcat at gmail
.com> To
Sent by: openal-devel at opensource.creative.co
openal-devel-boun m
ces at opensource.cr cc
eative.com
Subject
[Openal-devel] Extension proposal
09/19/2008 02:21 updated
PM
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.
_______________________________________________
Openal-devel mailing list
Openal-devel at opensource.creative.com
http://opensource.creative.com/mailman/listinfo/openal-devel
ForwardSourceID:NT0006516E
More information about the Openal-devel
mailing list