id-software/DOOM-3
1
0
Fork 0
mirror of https://github.com/id-Software/DOOM-3.git synced 2026-03-20 08:59:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

hello world

Browse Source
This commit is contained in:
Timothee 'TTimo' Besset
2011-11-22 15:28:15 -06:00
commit fb1609f554
2155 changed files with 1017022 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
neo/openal/docs/ChangeLog Normal file
View File

@@ -0,0 +1,378 @@
2001-02-06 Bernd Kreimeier <bk@lokigames.com>
* chp-rendering.sgml: added annotation about CONE calculation.
* chp-state.sgml: added more annotation on log vs. linear GAIN.
2001-01-09 Bernd Kreimeier <bk@lokigames.com>
* chp-state.sgml: ungrep of scratched DISTANCE_SCALE.
2001-01-08 Bernd Kreimeier <bk@lokigames.com>
* chp-rendering.sgml: amended MAX_DISTANCE.
* chp-state.sgml: culling clarification.
Note: MAX_DISTANCE (and consequently the current
Inverse Clamped Distance Model) do not fit the API.
The clamping of the distance (instead of clamping
to the effective gain at the max. distance) will
potentially break other distance-dependend calculations
further down in the processing chain.
TODO: revisit Inverse Clamped Distance Model. _DS3D extension?
2001-01-05 Bernd Kreimeier <bk@lokigames.com>
* chp-rendering.sgml: SOURCE_RELATIVE specification.
* chp-state.sgml: clarified distance attentuation calculation
a bit, and added back in the linear version as an annotation.
Note: watch this, it's tied into the GAIN_LINEAR issue.
TODO: added dist calculation requirements.
2001-01-04 Bernd Kreimeier <bk@lokigames.com>
* chp-operation.sgml: INVALID_ENUM for getters and enable,
not INVALID_OPERATION. Later: Delete{Object}s accepts zero.
2000-12-04 Bernd Kreimeier <bk@lokigames.com>
* Makefile: added HTML ZIP targets ("update" for website).
2000-11-10 Bernd Kreimeier <bk@lokigames.com>
* WWW: reworked the OpenAL web site as in CVS. This
includes emptying HTML files with obsolete whitepaper
and specification content not even linked from the
official pages, and reworking the official pages to
remove redundancy, and generally point to the snapshots.
Also created snapshots page (along with cronjob and
automated update installed by Rafael).
* Makefile: added ZIP file generation to update target.
* index.html: edited for snapshots/ page on www.openal.org.
As it is next to impossible to reproduce the Official OpenAL
Look w/o lots of tap dancing, I use the style from the
DocBook HTML rendering instead.
2000-11-06 Bernd Kreimeier <bk@lokigames.com>
* Makefile (full): full rendering target added.
* ent-marks-full.sgml: created.
2000-10-27 Bernd Kreimeier <bk@lokigames.com>
* Makefile: rendering targets for cronjob driven update.
2000-10-26 Bernd Kreimeier <bk@lokigames.com>
* alc-context.sgml: annotation on release of hardware resources.
Removed version query enry point, added size-safe GetIntegerv
and GetString, removed GetErrorString, added integer and string
query tokens, added device enumeration query. Added more annotation.
* chp-rendering.sgml: remark on release of hardware resources.
* alc-context.sgml: had INVALID_DEVICE also marked by RFC.
Removed the "device parameter should be NULL" leftovers.
Added Query functions. Removed redundant device parameters
to avoid GLX-style redundancy and resulting BadMatch errors.
2000-10-25 Bernd Kreimeier <bk@lokigames.com>
* oalspecs.sgml: include extension list entity (below).
* ent-extensions.sgml: created.
Note: during several unsuccessful attempts to convince
DocBook and the DocBook toolchain to handle CDATA external
entities properly for <literallayout> and <programlisting>,
I also had to recover accidentally deleted files.
2000-10-24 Bernd Kreimeier <bk@lokigames.com>
* alc-context.sgml: shared object section. Mike Kelly request
as RFC. ALC Error section placeholder. ALC attribute section
as placeholder. Process/Suspend added plus annotation, Update
removed. More typo fixes. Added extension query. Removed old
RFC's. No UNDERFLOW error. No CHANNELS attribute, MIXAHEAD
redundant. Removed alcUpdate( PROCESS | SUSPEND ) RFC.
2000-10-23 Bernd Kreimeier <bk@lokigames.com>
* alc-context.sgml: entities for ALCdevice and ALCcontext.
Fixed typos reported by CarloV on non-pointer handles.
* chp-rendering.sgml: infinite LOOPING attribute.
2000-10-20 Bernd Kreimeier <bk@lokigames.com>
* ent-examples.sgml: experimenting with external sample.c
files as CDATA entities, to no avail.
* oalspecs.sgml: example entities.
2000-10-16 Bernd Kreimeier <bk@lokigames.com>
* chp-rendering.sgml: moved in buffer queueing.
Scratched PLAY_COUNT. Fixed SourceStart{v} residue.
* chp-queueing.sgml: proof-reading, contents then moved out.
2000-10-13 Bernd Kreimeier <bk@lokigames.com>
* chp-queueing.sgml: changed according to discussion.
Removed some, but not all redundant annotation, and removed
remainders of old attribute based approach. Added annotation
on repetition by multiple calls. Changed signatures.
2000-10-11 Bernd Kreimeier <bk@lokigames.com>
* chp-state.sgml: removed GAIN_LINAR based equations.
* chp-rendering.sgml: removed GAIN_LINAR.
* ext-gainlinear.sgml: collected GAIN_LINEAR related sections.
Note: choosing to use GAIN_LINEAR_LOKI for now. The duplication
of tokens complicates specification and implementation, and
requires further discussion.
* ent-marks.sgml: added Revision mark.
* oalspecs.sgml: added per-file revision history (appendix).
Note: we might wind up never rendering these, I can't see
a consistent way to do this.
* ChangeLog: moved in revision history from oalspecs.sgml.
Note: see the very first entry in this document for the
revision history that predates this ChangeLog.
TODO: include ChangeLog in RFC/Revision rendering.
* chp-introduction.sgml: removed CVS based revision history.
Added a %Revision marked section (we now have these per-file).
2000-10-10 Bernd Kreimeier <bk@lokigames.com>
* oalspecs.sgml: reworked for new distributed document.
* app-annotations.sgml: created from original doc.
* app-extensionprocess.sgml: created from original doc.
* app-extensions.sgml: created from original doc.
* app-constants.sgml: created from original doc.
* alc-context.sgml: created from original doc.
Note: this breaks the scheme a bit, as this is technically
a chapter, but if ALC turns into a multi-chapter
documentation at some point down the road it will have
to be a separate document anyway.
* chp-multichannel.sgml: created from original doc.
* chp-queueing.sgml: created from original doc.
* chp-buffers.sgml: created from original doc.
* chp-rendering.sgml: created from original doc.
* chp-state.sgml: created from original doc.
* chp-operation.sgml: created from original doc.
* chp-introduction.sgml: created from original doc.
* sec-bookinfo.sgml: created from original doc.
* ent-names.sgml: created from original doc.
* ent-marks.sgml: got it working.
Note: this will be a temporary file (created from the Makefile),
not sure whether it should be in CVS at all.
* ChangeLog: created.
2000--1999 Bernd Kreimeier <bk@lokigames.com>
* oalspecs.sgml: moved out CVS Revision History (below).
The AL Specification was originally maintained as an HTML
document, and subsequently as a single SGML file. With the
split into several files, it is no longer possible or
desirable to maintain a single revision history. As we
have a manually maintained revhistory within the DocBook
source, I decided to move the old revision history into
the ChangeLog.
Revision 1.11 2000/10/11 18:44:46 bk
More JMJ typo corrections. IA-SID I3DL2 section rephrased. Moved
marked section toggles in ent-marks.sgml file so that these can
be generated or modified from the Makefile. Split document up into
several separate files using external entities. Created external
ChangeLog. From now on, revision history and changes will be
maintained in the ChangeLog as it is scattered over files.
Revision 1.10 2000/09/27 22:57:02 bk
Commit w/o subdoc (doesn't work).
Revision 1.9 2000/09/27 22:54:36 bk
Typos from MKV and JMJ. Fixed Inverse Square Law. Scratched
ProgagationSpeed. Described distance models in full. Changed
to INVERSE_DISTANCE (both models use ROF). Added GH text (parts)
as annotation to "View" sections, added Basic AL Operation text
he sent (some changes, removed redundant section), marked source
as Example sections. Changed Terminology annotation. Added TBA
on Fundamentals. RFC'ed distributed error section from GL and
annotation. Added TBA on Floating Point Computation. Added AL
State TBA. Added AL entity as opposed to OAL. Added Command Syntax
TBA (minimal) plus annotation. More fixes from JMJ. No NaN
check comment. Rephrased invalid commmands. Disclaimer on
Enable/Disable being unused. Query with NULL destination
clarified. Example values for simple query. TBA on data
conversions. Cleaned out Time query/scaling, added RFC,
marked DURATION/REMAINDER as Scratch. Euclidean. No Transforms
now annotation. Promoted RFC on Source( BUFER, NONE ) to spec
text. Scratch'ed Streaming Buffer remarks. Removed IMPLIED.
Scratch'ed Buffer Traversal and a whole shebang of queueing
annotation to go with it. ALC cleanup, RFC on multiple
current contexts. Skipped Buffer Queueing section for now.
SUBDOC NO in DocBook declaration. Validation pass for CVS.
Revision 1.8 2000/09/20 01:21:33 bk
Fixes from Ian Ollman: fixed wrong title on Buffer Attributes
section. Annotation on No application selected Names. Fixes
from JMJ: typos and mistakes on I3DL2. Renamed LOOP_COUNT to
PLAY_COUNT and clarified counting as requested. DOPPLER_FACTOR,
DOPPLER_VELOCITY, Doppler Effect section rewritten according to
announced changes. Removed DistanceFactor, added scale invariance.
Scratch-marked Multichannel sketch. Added BufferWriteData as Loki
extension. Removed obsolete RFC on depercating BUFFER. Rewrote
Buffer queueing state section and renamed BUFFERS_USED to
BUFFERS_PROCESSED following discussion with John Kraft, to remove
ambiguity. Rewrote BUFFERS_PROCESSED description. Added
MAX_DISTANCE plus MUTE annotation. Added No Culling section.
Edited DISTANCE_MODEL section. Distance Model Source Attributes
added. Rolloff quantization annotation added. Evaluation order
on attenuation/gain. Marked Scratch the current IASIG section
per JMJ's request, added Source Environment Attribute section
as TBA. Removed and moved RFC's (AppendData, GenStreaming).
Clarified directional attenuation. Clarified CONE_OUTER_GAIN
as scaling factor. Added a Programmers and Implementors View.
Revision 1.7 2000/08/15 02:47:03 bk
Fixed RFC markup error needed for Full version.
Revision 1.6 2000/08/15 02:20:49 bk
Clarified BUFFER_USED vs. buffer state. Started section on
handling multichannel output. Moved out GenStreamingBuffer
in annotation on BufferAppendData extension. Added BufferWriteData
with internalFormat parameter and discussion on mono vs.
multichannel buffers. Added Multichannel objects (kept short in
case we demote to extension or replace). Some annotation.
Tried GGI docbook2texi in attempt to end those rogue linux/doc
activities, to no avail. Removed messy scratchpad section.
Removed outdated example listing. Turned remaining scratch
annotation into appendix. Created minimal Makefile (cleanup).
Revision 1.5 2000/08/08 02:56:05 bk
alcGetCurrentContext. Attempt to formulate Design Objectives as
a guideline. RFC's on INITIAL state, ACTIVE misnomer. RFC on
INVALID_POINTER. Lots of scratch stuff (fallout from buffer
queueing discussions). Annotations on various buffer queue
rejects and related issues. Added Scaling and Timing sections
and related calls. Added CONE_OUTER_GAIN. Added Doppler sections.
Rewrote and shuffle globale state, simple query, string query.
Moved Extensions sections in Appendix. Added annotation and
RFC's regarding distance/gain model. No more ILLGEAL - finally
checked the specs and Mesa 3.3 to be sure. Picked OPERATION at
the same time, also specs conformat (no comment...). Removed
JMJ as responsible author (all blame shall be mine). Fixed
Play(), INITIAL vs. STOPPED. Edited related RFC's, stripped
obsolete commentary. Rewrote State/State Transition section.
Fixes on SGML. CHANNELS and BITS moved in RFC's. Moved and
rewrote RFC on Duration/Remainder queries into Time section.
Stripped BYTE_LOKI of all but the essentials. Added placeholders
for Callback and AppendData in same (backwards compatibility)
section. Lots of Buffer Queueing.
Revision 1.4 2000/07/25 17:19:17 bk
Changed ILLEGAL_OPERATION to ILLEGAL_COMMAND consistently. Added
excerpts from mailinglist to scratch section. Added Appendix on
Extension Process. Typos. RFC on EXTENSIONS changed to Annotation.
SGML validation and error fixes (not done on cvs1.3, sorry).
Revision 1.3 2000/07/24 21:18:53 bk
Reordered manual revision history to be CVS compliant. Diff against
Rev. 1.4/bk000626 as it was not checked in CVS. Created scratch
section for removed RFC 's. Checked edits on Extension section and
removal of related RFC/bk000506. Converted removed RFC/bk000504
on IsExtensionPresent in Annotation. Rewrote Mike's annotations
on source types and distance attentuation clamping as RFC's and
added some removed RFC sections back. Rewrote annotation added by
MikeV on compressed buffers, split of RFC on AL_SIZE query.
Re-added RFC's an buffer attribute defaults, edited annotation
on GetEnumValue return. RFC's on factory methods for streaming
buffers, memory budgeting, initial object state. Re-inserted and
extended RFC on format enum issue. Re-inserted the global
setter/getter in scratch section. Implementation requirement
section. Resurrected CONE_OUTSIDE_GAIN as RFC. BITS bitching,
annotation to explain why not enumerating frequencies. Got a grip
and recognized BITS and CHANNELS as query-only. More on frequency
in BufferData. Into CVS before current discussions are added.
Revision 1.2 2000/07/19 15:16:58 briareos
Enable/Disable return void, not enum.
Revision 1.1 2000/06/29 00:27:24 briareos
Initial draft of OpenAL specs.
1.4/briareos : not in CVS
Finished editing related to my comments, with Joe's
feedback, in preparation for use by Creative and eventual
public dissemination later this week.
1.4/bk000626 : not in CVS
Started using id attribute on RFC note elements, to ensure unique
identifiers. Added Annote level. Added oal15-jm/overview.html
changes. Added oal15-jm/object-state.html (mostly). Removed
Filtering/Spatialization distinction and merged attribute table.
Moved Filter chapter to annotation. Moved Geometry to annotation,
rewrote annotation with my latest conclusions on A3D/EAGLE like
approach. Stripped out ALU and ALUT, added annotation on reasons.
Added some text to introduction chapter. Moved ALC chapter to end
of specification. Followed John Hall advice to enable section
numbers in print stylesheet. Rewrote section on GetError. Created
I3DL2 extension appendix. Reworked all tables for better
formatting with separated descriptions. Took out a bunch of
outdated RFC's. Rewrote Query and String Query section. Added
Scratch sections. Added ARB/Ack section. Didn't get RFC comments
from MikeV. Fixed permission to copy.
1.4/bk000508 : not in CVS.
Added RFC to Device section. Made nested RFC around entire
device section to make sure. Added trailing blanks to data type
entities as a cheap workaround to the HTML backend problem in
FuncSynopsis. Added RFC from BYTE_LOKI discussion on mailinglist.
1.4/bk000507 : not in CVS.
Added altypes.h info on scalar types, copied Linux OpenGL Base
ABI layout. Also added some missing enums. Checked alc.h header,
added UpdateContext and RFC's. Changed alc*Context signatures to
include ALCdevice handle. Checked al.h header, fixed outdated
BufferData/BufferAppendData signatures, added RFC's. Added comments
on differing return types. This pretty much concludes the inventory.
1.4/bk000506 : not in CVS.
The HTML in CVS was completely mangled between the 1.2 and 1.3
revisions. Also, redundant al and AL_ prefixes were added, and
the document was restructured. I tried SaveAs ASCII and
whitespace insensitive compare, and finally did the compare
manually (no guarantees). The text sections that looked
relevant have been added in RFC's with the bk000506 tag.
Also added a revision history and CVS tags for future CVS based
revision control (post-E3).
1.4/bk000505 : not in CVS.
SGML version. Merges AL specification and API reference as
of GDC (v1.2) with each other. Adds ALC placeholder.
Addition of several RFCs based on recent discussions.
1.3/cvogelsa : only in CVS.
api-reference.html CVS v1.14
specification.html CVS v1.3
1.2/briareos : 8 March 2000, released at GDC.
api-reference.html CVS v1.13
specification.html CVS v1.2
x.xx/nn : early specifications.
Neither the early working papers by Terry Sikes, Sean L. Palmer
and others nor the first versions of the &OAL; specification
as compiled at Loki were archived and versioned in a coherent way.

148
neo/openal/docs/Makefile Normal file
View File

@@ -0,0 +1,148 @@
## ------------------------------------------------
## Makefile for openal/docs/
## DocBook stuff
DB2PS = db2ps
DB2PDF = db2pdf
DB2HTML = db2html
## TexInfo stuff
MAKEINFO = makeinfo
## Targets
OALSPEC = oalspecs
DB_OBJS = $(OALSPEC).ps $(OALSPEC)/index.html
TEXI_OBJS = openal.info
.SUFFIXES: .texi .info
## Rules
%.ps : %.sgml
$(DB2PS) $<
%/index.html : %.sgml
$(DB2HTML) $<
## Fixme - config.h
%.info : %.texi ../config.h
$(MAKEINFO) $<
## ----------------
## Standard targets
default: all
all: render
render: $(DB_OBJS)
texi: $(TEXI_OBJS)
## --------------
## Cronjob target
update: specs annotated full
## ----------------------------------------------------------
## Specification - prototypes, tokens, explanation
##
specs-ps:
-rm -f $(OALSPEC)-specs.ps
cp ent-marks-specification.sgml ent-marks.sgml
$(DB2PS) $(OALSPEC).sgml
mv $(OALSPEC).ps $(OALSPEC)-specs.ps
zip -9 $(OALSPEC)-specs.ps.zip $(OALSPEC)-specs.ps
specs-html:
-rm -rf $(OALSPEC)-specs/
cp ent-marks-specification.sgml ent-marks.sgml
$(DB2HTML) $(OALSPEC).sgml
mv $(OALSPEC) $(OALSPEC)-specs
-rm $(OALSPEC)-specs.html.zip
zip -r9 $(OALSPEC)-specs.html.zip $(OALSPEC)-specs/
specs: specs-ps specs-html
## -----------------------------------------------------------
## Annotated Version - including annotation seections
## (not Programmer's Guide, no examples)
annotated-ps:
-rm -f $(OALSPEC)-annote.ps
cp ent-marks-annotated.sgml ent-marks.sgml
$(DB2PS) $(OALSPEC).sgml
mv $(OALSPEC).ps $(OALSPEC)-annote.ps
zip -9 $(OALSPEC)-annote.ps.zip $(OALSPEC)-annote.ps
annotated-html:
-rm -rf $(OALSPEC)-annote/
cp ent-marks-annotated.sgml ent-marks.sgml
$(DB2HTML) $(OALSPEC).sgml
mv $(OALSPEC) $(OALSPEC)-annote
-rm $(OALSPEC)-annote.html.zip
zip -r9 $(OALSPEC)-annote.html.zip $(OALSPEC)-annote/
annotated: annotated-ps annotated-html
## ----------------------------------------------------------
## FULL Version - include's the RFC's and everything else
##
full-ps:
-rm -f $(OALSPEC)-full.ps
cp ent-marks-full.sgml ent-marks.sgml
$(DB2PS) $(OALSPEC).sgml
mv $(OALSPEC).ps $(OALSPEC)-full.ps
zip -9 $(OALSPEC)-full.ps.zip $(OALSPEC)-full.ps
full-html:
-rm -rf $(OALSPEC)-full/
cp ent-marks-full.sgml ent-marks.sgml
$(DB2HTML) $(OALSPEC).sgml
mv $(OALSPEC) $(OALSPEC)-full
-rm $(OALSPEC)-full.html.zip
zip -r9 $(OALSPEC)-full.html.zip $(OALSPEC)-full/
full: full-ps full-html
## ----------------------------------------------------------
## ZIP - create archive
##
clean: db_clean texi_clean
db_clean:
-rm -f $(OALSPEC).dvi
-rm -f $(OALSPEC).aux
-rm -f $(OALSPEC).log
-rm -f $(OALSPEC).tex
-rm -rf $(OALSPEC).junk
-rm -f \#*\#
-rm -f *~
texi_clean:
@echo "Not done."
install:
@echo "Not done."
distclean: clean
-rm -rf \
$(OALSPEC)-full/ \
$(OALSPEC)-full.ps \
$(OALSPEC)-annote/ \
$(OALSPEC)-annote.ps \
$(OALSPEC)-specs/ \
$(OALSPEC)-specs.ps \
*.zip

846
neo/openal/docs/alc-context.sgml Normal file
View File

@@ -0,0 +1,846 @@
<chapter id="alc">
<title>AL Contexts and the ALC API</title>
<para>
This section of the AL specification describes ALC, the AL Context API.
ALC is a portable API for managing &AL; contexts, including
resource sharing, locking, and unlocking. Within the core AL API the
existence of a Context is implied, but the Context is not exposed. The
Context encapsulates the state of a given intance of the AL state machine.
</para>
<para>
To avoid confusion with the AL related prefixes implied throughout
this document, the "alc" and "ALC_" prefixes have been made explicit
in the ALC related sections.
</para>
<para>
ALC defines the following objects: Contexts.
</para>
<![ %Annote [
<note><title>Annotation (ALC entry points)</title><para>
While the actual ALC implemention might be supplied
as a separate library, or as part of a server or
daemon, the specification requires that the AL library
provides the actual ALC entry points.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (ALC OS independend)</title><para>
ALC is meant to be OS-independent. OS specifics are
expected to be adressed by defining proper device
specifiers strings, and configuration attributes.
In this, ALC differs from GLX/WGL, which (due to the
tighter coupling with the window manager and
operating system) attempt to abstract OS specifics
to a much lesser degree.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001024-02"><title>RFC/ Issues </title><para>
Hardware init/deinit, mapping many processes with
multiple contexts to many devices, sharing resources
among processes.
</para></note>
]]>
<sect1>
<title>Managing Devices</title>
<para>
ALC introduces the notion of a Device. A Device can be,
depending on the implementation, a hardware device, or
a daemon/OS service/actual server. This mechanism also
permits different drivers (and hardware) to coexist
within the same system, as well as allowing several
applications to share system resources for audio, including
a single hardware output device. The details are left
to the implementation, which has to map the available
backends to uniq7ue device specifiers (represented as
strings).
</para>
<![ %Annote [
<note><title>Annotation (Network transparency)</title><para>
&AL; is meant for interoperability with &OGL;. Some
implementations of &OGL; bindings (e.g. GLX) are network
transparent. The Device API theoretically allows for
a network transparent AL implementation. No wire protocol
is specified, no specification or implementation is planned.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Device Enumeration)</title><para>
At this time, ALC does not provide mechanism to query
for available devices, and request device enumerations.
This might be added at a later time, depending on demand
and the ability to abstract OS and configuration specifics.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (X11 Audio)</title><para>
The ALC API intentionally mimicks XOpenDisplay
and XCloseDisplay. There is no X Audio standard,
although proposals have been made in the past.
The ALC API design accounts for this possibility
in a minimal way.
</para></note>
]]>
<sect2>
<title>Connecting to a Device</title>
<para>
The alcOpenDevice function allows the application (i.e. the
client program) to connect to a device (i.e. the server).
<funcsynopsis><funcprototype>
<funcdef> &device; * <function>alcOpenDevice</function></funcdef>
<paramdef> const &ubyte;* <parameter>deviceSpecifier</parameter></paramdef>
</funcprototype></funcsynopsis>
If the function returns NULL, then no sound driver/device has
been found. The argument is a null terminated string that requests
a certain device or device configuration. If NULL is specified,
the implementation will provide an implementation specific default.
</para>
<![ %Annote [
<note><title>Annotation (Operating system dependencies)</title><para>
At this point, system specific configuration, and operating system
specific details, are handled by leaving the details of the
string specifier to the implementation. The application coder
has to determine how he wants to obtain this information from the
OS or the user. If, at a later point, device enumeration and
configuration requests are supported through ALC, the resulting
string might still be operating system and implementation specific.
</para></note>
]]>
</sect2>
<sect2>
<title>Disconnecting from a Device</title>
<para>
The alcCloseDevice function allows the application (i.e. the
client program) to disconnect from a device (i.e. the server).
<funcsynopsis><funcprototype>
<funcdef> &void; <function>alcCloseDevice</function></funcdef>
<paramdef> &device; * <parameter>deviceHandle</parameter></paramdef>
</funcprototype></funcsynopsis>
If deviceHandle is NULL or invalid, an ALC_INVALID_DEVICE error
will be generated. Once closed, a deviceHandle is invalid.
</para>
</sect2>
</sect1>
<sect1>
<title>Managing Rendering Contexts</title>
<para>
All operations of the AL core API affect a current AL context.
Within the scope of AL, the ALC is implied - it is not visible as
a handle or function parameter. Only one AL Context per INprocess
can be current at a time. Applications maintaining multiple
AL Contexts, whether threaded or not, have to set the current
context accordingly. Applications can have multiple threads
that share one more or contexts. In other words, AL and ALC are
threadsafe.
</para>
<para>
The default AL Context interoperates with a hardware device driver.
The application manages hardware and driver resources by
communicating through the ALC API, and configures and uses
such Contexts by issuing AL API calls. A default AL Context
processes AL calls and sound data to generate sound output.
Such a Context is called a Rendering Context. There might
be non-rendering contexts in the future.
</para>
<para>
The word "rendering" was chosen intentionally to emphasize the
primary objective of the AL API - spatialized sound - and the
underlying concept of AL as a sound synthesis pipeline that
simulates sound propagation by specifying spatial arrangements
of listeners, filters, and sources. If used in describing an
application that uses both &OGL; and &AL;, "sound rendering
context" and "graphics rendering context" should be used for
clarity. Throughout this document, "rendering" is used
to describe spatialized audio synthesis (avoiding ambiguous
words like "processing", as well as proprietary and restrictive
terms like "wavetracing").
</para>
<sect2>
<title>Context Attributes</title>
<para>
The application can choose to specify certain attributes for
a context. Attributes not specified explicitely are set to
implementation dependend defaults.
</para>
<para>
<table>
<title>Context Attributes</title>
<tgroup cols="2" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>Name</>
<entry>Description</>
</row>
</thead>
<tbody>
<row>
<entry>ALC_FREQUENCY</>
<entry>Frequency for mixing output buffer, in units of Hz.</>
</row>
<row>
<entry>ALC_REFRESH</>
<entry>Refresh intervalls, in units of Hz.</>
</row>
<row>
<entry>ALC_SYNC</>
<entry>Flag, indicating a synchronous context.</>
</row>
</tbody>
</tgroup>
</table>
</para>
<![ %Annote [
<note><title>Annotation (Refresh Control)</title><para>
Applications might have a fixed, or bounded, schedule for
state changes (e.g. synchronously with the GL framerate).
In this case it is desirable to specify the mixahead
interval (milliseconds), or refresh rate (Hz), for the
mixing thread. This is especially important for a synchronous
context, where the application has to specify the refresh
interval it intends to keep.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001026-05"><title>RFC / Mixing Buffer Configuration </title><para>
ALC_RESOLUTION was originally used to specify the accuracy of the
mixing output buffer. For the time being this is not supported, but
could be added if mixing path and result accuracy control is desirable
to scale resource requirements.
A full ALC_FORMAT (including channel and other attributes) does not
make sense for rendering contexts, but will be necessary for PBuffers
(mix to memory).
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001026-01"><title>RFC / LOKI extensions </title><para>
<programlisting>
ALC_SOURCES_HINT_LOKI, /* # of sources to pre-allocate */
ALC_BUFFERS_HINT_LOKI, /* # of buffers to pre-allocate */
ALC_CD_LOKI, /* demand CD/DVD control */
</programlisting>
</para></note>
]]>
</sect2>
<sect2>
<title>Creating a Context</title>
<para>
A context is created using alcCreateContext. The device parameter
has to be a valid device. The attribute list can be NULL,
or a zero terminated list of integer pairs composed of valid
ALC attribute tokens and requested values.
<funcsynopsis><funcprototype>
<funcdef> &context; * <function> alcCreateContext </function></funcdef>
<paramdef> const &device; * <parameter> deviceHandle </parameter></paramdef>
<paramdef> &int; * <parameter> attrList </parameter></paramdef>
</funcprototype></funcsynopsis>
Context creation will fail
if the application requests attributes that, by themselves,
can not be provided. Context creation will fail if the
combination of specified attributes can not be provided.
Context creation will fail if a specified attribute, or
the combination of attributes, does not match the default
values for unspecified attributes.
</para>
</sect2>
<sect2>
<title>Selecting a Context for Operation</title>
<para>
To make a Context current with respect to AL Operation (state
changes by issueing commands), alcMakeContextCurrent is used.
The context parameter can be NULL or a valid context pointer.
The operation will apply to the device that the context was
created for.
<funcsynopsis><funcprototype>
<funcdef> &bool; <function> alcMakeContextCurrent </function></funcdef>
<paramdef> &context; * <parameter> context </parameter></paramdef>
</funcprototype></funcsynopsis>
For each OS process (usually this means for each application), only
one context can be current at any given time. All AL commands apply
to the current context. Commands that affect objects shared among
contexts (e.g. buffers) have side effects on other contexts.
</para>
<![ %Annote [
<note><title>Annotation (No Explicit Device)</title><para>
An ALC context is bound to the device it was created for.
The context carries this information, thus removing the
need to specify the device explicitely. Contexts can not
be made current for any other device aside from the one
they were created for.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (No Multiple Current)</title><para>
There is only one current context per process, even
in multithreaded applications, even if multiple
devices are used.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Current NULL)</title><para>
The implementation is encouraged to exploit optimizations
possible if the application sets the current context
to NULL, indicating that no state changes are intended
for the time being. The application should not set the
current context to NULL if more state changes are
pending on the most recent, or another context created
for the same device.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Shared Objects)</title><para>
Buffers are shared among contexts. As mutiple contexts
can exist at the same time, the state of shared objects
is also shared among contexts.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001026-06"><title>RFC / Buffer Deletion </title><para>
Buffers that have not yet been processed in another context
can not be deleted from any other context.
</para></note>
]]>
</sect2>
<sect2>
<title>Initiate Context Processing</title>
<para>
The current context is the only context accessible to state
changes by AL commands (aside from state changes affecting
shared objects). However, multiple contexts can be processed
at the same time. To indicate that a context should be
processed (i.e. that internal execution state like offset
increments are supposed to be performed), the application
has to use alcProcessContext.
<funcsynopsis><funcprototype>
<funcdef> &void; <function>alcProcessContext</function></funcdef>
<paramdef> &context; * <parameter> context </parameter></paramdef>
</funcprototype></funcsynopsis>
Repeated calls to alcProcessContext are legal, and do not
affect a context that is already marked as processing. The
default state of a context created by alcCreateContext is
that it is not marked as processing.
</para>
<![ %Annote [
<note><title>Annotation (Sync and async implementations)</title><para>
Unfortunately, the exact semantics of alcProcessContext is
not independend of the implementation. Ideally it should be completely
transparent to the application whether the sound driver is threaded or
synced. Unfortunately a synced context has to have its execution
initiated by the application, which requires calls of
alcProcessContext timed in accordance to the drivers mixahead,
or the rendering buffer will underflow. For a threaded driver,
the implementation is free to consider alcProcessContext
a NOP once the context has been marked as processing.
</para><para>
One consequence is that an application that was developed
using a threaded implementation of AL might not work
properly with a synchronous implementation of AL (on
the other hand, an AL application that works using a
synchronous implementation is guaranteed to work with
a threaded implementation.
</para><para>
Enforcing alcProcessContext calls would defeat the purpose
of a threaded implementation. Permitting the AL implementation
to e.g. schedule optimizations based on alcProcessContext
calls would similarly obfuscate the exact semantincs.
Consequently, the application coder has to accept this
implementation dependency, and has to rely on the ALC_SYNC
attribute to explicitely request a synchronous implementation.
The implementation can expect the application to be aware
of the additonal constraints imposed on alcProcessContext in
this case.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Multiple Contexts and SYNC refresh)</title><para>
The application can request SYNC contexts or threaded contexts,
however, the implementation is not obliged to provide both, or provide
a mixture of both on the same device.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001024-03"><title>RFC/ Implications for Networking</title><para>
What does alcProcessContext imply for networking?
For AL, will we add alFlush/alFinish?
</para></note>
]]>
</sect2>
<sect2>
<title>Suspend Context Processing</title>
<para>
The application can suspend any context from processing
(including the current one). To indicate that a context should be
suspended from processing (i.e. that internal execution state like
offset increments is not supposed to be changed), the application
has to use alcSuspendContext.
<funcsynopsis><funcprototype>
<funcdef> &void; <function>alcSuspendContext</function></funcdef>
<paramdef> &context; * <parameter> context </parameter></paramdef>
</funcprototype></funcsynopsis>
Repeated calls to alcSuspendContext are legal, and do not
affect a context that is already marked as suspended. The
default state of a context created by alcCreateContext is
that it is marked as suspended.
</para>
<![ %Annote [
<note><title>Annotation (Sync and async implementations)</title><para>
Unfortunately, the exact semantics of alcSuspendContext is
also not independend of the implementation. For a threaded
implementation, alcSuspendContext is necessary to ensure a context
is not processed. For a synchronous implementation, omitting
alcProcessContext calls will ultimately have the same effect,
but will also generate rendering buffer underflow errors.
Again, the application coder that requests a synchronous
context using ALC_SYNC has to make sure that alcSuspendContext
is used accordingly.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Suspending vs. Muting a context)</title><para>
By setting Listener GAIN to zero, an application can mute a
context, and expect the implementation to bypass all rendering.
However, the context is still processing, and the internal
execution state is still updated accordingly. Suspending a
context, whether muted or not, will incidentally suspend rendering
as well. However, it is the application's responsibility to
prevent artifacts (e.g. by proper GAIN control to fade in and
out). It is recommended to mute a context before suspending.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Current Context Suspended)</title><para>
It is possible to make a suspended context current, or
suspend the current context. In this case, the implementation
is still obliged to immediately verify AL commands as they
are issued, and generate errors accordingly. The implementation
is permitted to postpone propagating the actual state changes
until the context is marked for processing again, with the
exception of dereferencing data (e.g. buffer contents).
For efficiency reasons (memory usage), most if not all
AL commands applied to a suspended context will usually
be applied immediately. State changes will have to be applied
in the sequence they were requested. It is possible to
use suspension of a current context as an explicit locking
(to enforce apparent synchronicity), but execution is still
guaranteed to be in sequence, and the implementation is not
expected to optimize this operation. A typical use would
be setting up the initial configuration while loading a
scene.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Release of Hardware Resources)</title><para>
The specification does not guarantee that the implementation
will release hardware resources used by a suspended context.
This might well depend on the details of the hardware and driver.
Neither a muted context nor a suspended context can be expected
to free device resources. If all contexts for a given device
are suspended, and no context of this device is current, the
implementation is expected to release all hardware resources if possible.
</para></note>
]]>
</sect2>
<sect2>
<title>Destroying a Context</title>
<para>
<funcsynopsis><funcprototype>
<funcdef> &void; <function> alcDestroyContext </function></funcdef>
<paramdef> &context; * <parameter> context </parameter></paramdef>
</funcprototype></funcsynopsis>
The correct way to destroy a context is to first release it using
alcMakeCurrent and NULL. Applications should not attempt to destroy
a current context.
</para>
</sect2>
</sect1>
<sect1>
<title>ALC Queries</title>
<sect2>
<title>Query for Current Context</title>
<para>
The application can query for, and obtain an handle to, the current
context for the application. If there is no current context, NULL is
returned.
<funcsynopsis><funcprototype>
<funcdef> &context; * <function>alcGetCurrentContext</function></funcdef>
<void>
</funcprototype></funcsynopsis>
</para>
</sect2>
<sect2>
<title>Query for a Context's Device</title>
<para>
The application can query for, and obtain an handle to, the device
of a given context.
<funcsynopsis><funcprototype>
<funcdef> &device; * <function>alcGetContextsDevice</function></funcdef>
<paramdef> &context; * <parameter> context </parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
</sect2>
<sect2>
<title>Query For Extensions</title>
<para>
To verify that a given extension is available for the current
context and the device it is associated with, use
<funcsynopsis>
<funcprototype>
<funcdef>&bool;<function>IsExtensionPresent</function></funcdef>
<paramdef> const &device; * <parameter>deviceHandle</parameter></paramdef>
<paramdef>const &ubyte; * <parameter> extName </parameter></paramdef>
</funcprototype>
</funcsynopsis>
A NULL name argument returns FALSE, as do invalid and unsupported string
tokens. A NULL deviceHandle will result in an INVALID_DEVICE error.
<![ %Annote [
<note><title>Annotation (Exlicit Device Parameter)</title><para>
Certain ALC Extensions might be relevant to context creation
(like additional attributes, or support for unusual multi-context
combinations), thus the application might have to query these
before a context is created. On the other hand, ALC Extensions
are specific to the device.
</para></note>
]]>
</para>
</sect2>
<sect2>
<title>Query for Function Entry Addresses</title>
<para>
The application is expected to verify the applicability of
an extension or core function entry point before requesting
it by name, by use of alcIsExtensionPresent.
<funcsynopsis><funcprototype>
<funcdef> &void; * <function> alcGetProcAddress</function></funcdef>
<paramdef> const &device; * <parameter>deviceHandle</parameter></paramdef>
<paramdef> const &ubyte; * <parameter> funcName </parameter></paramdef>
</funcprototype></funcsynopsis>
Entry points can be device specific, but are not context specific.
Using a NULL device handle does not guarantee that the entry
point is returned, even if available for one of the available
devices. Specifying a NULL name parameter will cause an
ALC_INVALID_VALUE error.
</para>
</sect2>
<sect2>
<title>Retrieving Enumeration Values</title>
<para>
Enumeration/token values are device independend, but tokens
defined for extensions might not be present for a given device.
Using a NULL handle is legal, but only the tokens defined by
the AL core are guaranteed. Availability of extension tokens
dependends on the ALC extension.
<funcsynopsis><funcprototype>
<funcdef> &uint; <function> alcGetEnumValue </function></funcdef>
<paramdef> const &device; * <parameter>deviceHandle</parameter></paramdef>
<paramdef> const &ubyte; <parameter> enumName </parameter></paramdef>
</funcprototype></funcsynopsis>
Specifying a NULL name parameter will cause an
ALC_INVALID_VALUE error.
</para>
</sect2>
<sect2>
<title>Query for Error Conditions</title>
<para>
ALC uses the same conventions and mechanisms as AL for error
handling. In particular, ALC does not use conventions
derived from X11 (GLX) or Windows (WGL).
The alcGetError function can be used to query ALC errors.
<funcsynopsis><funcprototype>
<funcdef>&enum;<function>alcGetError</function></funcdef>
<paramdef> &device; * <parameter>deviceHandle</parameter></paramdef>
</funcprototype></funcsynopsis>
Error conditions are specific to the device.
</para>
<para>
<table>
<title>Error Conditions</title>
<tgroup cols="2" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>Name</>
<entry>Description</>
</row>
</thead>
<tbody>
<row>
<entry>ALC_NO_ERROR</>
<entry>The device handle or specifier does name an accessible driver/server.</>
</row>
<row>
<entry>ALC_INVALID_DEVICE</>
<entry>The Context argument does not name a valid context.</>
</row>
<row>
<entry>ALC_INVALID_CONTEXT</>
<entry>The Context argument does not name a valid context.</>
</row>
<row>
<entry>ALC_INVALID_ENUM</>
<entry>A token used is not valid, or not applicable.</>
</row>
<row>
<entry>ALC_INVALID_VALUE</>
<entry>An value (e.g. attribute) is not valid, or not applicable.</>
</row>
</tbody>
</tgroup>
</table>
</para>
<![ %Annote [
<note><title>Annotation (No UNDERFLOW error)</title><para>
Applications using synchronous (and, depending on CPU
load, even an asynchronous implementation itself) might
fail to prevent underflow of the rendering output
buffer. No ALC error is generated in these cases,
as it this error condition can not be applied to a
specific command.
</para></note>
]]>
</sect2>
<sect2>
<title>String Query</title>
<para>
The application can obtain certain strings from ALC.
<funcsynopsis><funcprototype>
<funcdef>const &ubyte; * <function>alcGetString</function></funcdef>
<paramdef> &device; * <parameter>deviceHandle</parameter></paramdef>
<paramdef> &enum; <parameter> token </parameter></paramdef>
</funcprototype></funcsynopsis>
For some tokens, NULL is is a legal value for the deviceHandle.
In other cases, specifying a NULL device will generate an
ALC_INVALID_DEVICE error.
</para>
<para>
<table>
<title>String Query Tokens</title>
<tgroup cols="2" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>Name</>
<entry>Description</>
</row>
</thead>
<tbody>
<row>
<entry>ALC_DEFAULT_DEVICE_SPECIFIER</>
<entry>The specifier string for the default device (NULL handle is legal).</>
</row>
<row>
<entry>ALC_DEVICE_SPECIFIER</>
<entry>The specifier string for the device (NULL handle is not legal).</>
</row>
<row>
<entry>ALC_EXTENSIONS</>
<entry>The extensions string for diagnostics and printing.</>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In addition, printable error message strings are provided for
all valid error tokens, including ALC_NO_ERROR, ALC_INVALID_DEVICE,
ALC_INVALID_CONTEXT, ALC_INVALID_ENUM, ALC_INVALID_VALUE.
</para>
</sect2>
<sect2>
<title>Integer Query</title>
<para>
The application can query ALC for information using an integer
query function.
<funcsynopsis><funcprototype>
<funcdef> &void; <function>alcGetIntegerv</function></funcdef>
<paramdef> &device; * <parameter>deviceHandle</parameter></paramdef>
<paramdef> &enum; <parameter> token </parameter></paramdef>
<paramdef> &sizei; <parameter> size </parameter></paramdef>
<paramdef> &int; <parameter> dest </parameter></paramdef>
</funcprototype></funcsynopsis>
For some tokens, NULL is a legal deviceHandle. In other
cases, specifying a NULL device will generate an ALC_INVALID_DEVICE
error. The application
has to specify the size of the destination buffer provided.
A NULL destination or a zero size parameter will cause ALC to ignore
the query.
</para>
<para>
<table>
<title>Integer Query Tokens</title>
<tgroup cols="2" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>Name</>
<entry>Description</>
</row>
</thead>
<tbody>
<row>
<entry>ALC_MAJOR_VERSION</>
<entry>Major version query.</>
</row>
<row>
<entry>ALC_MINOR_VERSION</>
<entry>Minor version query.</>
</row>
<row>
<entry>ALC_ATTRIBUTES_SIZE</>
<entry>The size required for the zero-terminated attributes
list, for the current context. NULL is an invalid
device. NULL (no current context for the
specified device) is legal.</>
</row>
<row>
<entry>ALC_ALL_ATTRIBUTES</>
<entry>Expects a destination of ALC_CURRENT_ATTRIBUTES_SIZE,
and provides the attribute list for the current
context of the specified device. NULL is an invalid
device. NULL (no current context for the
specified device) will return the default attributes
defined by the specified device.</>
</row>
</tbody>
</tgroup>
</table>
</para>
<![ %Annote [
<note><title>Annotation (Backward Compatibility)</title><para>
Backward compatibility is guaranteed only for minor revisions.
Breaking ABI backwards compatibility will require a issuing
major revision.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001026-02"><title>RFC / Version Matching </title><para>
The ALC version can be different from the AL version.
The ALC major version has to be identical between
application and driver (client and server).
The ALC minor version can differ between client and server,
and the minimum of the two minor version numbers is returned.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk001027-03"><title>RFC / Device Enumeration </title><para>
ALC_NUM_DEVICE_SPECIFIERS could be provided as an extension,
but it requires the number of device configurations to be
finite and small, as they are to be represented by strings.
</para></note>
]]>
</sect2>
</sect1>
<sect1>
<title>Shared Objects</title>
<para>
For efficiency reasons, certain AL objects are shared across
ALC contexts. At this time, AL buffers are the only shared
objects.
</para>
<![ %RFC [
<note id="rfc-bk001024-01"><title>RFC/ Sharing Sources?</title><para>
Mike Kelly from Dynamix describes an application scenario with
multiple camera views of the same scene (implemented using
several viewports on a single, "split screen", context)
in which he needs multiple listeners (one per view) to
preceive the same sources, with the rendering results of
each listener to mixed for a single output device. As an
alternative to permitting multiple listeners within a context,
it might be preferable to introduce a mechanism to explicitely
share certain AL objects among contexts, at a later time.
It is not desirable to share Sources by default, especially
as the more common multi-listener application is expected to
maintain listeners with disjunct sets of sources.
</para></note>
]]>
<sect2>
<title>Shared Buffers</title>
<para>
Buffers are shared among contexts. The processing state of a buffer
is determined by the dependencies imposed by all contexts, not just
the current context. This includes suspended contexts as well as
contexts that are processing.
</para>
</sect2>
</sect1>
</chapter>

15
neo/openal/docs/api-reference.html Normal file
View File

@@ -0,0 +1,15 @@
<html>
<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<title>OpenAL API Reference</title>
</head>
<body>
<h1>OpenAL API Reference</h1>
<p>
This document has been removed.
</p>
</body>
</html>

297
neo/openal/docs/app-annotations.sgml Normal file
View File

@@ -0,0 +1,297 @@
<appendix>
<title>Miscellaneous Annotations</title>
<section id="reverb-objects">
<title>Reverberation Objects?</title>
<para>
In a generalization of the I3DL2 Extension for
listener specific reverberation effects, it might
be best to implement Reverb Objects. A Reverb Object
is one example of a parametrized filter. Each
such object encapsulates a set of attributes (the
filter parameters). Sources and Listener alike
have an attribute that allows the application coder
to choose a reverb object for application either
at the origin of the sound, or at the position of
the listener. Initial implementation would only
support one Reverb Object per Context, applied at
the listener position.
</para>
<para>
The I3DL2 Environment is a filter that alters the
way the user experiences the virtual world. As
filters require DSP operations it is limited by hardware
processing capabilities.
</para>
<para>
The I3DL2 Environment models the surroundings of the
listener by simplifying the presumed acoustic properties
of those surroundings into a small set of parameters.
It allows to reproduce the effects of sound reflections
and reverberation caused by walls and obstacles, and
the muffling effects of obstacles inside environments
or partitions between environments.
</para>
<para>
Environment properties:
Early reflections level and delay.
Late reverberation level and delay, low- and high-frequency decay time.
Reverberation diffusion, density and spectrum.
</para>
<para>
Source properties:
Direct path intensity and spectrum.
Reverberation intensity and spectrum.
</para>
</section>
<section id="al-objects-filters">
<title>On Filters</title>
<para>
RFC/bk000502: Filters as the general concept of modifiers?
Environment as a special case filter?
Can we break down EAX environments into ReverbFilters where we
parametrize late reflections, and ReflectFilters, which fake
early reflections? Do we need this separation if we have
calculated or distinct echo effect reflections instead of
stocastic ones? Does it make sense to superimpose a general
reverb kicking in after a delay t, with reflections (random
or not) or should reverb only kick in after reflections are
discarded?
</para>
<para>
RFC/bk000502: old text.
(Environment) Properties:
Geometry - geometry is specified using an immediate mode API which is
similar to OpenGL. Support for scene lists are also provided on a basis
similar to OpenGL's display lists.
Materials - specify the absorptive and reflective qualities of a piece
of geometry. &AL; should provide a facility for accessing preset
materials, and storing and retrieving new materials at runtime.
</para>
<para>
RFC/nn: Atmospheric/ambient properties?
REF/nn: A3D 2.0 IA3dMaterial
</para>
<section id="al-objects-filters-atmospheric">
<title>Atmospheric Filter</title>
<para>
The atmospheric filter the effects of media with constant density,
on propagating sound waves. The effect of the atmospheric filter
is distance dependent. Atmospheric effects can be parameterized
by specifying attenuation per unit distance, the scale for the
unit distance, for one of a minimum of two frequency ranges
(low frequency and high frequency roll-off).
</para>
<para>
RFC/bk000502: do we specify the atmospheric filter per-source?
The effect is clearly dominated by the most dense medium, but
we have little chance simulating crossings between different
media this way. Distance attenuation in media clearly depends
on source and listener being embedded in the same medium,
without any obstruction along the LOS.
</para>
</section>
<section id="al-objects-filters-listenerreverb">
<title>Listener Reverb</title>
<para>
Listener Reverb is a parameterized filter that modifies the sound at
listener position to emulate effects of the surroundings, namely
effects of late reflections. Without simulating sound propagation
this reverb accounts for the averaged outcome of different arrangements
of reflecting/absorbing surfaces around the listener.
</para>
</section>
<section id="al-objects-filters-sourcereverb">
<title>Source Reverb</title>
<para>
There is currently no support for reverb at the source position.
</para>
</section>
<section id="al-objects-filters-reflection">
<title>Reflection Filter</title>
<para>
First order reflection (and, if support, O(n) reflection for small n)
can choose to simulate the effects of different materials by
parametrizing reflection filters.
There is currently no support for reflections.
</para>
</section>
<section id="al-objects-filters-transmission">
<title>Transmission Filter</title>
<para>
Sound propagation along the LOS can pass through obstructions
specified as convex polygons. The effects of lossy transmission
can be approximated by applying a once-off filtering. Like
atmospheric filters, this can be a frequency-dependent roll-off,
unlike atmospheric filters this does not take distance into
account. Transmission filters can be used to emulate losses
on crossing separating surfaces between different media (water/air
borders).
There is currently no support for transmissions.
</para>
</section>
</section>
<section>
<title>Parameterization over Time</title>
<para>
Fading and cross-fading. There are three ways to handle any kind
of gain control as a function of time:
<itemizedlist>
<listitem>
<para>
manipulate gain per frame/sufficiently often
</para>
</listitem>
<listitem>
<para>
parameterize, i.e. specify a target gain,
a duration over which to interpolate, and an interpolation function
</para>
</listitem>
<listitem>
<para>
provide an buffer that indicates amplitude, stretched over
a duration/by a frequency
</para>
</listitem>
The last mechanism also works for early reflections and echos,
and any other temporal filtering. The first and second approach
also work for attributes like Pitch.
</para>
</section>
<section>
<title>On Geometry</title>
<para>
Both the A3D API and implementation as well as EAX related utilities
like EAGLE seem to indicate that any effort to handle scene geoemtry
at API level will inevitably duplicate modules found in common game
engines for purposes of collision detection, path planning, AI
support, visibility and sound propagation culling.
</para>
<para>
In other words, any such effort will inevitably lead to competing
subsystems and multiple use of processing and memory resources to
implement the same functionality. While it makes sense to provide
templates, examples, and even utilities like EAGLE and SDK's to
developers, it makes no sense to integrate any such functionality
with the API.
</para>
<para>
The geometry based processing inevitably leads to a scene graph
API, with all the resulting problems. On closer examination it
seems that the specification and storage of source and listener
positions is a red herring.
</para>
<para>
Second and higher order reflections seem to be irrelevant.
</para>
<para>
Reflection can be faked by stochastic means, but an actual
presence/immersion effect will require smooth transitions
depending on the continuous change of distance between
sources, listener, and dominant reflectors.
</para>
<para>
Dominant reflectors are presumed to be 1st order,
with material properties that incur little or no loss
(or even provide amplification), and significant
surface area.
</para>
<para>
Transmission loss through dense media is equivalent to
the distance attenuation model.
</para>
<para>
Refraction/reflection loss at border surfaces separating
media....
</para>
<para>
No explicit geometry to check whether there is any indirect
(1st order reflection, multiple reflections) path between
source and listener - the application is usually better
equipped to handle this (portal states, PHS). The benefit
of forcing the AL implementation to check for obstruction
(object inersecting LOS) is questionable at best - LOS
checking is also better done by the main application.
In essence, the application might even handle the 1st
order reflections IFF we provide the means to generate
early reflection instead of rolling dice, and if we
make it cheap to enable a path between a source and
the listener complete with a material. Come to think of
it: the implementation guarantees n paths with m filters
one of which is transmission or reflection, one is
distance attenuation, one is source reverb, one is
listener reverb....
</para>
</section>
<section>
<title>No ALU</title>
<note id="bk000019-01"><title>RFC</title><para>
ALU, like GLU, is a problem: linkage dependencies, multiple drivers
sharing one ALU etc. It would be best to not clutter the specification
with ALU/ALUT. Any support code/template repository/SDK can be
maintained as a separate open source project.
</para></note>
<para>
ALU provides operations that do not affect driver or hardware state.
These can be resampling/conversion methods or other sample data
processing, or utilities for (optimized) filter generation. ALU
does not provide I/O operations. At this time,
ALU is not specified and not implemented.
</para>
<para>
RFC/bk000502: GLU is becoming a bit of a problem right now, with
most applications avoiding it as they load GL DLL's explicitely,
but do not trust the ABI specification enough to link against GLU,
and not bothering to load it. A vendor-neutral open source ALU
works for me, but we can not accept link time dependencies to AL.
ALU (like GLU) is meant for minimal convenience, in small
building blocks, it is not meant as an SDK.
</para>
<para>
RFC/bk000502: old text.
ALU is the AL Utility library, and provide functions for performing audio
conversion, preset material properties, and a compatability layer for
legacy stereo format audio. This includes support for panning and per
channel volume control.
</para>
<para>
RFC/nn: Er, what else does the world of 2D sound usually need?
</para>
</section>
<section>
<title>No ALUT</title>
<para>
Application coders frequently request additional support for sound
handling to the extent of sophisticated SDKs. It is expected that
SDK vendors will provide such products on top of AL. ALUT (in analogy
to GLUT) would constitute an "official" SDK if desired. At this time,
ALUT is not specified and not implemented, and not intended to be part
of &AL; proper.
</para>
<para>
ALUT is a utility toolkit for &AL;. It sits on top of ALC.
It provides convenience functions for accessing files, for playing sounds,
and an API for accessing CDROM functionality.
</para>
</section>
<!-- Driver DDK section
http://www.microsoft.com/directx/
http://www.microsoft.com/DDK/DDKdocs/win98ddk/ds-ddk_8eas.htm
-->
</appendix>

43
neo/openal/docs/app-constants.sgml Normal file
View File

@@ -0,0 +1,43 @@
<appendix>
<title>Global Constants</title>
<para>
<table>
<title>Misc. &AL; Global Constants</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>Name </>
<entry>&OAL; datatype </>
<entry>Description </>
<entry>Literal value </>
</row>
</thead>
<tbody>
<row>
<entry> ALenum </entry>
<entry> FALSE </entry>
<entry> boolean false </entry>
<entry> 0 </entry>
</row>
<row>
<entry> ALenum </entry>
<entry> TRUE </entry>
<entry> boolean true </entry>
<entry> 1 </entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<![ %RFC [
<note id="bk000621-01"><title>RFC</title><para>
NONE, ONE, ZERO needed?
</para></note>
]]>
</appendix>

36
neo/openal/docs/app-extensionprocess.sgml Normal file
View File

@@ -0,0 +1,36 @@
<appendix>
<title>Extension Process</title>
<para>
There are two ways to suggest an Extension to AL or ALC.
The simplest way is to write an ASCII text that matches
the following template:
<literallayout>
RFC: rfc-iiyymmdd-nn
Name: (indicating the purpose/feature)
Maintainer: (name and spam-secured e-mail)
Date: (last revision)
Revision: (last revision)
new enums
new functions
description of operation
</literallayout>
Such an RFC can be submitted on the &AL; discussion
list (please use RFC in the Subject line), or send to the
maintainer of the &AL; specification. If you are shipping
an actual implementation as a patch or as part of the
&AL; CVS a formal writeup is recommend. In this case,
the Extension has to be described as part of the
specification, which is maintained in DocBook SGML
(available for UNIX, Linux and Win32). The SGML source of
the specification is available by CVS, and the Appendix
on Extensions can be used as a template. Contact the
maintainer for details.
</para>
</appendix>

754
neo/openal/docs/app-extensions.sgml Normal file
View File

@@ -0,0 +1,754 @@
<appendix>
<title>Extensions</title>
<para>
Extensions are a way to provide for future expansion of the &AL; API.
Typically, extensions are specified and proposed by a vendor, and
can be treated as vendor neutral if no intellectual property
restrictions apply. Extensions can also be specified as, or
promoted to be, ARB extensions, which is usually the final step
before adding a tried and true extension to the core API. ARB
extensions, once specified, have mandatory presence for
backwards compatibility. The handling of vendors-specific or
multi-vendor extensions is left to the implementation. The IA-SIG
I3DL2 Extension is an example of multi-vender extensions to
the current &AL; core API.
</para>
<sect1>
<title>Extension Query</title>
<para>
To use an extension, the application will have to obtain function addresses
and enumeration values. Before an extension can be used, the application will
have to verify
the presence of an extension using IsExtensionPresent(). The application
can then retrieve the address (function pointer) of an extension entry
point using GetProcAddress. Extensions and entry points can be
Context-specific, and the application can not count on an Extension being available
based on the mere return of an entry point. The application also
has to maintain pointers on a per-Context basis.
<funcsynopsis>
<funcprototype>
<funcdef> &bool; <function>IsExtensionPresent</function></funcdef>
<paramdef> const &ubyte; * <parameter>extName</parameter></paramdef>
</funcprototype>
</funcsynopsis>
Returns TRUE if the given extension is supported for the current
context, FALSE otherwise.
</para>
<![ %Annote [
<note id="ann-bk000721-22"><title>Annotation (IsExtensionPresent)</title><para>
This function is inspired by the GLU addition, but placed in
the core API as we intend to avoid a separate ALU. This function
avoids potential string overflow and string parsing issues (strstr)
raised by GetString( EXTENSIONS ).
</para></note>
]]>
<![ %Annote [
<note><title>Annotation/ EXTENSIONS</title><para>
GetString( EXTENSIONS ) is supported as well, as it allows for
easy archiving and priting of the list of supported extensions.
</para></note>
]]>
</sect1>
<sect1>
<title>Retrieving Function Entry Addresses</title>
<para>
<funcsynopsis><funcprototype>
<funcdef> &void;* <function>GetProcAddress</function></funcdef>
<paramdef> const &ubyte; * <parameter>funcName</parameter></paramdef>
</funcprototype></funcsynopsis>
Returns NULL if no entry point with the name funcName can be found.
Implementations are free to return NULL if an entry point is present,
but not applicable for the current context. However the specification
does not guarantee this behavior.
</para>
<para>
Applications can use GetProcAddress to obtain core API entry points,
not just extensions. This is the recommended way to dynamically load
and unload &AL; DLL's as sound drivers.
</para>
<![ %RFC [
<note><title>RFC/bk000504:</title><para>
Original spec required all addresses are Context independent.
This matches the Linux &OGL; ABI specification, but imposes
additional implementation constraints. For now, the specification
does not guarantee this.
</para></note>
]]>
</sect1>
<sect1>
<title>Retrieving Enumeration Values</title>
<para>
To obtain enumeration values for extensions, the application has
to use GetEnumValue of an extension token. Enumeration values are
defined within the &AL; namespace and allocated according to
specification of the core API and the extensions, thus they are
context-independent.
<funcsynopsis><funcprototype>
<funcdef> &uint; <function> GetEnumValue </function></funcdef>
<paramdef> const &ubyte;<parameter> enumName </parameter></paramdef>
</funcprototype></funcsynopsis>
Returns 0 if the enumeration can not be found. The presence of an
enum value does not guarantee the applicability of an extension
to the current context. A non-zero return indicates merely that
the implementation is aware of the existence of this extension.
Implementations should not attempt to return 0 to indicate that
the extensions is not supported for the current context.
</para>
<![ %Annote [
<note><title>Annotation/ enums with value zero</title><para>
The literal value 0 is guaranteed for a number of AL
enums, such as FALSE, NONE, ZERO. As with GL applications
might employ sloppy use of this identity. It also means
that enums with zero value can not be queried through
GetEnumValue, a minor flaw given the constraints of
ABI backward compatibility. The recommended value to
compare GetEnumValue results with is NONE.
</para></note>
]]>
</sect1>
<sect1>
<title>Naming Conventions</title>
<para>
Extensions are required to use a postfix that separates the
extension namespace from the core API's namespace.
For example, an ARB-approved extension would use
"_ARB" with tokens (ALenum), and "ARB" with commands (function
names). A vendor specific extension uses a vendor-chosen
postfix, e.g. Loki Extensions use "_LOKI" and "LOKI",
respectively.
</para>
</sect1>
<sect1>
<title>ARB Extensions</title>
<para>
There are no ARB Extensions defined yet, as the ARB has
yet to be installed.
</para>
</sect1>
<![ %Ext1 [
<sect1>
<title>Other Extension</title>
<para>
For the time being this section
will list externally proposed extensions, namely
the extension based on the IASIG Level 2 guideline.
</para>
<sect2>
<title>IA-SIG I3DL2 Extension</title>
<para>
The IA-SIG I3DL2 guideline defines a set of parameters to control
the reverberation characteristics of the environment the listener
is located in, as well as filtering or muffling effects applied to
individual Sources (useful for simulating the effects of obstacles
and partitions). These features are supported by a vendor neutral
extension to &AL; (TBA).
The
<ulink
url="http://www.iasig.org/wg/3dwg/3dwg.htm"
type="http">IA-SIG 3D Level 2 rendering guideline</ulink>
provides related information.
</para>
<![ %Scratch [
<![ %RFC [
<note id="rfc-bk000626-07"><title>RFC: Global Attributes</title><para>
Do we need global setters for these:
DIRECT_IASIG/DIRECT_HIGH_FREQUENCY_IASIG?
ROOM_IASIG/ROOM_HIGH_FREQUENCY_IASIG?
</para></note>
]]>
<sect3>
<title>Listener Environment Attributes</title>
<para>
<table>
<title>ENV_ROOM Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_ROOM_EXT</>
<entry>f</>
<entry>[0.0, 1.0]</>
<entry> 1.0f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
</para>
<para>
<table>
<title>ENV_ROOM_HIGH_FREQUENCY Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_ROOM_HIGH_FREQUENCY_EXT</>
<entry>f</>
<entry>[0.0, 1.0]</>
<entry> 0.1f ???</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
</para>
<para>
<table>
<title>ENV_DECAY_TIME Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_DECAY_TIME_EXT</>
<entry>f</>
<entry>[0.1, 20.0]</>
<entry> 1.0f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>NV_DECAY_HIGH_FREQUENCY_RATIO Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_DECAY_HIGH_FREQUENCY_RATIO_EXT</>
<entry>f</>
<entry>[0.1, 2.0]</>
<entry> 0.5f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_REFLECTIONS Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_REFLECTIONS_EXT</>
<entry>f</>
<entry>[0.1, 3.0]</>
<entry> 1.0f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_REFLECTIONS_DELAY Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_REFLECTIONS_DELAY_EXT</>
<entry>f</>
<entry>[0.0, 0.3]</>
<entry> 0.02f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_REVERB Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_REVERB_EXT</>
<entry>f</>
<entry>[0.0, 10.0]</>
<entry> 1.0f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_REVERB_DELAY Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_REVERB_DELAY_EXT</>
<entry>f</>
<entry>[0.0, 0.1]</>
<entry> 0.04f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_DIFFUSION Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_DIFFUSION_EXT</>
<entry>f</>
<entry>[0.0, 100.0]</>
<entry> 100.0f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_DENSITY Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_DENSITY_EXT</>
<entry>f</>
<entry>[0.0, 100.0]</>
<entry> 100.0f</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
<para>
<table>
<title>ENV_HIGH_FREQUENCY_REFERENCE Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>ENV_HIGH_FREQUENCY_REFERENCE_EXT</>
<entry>f</>
<entry>[20.0, 20000.0]</>
<entry>5000.0</>
</row>
</tbody>
</tgroup>
</table>
Description: ???
What's up with the defaults? Not a normalized range
and a global Scale to set?
</para>
</sect3>
<sect3>
<title>Source Environment Attributes</title>
<para>
TBA.
</para>
</sect3>
]]>
</sect2>
</sect1>
]]> <!-- Environment -->
<![ %Ext2 [
<sect1>
<title>Compatibility Extensions</title>
<para>
The extensions described have at one point been in use for
experimental purposes, proof of concept, or short term needs.
They are preserved for backwards compatibility. Use is not
recommended, avialability not guaranteed. Most of these will
be officially dropped by the time API revision 2.0 is released.
</para>
<sect2>
<title>Loki Buffer InternalFormat Extension</title>
<para>
&AL; currently does not provide a separate processing
chain for multichannel data. To handle stereo samples,
the following alternative entry point to BufferData
has been defined.
<funcsynopsis><funcprototype>
<funcdef> &void; <function> BufferWriteData</function></funcdef>
<paramdef> &uint; <parameter>bufferName</parameter></paramdef>
<paramdef> &enum; <parameter>format</parameter></paramdef>
<paramdef> &void;* <parameter> data </parameter></paramdef>
<paramdef> &sizei; <parameter> size </parameter></paramdef>
<paramdef> &uint; <parameter>frequency</parameter></paramdef>
<paramdef> &enum; <parameter>internalFormat</parameter></paramdef>
</funcprototype></funcsynopsis>
Valid formats for internalFormat are FORMAT_MONO8, FORMAT_MONO16,
FORMAT_STEREO8, and FORMAT_STEREO16.
</para>
</sect2>
<sect2>
<title>Loki BufferAppendData Extension</title>
<para>
Experimental implementation to append data to an existing
buffer. Obsoleted by Buffer Queueing. TBA.
</para>
<![ %Annote [
<note><title>Annotation (GenStreamingBuffers):</title><para>
It is possible that a consistent implementation of this
extension will require distinguishing streaming from
regular buffers at creation time, instead of making
this distinction implied by the use of BufferData vs.
BufferAppendData.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk0000507-09"><title>RFC: alBufferAppendData</title><para>
Specify data to be filled into a streaming buffer.
This takes the current position at the time of the
call, and returns the number of samples written.
ALsizei ALAPIENTRY alBufferAppendData( ALuint buffer,
ALenum format,
ALvoid* data,
ALsizei size,
ALuint freq );
</para></note>
]]>
<![ %RFC [
<note id="rfc-briareaos0006XX-01"><title>RFC: GenStreamingBuffers</title><para>
Currently there is a function call on the Linux side,
alGenStreamingBuffers(), which generates a Buffer intended
for streaming. The intent of this function was the provide
a clear creation point for streaming buffers, rather than
the previous behaviour of a Buffer "magically" becoming
streaming Buffer the first time BufferAppendData() was
called on it. However, it's hard to believe this anomaly
in the API can be any better. What about
DelStreamingBuffers()? IsStreamingBuffer()?
</para><para>
The design problem here is that we handle qualitatively different
objects using the same API. Streaming and non-streaming buffers
are fundamentally different. If we create an API that makes it
easy to mistake one for the other, or worse, if we decide to
quietly convert one type of object into another in some cases,
we create a plethora of error cases for the implementation and
the app coder to catch. Separating the Factory methods for the
objects allows us to omit an specialization API that will
accidentally be called more than once, and saves us handling
different stages of "initialization state". AL should not have
any notion of "partially initialized" or "incomplete" objects:
misery and despair lie down that road. If necessary the entire
API should be duplicated (after all, nobody handles 1D, 2D, and
3D textures using the same GL API hooks), but as the AL
implementation has the ability to distinguish streaming and
non-streamin buffers internally there might not be a need.
Unless a concrete alternative is proposed to resolve the "anomaly"
it will be the preferred method to avoid an API that is
leaner at the expense of being more error-prone.
</para></note>
]]>
</sect2>
<sect2>
<title>Loki Decoding Callback Extension</title>
<para>
Experimental implementation to allow the application to
specify a decoding callback for compression formats
and codecs not supported by &AL;. This is supposed to
be used if full uncompression by the application is prohibited
by memory footprint, but streaming (by queueing) is not
desired as the compressed data can be kept in memory
in its entirety.
</para>
<para>
If mixing can be done from the compressed data directly,
several sources can use the sample without having to
be synchronized. For compression formats not supported
by AL, however, partial decompression has to be done by
the application. This extension allows for the implementation
to "pull" data, using apllication provided decompression
code.
</para>
<para>
The use of this callback by the &AL;
implementation makes sense only if late decompression
(incremerntal, on demand, as needed for mixing) is done,
as full early compression (ahead-of-time) inside the
implementation would exact a similar memory footprint.
</para>
<para>
TBA.
</para>
<para>
This extension forces execution of third party code
during (possibly threaded) driver operation, and
might also require state management with global
variables for decoder state, which raises issues
of thread safety and use for multiple buffers. This
extension should be obsolete as soon as &AL;
supports a reasonable set of state of the art
compression and encoding schemes.
</para>
</sect2>
<sect2>
<title>Loki Infinite Loop Extension</title>
<para>
To support infinite looping, a boolean LOOP was introduced.
With the introduction of buffer queueing and the request for
support for a limited number of repetitions, this mechanism
was redundant. This extension is not supported for
buffer queue operations, attempts to use it will cause
an ILLEGAL_OPERATION error. For backwards compatibility
it is supported as the equivalent to
<literallayout>
Source( sName, PLAY_COUNT, MAX_INTEGER )
</literallayout>
For the query LOOP==TRUE, the comparison
PLAY_COUNT!=MAX_INTEGER has to be executed on
the queue, not the current value which is decremented
for a PLAYING Source.
<table>
<title>Source LOOP_LOKI Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<colspec colname=c3>
<colspec colname=c4>
<spanspec spanname=hspan namest=c1 nameend=c4 align=left>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>LOOP_LOKI</>
<entry>b</>
<entry> &TRUE; &FALSE;</>
<entry> &FALSE; </>
</row>
</tbody>
</tgroup>
</table>
Description:
&TRUE; indicates that the Source will perform an inifinite
loop over the content of the current Buffer it refers to.
</para>
</sect2>
<sect2>
<title>Loki Byte Offset Extension</title>
<para>
The following has been obsoleted by explicit Source State query.
hack.
</para>
<para>
<table>
<title>Buffer BYTE Offset attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>BYTE_LOKI</>
<entry>ui</>
<entry> n/a </>
<entry> n/a </>
</row>
</tbody>
</tgroup>
</table>
Current byte for the buffer bound to the source interpreted
as an offset from the beginning of the buffer.
</para>
</sect2>
</sect1>
]]>
<![ %Ext2 [
<sect1>
<title>Loop Point Extension</title>
<para>
In external file now.
</para>
</sect1>
]]>
</appendix>

16
neo/openal/docs/architecture.html Normal file
View File

@@ -0,0 +1,16 @@
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>OpenAL Architecture</title>
</head>
<body>
<h1>OpenAL Architecture</h1>
<p>
This document has been removed.
See <a href="index.html">Index</a>
for the specification.
</p>
</body>
</html>

691
neo/openal/docs/chp-buffers.sgml Normal file
View File

@@ -0,0 +1,691 @@
<chapter id="buffers">
<title>Buffers</title>
<para>
A Buffer encapsulates &AL; state related to storing sample data. The
application can request and
release Buffer objects, and fill them with data. Data can be supplied
compressed and encoded as long as the format is supported.
Buffers can, internally, contain waveform data as uncompressed or
compressed samples.
</para>
<para>
Unlike Sources and Listener, Buffer Objects can be shared among AL contexts.
Buffers are referenced by Sources.
A single Buffer can be referred to by multiple Sources. This separation allows
drivers and hardware to optimize storage and processing where applicable.
</para>
<para>
The simplest supported format for buffer data is PCM.
</para>
<![ %Annote [
<note id="ann-bk000721-01"><title>Annotation/ Compressed Buffers</title><para>
Compressed formats are in no way guaranteed by the implementation
to remain compressed. The driver might have to uncompres in memory
at once, if no hardware-assisted or incremental decoding is possible.
In many cases an implementation has to decompress the buffer,
converting the uncompressed data to a canonical internal format,
and resample it into the format native to the current context.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000721-18"><title>RFC: Compressed Buffers</title><para>
MikeV suggests: an application can query the amount of memory buffer
is consuming. He suggests using GetBufferi(AL_SIZE, ... ). This seems
a bad idea as (a) the application is not meant to micromanage
driver-internal memory, (b) the memory requirements known to the
application might differ from the actual, (c) there are OS
mechanisms to query free memory, (d) AL_SIZE is now ambiguous as
it announces app-side memory as allocated vs. driver side memory
as used by the driver. For clarity AL_INTERNAL_SIZE (analog to
internal format enums) might be a better choice.
</para></note>
]]>
<![ %Scratch [
<para>
Buffers can be non-streaming (default) or streaming. Non-streaming
buffers are used to store looping and non-looping (single-shot) sound
data. Streaming buffers have to be used to cache streaming
media that the application can not keep in memory for technical
reasons: e.g. data delivered in real time over network. Streaming buffers
can also be used to partially store sound samples that the application
coder consider too large to keep in memory at once.
</para>
]]>
<sect1>
<title>Buffer States</title>
<para>
At this time, Buffer states are defined for purposes of discussion.
The states described in this section are not exposed through the API
(can not be queried, or be set directly), and the state description
used in the implementation might differ from this.
</para>
<para>
A Buffer is considered to be in one of the following States, with respect
to all Sources:
<itemizedlist>
<listitem>
<para>
UNUSED: the Buffer is not included in any queue
for any Source. In particular, the
Buffer is neither pending nor current
for any Source. The Buffer name can be
deleted at this time.
</para>
</listitem>
<listitem>
<para>
PROCESSED: the Buffer is listed in the queue of
at least one Source, but is neither pending
nor current for any Source. The Buffer can
be deleted as soon as it has been unqueued
for all Sources it is queued with.
</para>
</listitem>
<listitem>
<para>
PENDING: there is at least one Source for which the
Buffer has been queued, for which the Buffer
data has not yet been dereferenced. The Buffer
can only be unqueued for those Sources that
have dereferenced the data in the Buffer
in its entirety, and cannot be deleted or
changed.
</para>
</listitem>
</itemizedlist>
The Buffer state is dependent on the state of all Sources
that is has been queued for.
A single queue occurrence of a Buffer propagates the
Buffer state (over all Sources) from UNUSED to PROCESSED
or higher. Sources that are STOPPED or INITIAL still have
queue entries that cause Buffers to be PROCESSED.
</para>
<para>
A single queue entry
with a single Source for which the Buffer is not yet
PROCESSED propagates the buffer's queueing state to
PENDING.
</para>
<para>
Buffers that are PROCESSED for a given Source can be
unqueued from that Source's queue. Buffers that have
been unqueued from all Sources are UNUSED.
Buffers that are UNUSED can be deleted, or changed by
BufferData commands.
</para>
<![ %Annote [
<note><title>Annotation (No CURRENT State)</title><para>
For buffer queueing, it is not relevant whether
the Buffer data is currently dereferenced by any
Source or not. It is therefore not necessary to
distinguish a CURRENT state (being referenced as
current buffer by a single PLAYING or PAUSED Source).
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (State Query and Shared Buffers)</title><para>
A buffer that is unused by one Source might be used
by another. The Unqueue operation is determined by
the number of queue entries already processed by the
given Source.
However, the application has to check whether the
Buffer is still in use by other Sources. For now,
applications have to maintain their own lists of
buffer consumer (source) lists. If necessary, an
explicit call to determine current buffer state
with respect to all Sources might be added in
future revisions.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000927-02"><title>RFC: IsBufferProcessed? </title><para>
Instead of exposing the internal state, a simple boolean query
whether a buffer can be deleted or refilled can be used.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000731-04"><title>RFC: BufferData on QUEUED</title><para>
The error on using BufferData in QUEUED buffers is introduced
because the implementation might not be able to guarantee when
the Buffer is dereferenced. Applications have to account for the
possibility that the Buffer is dereferenced at the latest possible
moment, e.g. when it becomes CURRENT. As it is easier to relax
this restricition at a later time (no effect on backwards
compatibility) than doing the reverse, we are conserative here.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000731-05"><title>RFC: Buffer State Query</title><para>
Buffer State could be queried using alBuffer(), but it can't be
set. Prohibiting deferred deletion of buffers would make such a
state query desirable.
</para></note>
]]>
</sect1>
<sect1>
<title>Managing Buffer Names</title>
<para>
&AL; provides calls to obtain Buffer names, to request
deletion of a Buffer object associated with a valid Buffer name,
and to validate a Buffer name. Calls to control Buffer attributes
are also provided.
</para>
<sect2>
<title>Requesting Buffers Names</title>
<para>
The application requests a number of Buffers using GenBuffers.
<funcsynopsis><funcprototype>
<funcdef> void <function> GenBuffers </function></funcdef>
<paramdef> &sizei; <parameter> n </parameter></paramdef>
<paramdef> &uint;* <parameter> bufferNames </parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<![ %RFC [
<note id="rfc-bk000803-02"><title>RFC: Buffer Name 0</title><para>
NONE or 0 is a reserved buffer name. What properties does
this buffer have? Does it have content? If there is no content,
what is its duration? 0? 1 microsecond? Should we use this buffer
to schedule a limited duration "silence"?
</para></note>
]]>
</sect2>
<sect2>
<title>Releasing Buffer Names</title>
<para>
The application requests deletion of a number of Buffers
by calling DeleteBuffers.
</para>
<para>
Once deleted, Names are no longer valid for use with AL
function calls. Any such use will cause an INVALID_NAME
error. The implementation is free to defer actual
release of resources.
<funcsynopsis><funcprototype>
<funcdef> &void; <function> DeleteBuffers </function></funcdef>
<paramdef> &sizei; <parameter> n </parameter></paramdef>
<paramdef> &uint;* <parameter> bufferNames </parameter></paramdef>
</funcprototype></funcsynopsis>
IsBuffer(bname) can be used to verify deletion of a buffer.
Deleting bufferName 0 is a legal NOP in both scalar and
vector forms of the command. The same is true for unused
buffer names, e.g. such as not allocated yet, or as
released already.
</para>
<![ %RFC [
<note id="rfc-bk000803-01"><title>RFC: Force Deletion</title><para>
If a buffer name is deleted, we could replace all occurences
in queues with bname 0. This is the GL behavior for deleting
the texture currently bound.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000731-07"><title>RFC: Relasing used Buffers</title><para>
If a Buffer is USED or QUEUED, it cannot be deleted, and the operation
should fail. We have three possible responses: throw an error, deferr
deletion, or force deletion by replacing every use
of the buffer in question with bname zero.
Throwing an error requires that we lock, verify that all specified
buffers can be deleted, then perform deletion, then unlock. If there
is one buffer that can not be deleted we have to throw an error and
make the entire operation a NOP.
Deferred deletion has its own set of problems (see other RFC).
Forcing deletion makes the mistake obvious to the application
for current buffers (sound artifacts) but still doesn't expose
errors for queued buffers. It also requires complete consumer
book-keeping for each buffer. GL uses this approach for textures
at little expense because it only has one current texture.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000731-06"><title>RFC: Deferred Buffer Release</title><para>
Buffer deletion could be performed as a deferred operation.
In this case actual deletion would be deferred until a Buffer is
unused, i.e. not QUEUED or CURRENT anymore. The specification
would not guarantee that they are deleted as soon as possible.
However, such a deferred execution would be muddying the borders
between immediate and deferred execution in general (as we
might want to add scheduling and deferred commands at a later time).
Introduced as the default it makes impossible for the application
to force deletion or errors. Errors caused by improper use of
&AL; will be triggered at some distance from the original mistaken
command. Debugging such conditions is usually expensive. This approach
also does not take into account sharing of buffers among contexts.
It might be possible to introduce this behavior as a Hint()
in case that it is not desirable to explicitely introduce
deferred commands.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000927-03"><title>RFC: sourceName 0 </title><para>
Is there a useful application for this? Do we mark that this
is reserved?
</para></note>
]]>
</sect2>
<sect2>
<title>Validating a Buffer Name</title>
<para>
The application can verify whether a buffer Name is valid
using the IsBuffer query.
<funcsynopsis><funcprototype>
<funcdef> &bool; <function> IsBuffer </function></funcdef>
<paramdef> &uint; <parameter> bufferName</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
</sect2>
</sect1>
<sect1>
<title>Manipulating Buffer Attributes</title>
<sect2>
<title>Buffer Attributes</title>
<para>
This section lists the attributes that can be set, or
queried, per Buffer. Note that some of these attributes
can not be set using the Buffer commands, but are set
using commands like BufferData.
</para>
<para>
Querying the attributes of a Buffer with a buffer name that
is not valid throws an INVALID_OPERATION. Passing in an
attribute name that is invalid throws an INVALID_VALUE error.
</para>
<para>
<table>
<title>Buffer FREQUENCY Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry> FREQUENCY </>
<entry> float </>
<entry> none </>
<entry> (0, any]</>
</row>
</tbody>
</tgroup>
</table>
Description: Frequency, specified in samples per second,
i.e. units of Hertz [Hz].
Query by GetBuffer. The frequency state of a buffer is set by
BufferData calls.
</para>
<![ %Annote [
<note><title>Annotation (No Frequency enumeration)</title><para>
As the implementation has to support conversion from
one frequency to another to implement pitch, it is
feasible to offer support for arbitrary sample
frequencies, instead of restricting the application
to an enumeration of supported sample frequencies.
Another reason not to limit frequency to an enumerated
set is that future hardware might support variable
frequencies as well (it might be preferable to choose
the sampling frequency according to the PSD of the
signal then).
</para><para>
However, it is desirable to avoid conversions due
to differences between the sample frequency used in
the original data, the frequency supported during the
mixing, and the frequency expected by the output device.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Implied Frequency)</title><para>
To account for the possibility of future AL implementations
supporting encoding formats for the application might
not want, or be able, to retrieve the actual frequency
from the encoded sample, the specification will be
amended to guarantee the following behavior: If a nonzero
frequency is specified, it will force a conversion from
the actual to the requested frequency. If the application
specifies a 0 frequency, AL will use the actual frequency.
If there is no frequency information implied by the format
or contained in the encoded data, specifying a 0 frequency
will yield INVALID_VALUE. It is recommended that applications
use NONE instead of the literal value.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000806-01"><title>RFC: BITS not needed </title><para>
This is not a setter. As a state query it doesn't provide useful
information about the internal canonical format (which could be
queried independent of the buffer).
</para></note>
<para>
<table>
<title>Buffer BITS Attribute</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>BITS</>
<entry>ui</>
<entry>8,16</>
<entry>0</>
</row>
</tbody>
</tgroup>
</table>
Description:
Bits per sample. This is a query-only attribute. The
default value for an (empty) buffer is zero.
</para>
]]>
<![ %Annote [
<note><title>Annotation (No Format query)</title><para>
As of this time there is no query for FORMAT, or format
related state information. Query of the channels or
bits of a given buffer make little sense if the query
the internal (canonical, not buffer specific) format.
Query of the original sample data format makes little
sense unless the implementation is obliged to preserve
the original data.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000806-02"><title>RFC: CHANNELS needed?</title><para>
No setter. Does this indicate the channels in the original data,
or those in the (canonical) format internally used? Redundant to
querying the buffer type. Should be enums as speaker configurations
might have to be destribed by two integers: 5.1.
</para></note>
<para>
<table>
<title>Buffer CHANNELS Attribute</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val;</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>CHANNELS</>
<entry>ui</>
<entry>RFC: enums or N/A?</>
<entry>0</>
</row>
</tbody>
</tgroup>
</table>
Description: Channels that buffer stores. Query only
attribute. This is almost
always 1, as applications using spatialized sound always
downsample to mono. This depends on the purpose of the
buffer: buffers used for spatialization have to provide
single-channel data. The default value for an (empty)
buffer is zero.
</para>
]]>
<para>
<table>
<title>Buffer SIZE Attribute</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val;</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>SIZE</>
<entry> &sizei; </>
<entry> [0, MAX_UINT]</>
<entry> 0 </>
</row>
</tbody>
</tgroup>
</table>
Description: Size in bytes of the buffer data. Query through
GetBuffer, can be set only using BufferData calls.
Setting a SIZE of 0 is a legal NOP. The number of bytes does
not necessarily equal the number of samples (e.g. for compressed data).
</para>
<![ %RFC [
<note id="rfc-bk000724-15"><title>RFC: buffer overflow/underflow</title><para>
If a SIZE is specified for a buffer and an attempt is made to
write less or more data to the buffer, is this an error? Do we
have SubData updates? Is trying to write data to a zero size buffer
an error? Which error?
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000619-16"><title>RFC: query for samples/duration?</title><para>
Do we need a query for samples (which does not equal memory size)?
Do we prefer a duration query? As integral, for precision? Which,
combined with frequency, has to guarantee accurate sample number?
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000724-01"><title>RFC: memory budgeting</title><para>
SIZE comment said: Useful for memory budgeting with compressed data.
Sounds bogus: the application can only announce how many bytes
of data it intends to provide, it might not be able to estimate
the uncompressed, decoded size in the internal format chosen by
the implementation w/o decompressing, decoding, and querying for
the internal format. Micromanaging memory is usually a bad idea.
Using SIZE to configure a buffer might ge a mistake. Using the
same enum to query the actual size internally (which might
consists of two or more buffer areas and cached decoding state)
will be confusing.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000724-02"><title>RFC: buffer initial state</title><para>
MikeV added:
"The default attribute values for a Buffer are nonsensical insofar
as a Buffer is incomplete without data having been
specified."
This seems wrong. An AL object will always be complete and valid,
albeit useless. A Buffer in its default state might not produce
any useful outout, but it can be specified and used.
</para></note>
]]>
</sect2>
<sect2>
<title>Querying Buffer Attributes</title>
<para>
Buffer state is maintained inside the &AL; implementation and can be
queried in full. The valid values for paramName are identical to the
ones for Buffer*.
<funcsynopsis><funcprototype>
<funcdef> void <function> GetBuffer{n}{sifd}{v} </function></funcdef>
<paramdef> &uint; <parameter>bufferName</parameter></paramdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &type;* <parameter> values </parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
</sect2>
<sect2>
<title>Specifying Buffer Content</title>
<para>
A special case of Buffer state is the actual sound sample data stored
in asociation with the Buffer. Applications can specify sample data using
BufferData.
<funcsynopsis><funcprototype>
<funcdef> &void; <function> BufferData </function></funcdef>
<paramdef> &uint; <parameter>bufferName</parameter></paramdef>
<paramdef> &enum; <parameter>format</parameter></paramdef>
<paramdef> &void;* <parameter> data </parameter></paramdef>
<paramdef> &sizei; <parameter> size </parameter></paramdef>
<paramdef> &sizei; <parameter>frequency</parameter></paramdef>
</funcprototype></funcsynopsis>
The data specified is copied to an internal software, or if possible,
hardware buffer. The implementation is free to apply decompression,
conversion, resampling, and filtering as needed. The internal format
of the Buffer is not exposed to the application, and not
accessible. Valid formats are FORMAT_MONO8, FORMAT_MONO16,
FORMAT_STEREO8, and FORMAT_STEREO16. An implementation may
expose other formats, see the chapter on Extensions for
information on determining if additional formats are supported.
</para>
<para>
Applications should always check for an error condition after attempting
to specify buffer data in case an implementation has to generate an
OUT_OF_MEMORY or conversion related INVALID_VALUE error. The application
is free to reuse the memory specified by the data pointer once the
call to BufferData returns. The implementation has to dereference,
e.g. copy, the data during BufferData execution.
</para>
<![ %RFC [
<note id="rfc-bk000724-04"><title>RFC: format enums</title><para>
With the possible exception of sample frequency, all
details of a sample (mono/stero, bit resolution, channels,
encoding,compression) should be specified in a format parameter.
In other words, I opt for an enumeration of formats. GL has a
quite large number of those w/o suffering damage. Allowing
parameters the way we do increases error cases and/or
conversion load. The space is combinatorial to begin with,
but an enumeration of valid formats seems better to impose
restrictions. Using enums helps dealing with formats
opaque to the application (compressed data with compressed
header) where sample size and sampling frequency might not
be available.
There is the related issue of internal formats. A buffer used
for spatialization will have to convert to mono. A buffer used
to pass through to the output hardware will have to
remap an n-channel format to an m-channel format (or let the
hardware do it) including crosstalk handling depending on
the output device (headphones vs. speaker). To prevent that
every buffer has to do both AL needs to know the purpose of a
buffer when dereferencing the data.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk0000507-17"><title>RFC: Frequency woes</title><para>
Frequency as a uint rises precision issues.
Frequency might not be known for compressed data, we might need
a (yuck) wildcard frequency specifier?
We have a redundancy: frequency per context (mixing quality
desired), frequency internally used by the implementation when
storing the buffers, frequency provided in the data. We need
to specify the latter in some cases and can't in others. Format
enum or frequency enum again.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000504-01"><title>RFC: data mover mess</title><para>
API to copy data from output buffer to a buffer?
BufferWriteData to supersede BufferData, BufferReadData
as later extensions for buffer readback for those who want it?
Reading the output stream reverses the problems we have
with appendData: the application provides a memory buffer
into which AL copies as much data as available/as fits.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000724-11"><title>RFC: expose internal format</title><para>
Implementations are free to use whatever internal data format is best
suited for their hardware/software implementation, leaving the actual
sample format and structure opaque to the application. Should applications
be able to influence this? Through context creation? Per Buffer?
Do we use Lowest Common Denominator or highest possible quality as a
default?
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000724-12"><title>RFC: memory management with compressed data</title><para>
If we allow for mixing from compressed data (perfectly reasonable
for hardware) then it seems even more unlikely the application could
estimate memory usage.
If a compressed format is supported by AL, do we require support for mixing from
compressed data? I daresay not - some formats might not allow for
cheap incremental decompression.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000724-21"><title>RFC: conversion and sample retrieval</title><para>
To retrieve a sample, the size has to be queried first for allocating a
properly sized memory segment as destination. This is dependent on the
format. Conversion can be implemented as creating a buffer, and then
requesting the data in a different format. Is this desirable? Even if
we restrict reading from buffers to the same format they were written
to, conversion from the internal format might be inevitable. Querying
and setting the internal format however might be desirable for certain
purposes.
</para></note>
]]>
</sect2>
</sect1>
</chapter>

304
neo/openal/docs/chp-introduction.sgml Normal file
View File

@@ -0,0 +1,304 @@
<chapter id="introduction">
<title>Introduction</title>
<![ %Revision [
<para><literallayout>
CVS Document: $Id: chp-introduction.sgml,v 1.3 2000/11/10 21:23:52 bk Exp $
CVS Revision: $Revision: 1.3 $
$Log: chp-introduction.sgml,v $
Revision 1.3 2000/11/10 21:23:52 bk
Use ../CREDITS for list of contributors.
Revision 1.2 2000/10/26 02:58:55 bk
Cleanup (typos).
Revision 1.1 2000/10/11 18:44:46 bk
Document split into separate files. Minor fixes.
</literallayout><para>
]]>
<section>
<title>Formatting and Conventions</title>
<para>
This API Specification and Reference uses a style that is a blend of the
OpenGL v1.2 specification and the OpenGL Programming Guide, 2nd ed.
Conventions: 'T' is used to designate a type for those functions which
exist in multiple signatures for different types. 'Object' is used
to designate a target Object for those functions which exist in multiple
versions for different Object categories. The 'al' and 'AL_' prefix
is omitted throughout the document.
</para>
<![ %Annote [
<note><title>Annotation (Terminology)</title><para>
"State" refers to state within the context of the &OAL;
state machine description of the &OAL; implementation.
"Objects" refer to &OAL; primitives.
"Attribute" refers to attributes of &OAL; Objects.
Attributes of a &OAL; Objects are one part of the
&OAL; state. Some attributes are not specific to
single objects, but apply to the entire context.
"Parameter" is used for function arguments that might
or might not be attributes, in particular for
command arguments that are not stored as state.
The use of "Property" is to be avoided.
</para></note>
]]>
<para>
<revhistory>
<revision>
<revnumber> 1.8/1.7./1.6/1.5 </revnumber>
<date> September-August 2000 </date>
<authorinitials> bk </authorinitials>
<revremark> Final Draft for Public Review </revremark>
</revision>
<revision>
<revnumber> 1.4 </revnumber>
<date> June 2000 </date>
<authorinitials> bk </authorinitials>
<revremark> First Draft for Public Review </revremark>
</revision>
<revision>
<revnumber> 1.2 </revnumber>
<date> March 2000 </date>
<authorinitials> mkv </authorinitials>
<revremark> Draft released for GDC </revremark>
</revision>
</revhistory>
</para>
<![ %Scratch [
<note id="todo"><title>TODO</title><para>
<literallayout>
- work thru past changes
- add GH section
- add rewrite of GH section
- add section on rfc/ann id's
- add section on procedure
- add proper id's to rfc/ann/sections etc.
</literallayout>
</para></note>
]]>
</section>
<section>
<title>What is the &OAL; Audio System?</title>
<para>
&OAL; (for "Open Audio Library") is a software interface to audio hardware.
The interface consists of a number of functions that allow a programmer
to specify the objects and operations in producing high-quality audio
output, specifically multichannel output of 3D arrangements of sound
sources around a listener.
</para>
<para>
The &OAL; API is designed to be cross-platform and easy to use.
It resembles the &OGL; API in coding style and conventions. &OAL; uses a
syntax resembling that of &OGL; where applicable.
</para>
<para>
&OAL; is foremost a means to generate audio in a simulated three-dimensional
space. Consequently, legacy audio concepts such as panning and left/right
channels are not directly supported. &OAL; does include extensions compatible
with the IA-SIG 3D Level 1 and Level 2 rendering guidelines to handle
sound-source directivity and distance-related attenuation and Doppler effects,
as well as environmental effects such as reflection, obstruction, transmission,
reverberation.
</para>
<para>
Like &OGL;, the &OAL; core API has no notion of an explicit rendering context,
and operates on an implied current &OAL; Context. Unlike the &OGL;
specification the &OAL; specification includes both the core API (the
actual &OAL; API) and the operating system bindings
of the ALC API (the "Audio Library Context"). Unlike &OGL;'s GLX, WGL
and other OS-specific bindings, the ALC API is portable across platforms
as well.
</para>
</section>
<section>
<title>Programmer's View of &OAL;</title>
<para>
To the programmer, &OAL; is a set of commands that allow the
specification of sound sources and a listener in three
dimensions, combined with commands that control how these
sound sources are rendered into the output buffer. The
effect of &OAL; commands is not guaranteed to be immediate,
as there are latencies depending on the implementation,
but ideally such latency should not be noticeable to the
user.
</para>
<para>
A typical program that uses &OAL; begins with calls to
open a sound device which is used to process output and
play it on attached hardware (e.g. speakers or headphones).
Then, calls are made to allocate an AL context and
associate it with the device. Once an AL context is
allocated, the programmer is free to issue AL commands.
Some calls are used to render Sources (point and directional
Sources, looping or not), while others affect the rendering
of these Sources including how they are attenuated by
distance and relative orientation.
</para>
<![ %Annote [
<note><title>Annotation (&OAL; and &OGL; use)</title><para>
Often, &OAL; will be used to render a 3D audio environment
matched by a 3D visual scenery. For this purpose, &OAL; is
meant to be a seamlessly integrating complement to &OGL;.
&OAL; state can be updated in sync with the &OGL; or video
updates (synchronized), or in timesteps independent of the
graphics framerate. Audio rendering loops usually update
the current locations of the sources and the listener, updates
global settings, and manages buffers.
</para></note>
]]>
</section>
<section>
<title>Implementor's View of &OAL;</title>
<para>
To the implementor, &OAL; is a set of commands that affect
the operation of CPU and sound hardware. If the hardware
consists only of an addressable output buffer, then &OAL; must
be implemented almost entirely on the host CPU. In some cases
audio hardware provides DSP-based and other acceleration in
various degress. The &OAL; implementors task is to provide
the CPU software interface while dividing the work for each
AL command between the CPU and the audio hardware. This
division should be tailored to the available audio hardware
to obtain optimum performance in carrying out AL calls.
</para>
<para>
&OAL; maintains a considerable amount of state information.
This state controls how the Sources are rendered into the
output buffer. Some of this state is directly available to
the user: he or she can make calls to obtain its value.
Some of it, however, is visible only by the effect it has
on what is rendered. One of the main goals of this
specification is to make &OAL; state information explicit,
to eludicate how it changes, and to indicate what its
effects are.
</para>
<![ %Annote [
<note><title>Annotation (Native audio APIs)</title><para>
Implementors can choose to implement &OAL; on top
of an existing native audio API.
</para></note>
]]>
</section>
<section>
<title>Our View</title>
<para>
We view &OAL; as a state machine that controls a multichannel
processing system to synthesize a digital stream, passing sample
data through a chain of parametrized digital audio signal
processing operations. This model should engender a specification
that satisfies the needs of both programmers and implementors.
It does not, however, necessarily
provide a model for implementation. Any conformant implementation
must produce results conforming to those produced by the specified
methods, but there may be ways to carry out a particular computation
that are more efficient than the one specified.
</para>
</section>
<section>
<title>Requirements, Conformance and Extensions</title>
<para>
The specification has to guarantee a minimum number of resources.
However, implementations are encouraged to compete on performance,
available resources, and output quality.
</para>
<![ %RFC [
<note id="rfc-bk000724-06"><title>RFC: suggested requirements</title><para>
These have been taken from earlier specs drafts, suggested by
Creative:
A minimum of sixteen (16) Sources per Context should always be available.
The number and size of Buffers available is limited only by the amount
of memory available and/or accessible by the implementation.
The specification could also list requirements by the implementation:
A minimum storage space of half a megabyte (512kB) should always be available.
</para></note>
]]>
<![ %RFC [
<note id="rfc-briareos000724-01"><title>RFC: no requirements</title><para>
I3DL1-like requirements might be so arbitrary that they are useless.
The dangers here are cap bits, and a subtle aliasing of source and
hardware buffers. AL implementations should implement as much quality
and performance as possible for any given number of sources/
Application request resources when creating a context and can use Hints
to indicate desired trade-offs.
</para></note>
]]>
<para>
There will be an &OAL; set of conformance tests available along
with the open source sample implementation. Vendors and individuals
are encouraged to specify and implement extensions to &OAL; in
the same way &OGL; is extensible. Successful extensions will
become part of the core specification as necessary and desirable.
&OAL; implementations have to guarantee backwards compatibility
and ABI compatibility for minor revisions.
</para>
<para>
The current sample implementation and documentation for &OAL; can be
obtained from
<ulink
url="http://wwww.openal.org/"
type="http">openal.org</ulink>.
&OAL; is also available from the the
<ulink url="http://cvs.lokigames.com/cgi-bin/cvsweb.cgi/openal/" type="http">
&OAL; CVS repository</ulink>. For more information on how to get
&OAL; from CVS also see <ulink url="http://cvs.lokigames.com/" type="http">
&coLoki; CVS</ulink>.
</para>
</section>
<section>
<title>Architecture Review and Acknowledgements</title>
<para>
Like &OGL;, &OAL; is meant to evolve through a joined effort of
implementators and application programmers meeting in regular
sessions of an Architecture Review Board (ARB). As of this time
the ARB has not yet been set up. Currently, the two companies
committed to implementing &OAL; drivers have appointed two
contacts responsible for preparing the specification draft.
</para>
<para>
Consequently &OAL; is a cooperative effort, one in a sequence of
earlier attempts to create a cross-platform audio API. The current
authors/editors have assembled this draft of the specification,
but many have, directly and indirectly, contributed to the content
of the actual document. The following list (in all likelihood
incomplete) gives in alphabetical order participants in the discussion
and contributors to the specification processs and related efforts:
&CREDITS;
</para>
</section>
</chapter> <!-- Overview -->

261
neo/openal/docs/chp-multichannel.sgml Normal file
View File

@@ -0,0 +1,261 @@
<chapter id="multichannel">
<title>Handling Multichannel Data</title>
<para>
&AL; is foremost an API to control processing of spatialized sound. For that
reason, the internal, canonical format of data stored in buffers is mono.
The specification does not require the implementation to preserve the
original data, thus multichannel (e.g. stereo) data is usually downsampled
using an algorithm of the implementor's choosing. Implementations are free
to defer decompression, decoding, and conversion until the latest possible
moment, but they are not required to do so by the specification.
</para>
<para>
However, &AL; is an audio API, and consequently has to provide means to
pass through preprocessed multichannel data to the sound driver and
hardware, which in turn will map it to the actual output channels. This
processing might involve mapping from n channels in the data to m channels
in the output, as well as filtering to account for varying requirements
for a given setup. For example, headphone and speaker setups differ with
respect to handling of crosstalk and noise.
</para>
<para>
For this reason, mono buffers can not be used to store data meant for
direct multichannel output. The API has to provide means by which the
application can signal its intention to use a given buffer in this way,
causing the implementation to either preserve the original data, or
convert it as needed for the direct output to the given speaker or
headphone configuration. In many cases, multichannel buffers could be
used with Sources, but the specification does not endorse this at this
time as this might not be guaranteed for all multichannel data formats
&AL; will support.
</para>
<para>
While spatialized sound is often played once, or looping a limited number
of times, multichannel data is usually streaming: typically stereo or MP3
music, soundtracks, maybe voice data accompanying animation and cinematic
sequences. The queueing mechanism defined for mono buffers and spatialized
Sources is thus also applied to multichannel buffers and passthrough
output.
</para>
<para>
Applications can expect &AL; implementations to support more than one
multichannel output at once (e.g. mixing two stereo streams, or fading
from one to the other for transition). For that reason we can not restrict
multichannel output to just one stream or buffer at a time.
</para>
<![ %Annote [
<note><title>Annotation (per-case Buffer use)</title><para>
The specification will likely be amended at a later time to
allow for the use of mono buffers with multichannel output,
and multichannel buffers with spatialized Sources.
The decision to use the same buffer API for mono
and multichannel buffers was taken in anticipation of this.
In cases where the specification can not guarantee
use of a given multichannel data encoding with a
spatialized source, an error can be generated at the
attempted use, validating the buffer's internal format
against the output chosen. In cases were the specification
can not guarantee the implementation will defer the
conversion of multichannel buffer content as needed (e.g.
PCM stereo data), the application can either specify the
internal format, or the internal format enumeration
can be extended to explicitely request storage of both
multichannel and mono data within the same buffer, at memory
expense.
</para></note>
]]>
<section>
<title>Specifying Buffer Content and Internal Format</title>
<para>
The existing BufferData command does not permit the application
to specify an internal format. The implementation is free to
apply conversions, downsampling, upsampling, including
interpolation and filtering, in accordance with the specification.
</para>
<para>
However, applications might want to use different trade-offs
between quality and resource expenditure. More imortantly,
applications might choose to use preprocessed, multichannel
data instead of doing runtime spatialization, e.g. for
recorded music, voice, and realtime streams. In this case
the application expects efficient passthrough of the data
to the hardware.
</para>
<para>
To account for this requirement, an extended command to specify
sample data to be stored in a given buffer is introduced.
<funcsynopsis><funcprototype>
<funcdef> &void; <function> BufferWriteData</function></funcdef>
<paramdef> &uint; <parameter>bufferName</parameter></paramdef>
<paramdef> &enum; <parameter>format</parameter></paramdef>
<paramdef> &void;* <parameter> data </parameter></paramdef>
<paramdef> &sizei; <parameter> size </parameter></paramdef>
<paramdef> &uint; <parameter>frequency</parameter></paramdef>
<paramdef> &enum; <parameter>internalFormat</parameter></paramdef>
</funcprototype></funcsynopsis>
The internal format of the Buffer can be requested by the
application. The implementation is not required to match
the request excatly. The specification does guarantee that
use of a multichannel internalFormat parameter will cause
the implementation to treat the data as multichannel data.
The implementation is free to perform any remapping from
the number of channels used in the data to the number of
channels available at the output, and apply other prcessing
as needed.
</para>
<para>
Valid formats for internalFormat are FORMAT_MONO8, FORMAT_MONO16,
FORMAT_STEREO8, and FORMAT_STEREO16. An implementation may
expose other formats, see the chapter on Extensions for
information on determining if additional formats are supported.
In general, the set of valid internalFormat parameters will be
a subset of those available as format parameters.
</para>
<![ %Annote [
<note><title>Annotation (atomic WriteData)</title><para>
The internal format for a buffer can not be specified
by using Bufferi. The modular way to set state
is preferable for operations that are always, or
nearly legal and orthogonal, but specifying the
internal format affect allocation and use of a buffer,
and would cause too many error cases.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (change buffer format on write)</title><para>
The API allows for changing a buffer on every write operation,
turning a multichannel buffer into a mono buffer and vice versa.
The specification does not require the implementation to handle
these operations efficiently, as they might require reallocation
of memory. The same is true for resize operations at write.
Applications might prefer to release buffer names that do not
match current requirements, and request new buffer names instead,
an operation which implementations are encouraged to optimize.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (BufferReadData)</title><para>
The specification might be amended at a later time
with a command to retrieve the data from a buffer,
following use of alGetBuffer to retrieve size and
internalFormat. Reading has to be queued for
continuous reads from the actual mixing buffer.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000813-01"><title>RFC: frequency for write/read? </title><para>
Do we (ever) want to provide the application control over the internal frequency?
</para></note>
]]>
</section>
<section>
<title>Rendering Multichannel Buffers</title>
<para>
For a variety of reasons, Sources are not used to feed buffer
data into multichannel processing. Instead, a different class
of &AL; object is introduced to encapsulate state management
and resource management for multichannel output: Multichannel
objects.
</para>
<para>
Multichannel objects are referred to by name, and they
are managed by an API partly duplicating the Source API:
GenMultichannels, IsMultichannel, DeleteMultichannels,
Multichanneli and GetMultichanneli. However, the
SourcePlay/Stop commands as well as the Queue/Unqueue
commands can be applied to both: these commands accept
mcName parameters as well as sName parameters. It is
left to the implementation how a Name is mapped to an
object, and how the implementation dinstiguishes sNames
from mcNames. Within a 32bit namespace, and given the
small number of multichannel sources to expect (more than
one is quite possible, but not common), the implementation
can exploit the fact that Names are opaque to the
application.
</para>
<![ %Annote [
<note><title>Annotation (Source NONE)</title><para>
The literal value "0", i.e. NONE, is legal. All
operations on Source/Multichannel NONE are legal NOPs
and quietly ignored. Because of the ambiguity
(is NONE a Source or Multichannel) NONE will never
be available as an actual object, nor will operations
on it ever have effects.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (implicit ambient)</title><para>
One way to feed multichannel data into the rendering is
using the Listener as a Source (sname==0 implies
Listener). This was rejected, as it
does not allow for multiple streams. Using multiple
Sources with appropriate type SOURCE_AMBIENT or
SOURCE_MULTICHHANEL was rejected, as Sources
are by definition spatialized, and support operations
which are meaningless or even illegal for an output
that is not spatialized at all. Modifying the semantics
of Source spatialization by a provision that a relative
position of (0,0,0) would mark a Source as ambient was
rejected for clarity and cleanness. Updates of Source
position can not be expected to convert Sources from
spatialized to ambient and vice versa at any time,
a Source State dependent semantics of position updates
is outright confusing, handling of sources that are
SOURCE_ABSOLUTE but incidentally at listener position
can not be different from that of SOURCE_RELATIVE with
a zero offset. Furthermore, multichannel data is not
necessarily ambient (surround can rotate, while ambient
attempts to prevent any perception of direction).
Finally, multichannel processing might require per-channel
gain adjustment at user request, which is a meaningless
concept for Sources.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (no direct mixing)</title><para>
Direct mixing into the rendering buffer, allowing the
application to superimpose its multichannel data
(or custom software mixing results) on the audio stream
generated by spatialization was rejected, as it suffers
from similar problems as BufferAppendData and loop points,
namely the need to operate at sample level on buffers of
unknown format that might not even be directly accessible.
The same rationale that led to the adoption of maintaining
a processing queue for Sources applies to multichannel data.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (no combined Buffer/Passthrough)</title><para>
Multichannel buffers cannot serve as multichannel output
objects for two reasons: it would complicate the buffer
API with operations only applicable to a subset of buffers,
and it does not allow for queueing.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000813-02"><title>RFC: Per-Channel access</title><para>
At a later time we might want to amend the specification to
gain access to a single channel within a multichannel buffer.
I suggest that any such operation should be restricted to the
ability of reading samples from just one channel into application
memory, which allows for writing it into a mono buffer subsequently.
</para></note>
]]>
</section>
</chapter>

977
neo/openal/docs/chp-operation.sgml Normal file
View File

@@ -0,0 +1,977 @@
<chapter id="oal-operation">
<title>&OAL; Operation</title>
<sect1>
<title>&OAL; Fundamentals</title>
<para>
&OAL; (henceforth, the "&AL;") is concerned only with rendering audio
into an output buffer,
and primarily meant for spatialized audio.
There is no support for reading audio input from buffers at this
time, and no support for MIDI and other components usually
associated with audio hardware. Programmers must relay on other
mechanisms to obtain audio (e.g. voice) input or generate music.
</para>
<para>
The &AL; has three fundamental primitives or objects -- Buffers, Sources,
and a single Listener. Each object can be changed independently,
the setting of one object does not affect the setting of others.
The application can also set modes that affect processing. Modes
are set, objects specified, and other &AL; operations performed
by sending commands in the form of function or procedure calls.
</para><para>
Sources store locations, directions, and other attributes of an object in 3D
space and have a buffer associated with them for playback. There are
normally far more sources defined than buffers. When the program wants to play
a sound, it controls execution through a source object. Sources are
processed independently from each other.
</para><para>
Buffers store compressed or un-compressed audio data. It is common to
initialize a large set of buffers when the program first starts (or at
non-critical times during execution -- between levels in a game, for instance).
Buffers are referred to by Sources. Data (audio sample data) is associated
with buffers.
</para><para>
There is only one listener (per audio context). The listener attributes are
similar to source attributes, but are used to represent where the user is
hearing the audio from. The influence of all the sources from the
perspective of the listener is mixed and played for the user.
</para>
<![ %RFC [
<note id="rfc-bk000926-03"><title>RFC: Data Binding</title><para>
Have to specifiy when pointer arguments are dereferenced.
</para></note>
]]>
<sect2>
<title>Primitive Types</title>
<para>
As &AL; is meant to allow for seamless integration with &OGL; code
if needed, the &AL; primitive (scalar) data types mimic the
&OGL; data types. Guaranteed minimum sizes are stated for &OGL;
data types (see table 2.2 of the &OGL; 1.2 Specification), but
the actual choice of C datatype is left to the implementation.
All implementations on a given binary architecture, however, must
use a common definition of these datatypes.
</para>
<![ %RFC [
<note><title>RFC/000507:</title><para>
ALlong/ALulong are omitted from the Linux OpenGL Base ABI,
and the GL specification. Do we want to go ahead on this,
or trail GL? Do we include non-i386 architectures to list
sizes explicitely. I.e. do we make the ABI part of our
mandate?
</para></note>
]]>
<para>
Note that this table uses explicit AL prefixes for clarity,
while they might be omitted from the rest of the document
for brevity. GCC equivalents are given for IA32, i.e. a
portable and widely available compiler on the most common
target architecture.
<table>
<title>&AL; Primitive Data Types</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>AL Type</>
<entry>Description</>
<entry>GL Type</>
<entry>GCC IA32</entry>
</row>
</thead>
<tbody>
<row>
<entry> ALboolean </entry>
<entry> 8-bit boolean </entry>
<entry> GLboolean </entry>
<entry> unsigned char </entry>
</row>
<row>
<entry> ALbyte </entry>
<entry> signed 8-bit 2's-complement integer </entry>
<entry> GLbyte </entry>
<entry> signed char </entry>
</row>
<row >
<entry> ALubyte </entry>
<entry> unsigned 8-bit integer </entry>
<entry> GLubyte </entry>
<entry> unsigned char </entry>
</row>
<row>
<entry> ALshort </entry>
<entry> signed 16-bit 2's-complement integer </entry>
<entry> GLshort </entry>
<entry> short </entry>
</row
<row>
<entry> ALushort </entry>
<entry> unsigned 16-bit integer </entry>
<entry> GLushort </entry>
<entry> unsigned short </entry>
</row>
<row>
<entry> ALint </entry>
<entry> signed 32-bit 2's-complement integer </entry>
<entry> GLint </entry>
<entry> int </entry>
</row>
<row>
<entry> ALuint </entry>
<entry> unsigned 32-bit integer </entry>
<entry> GLuint </entry>
<entry> unsigned int </entry>
</row>
<![ %RFC [
<row>
<entry> ALlong </entry>
<entry> signed 64-bit 2's-complement integer </entry>
<entry> n/a </entry>
<entry> long long </entry>
</row>
<row>
<entry> ALulong </entry>
<entry> unsigned 64-bit integer </entry>
<entry> n/a </entry>
<entry> unsigned long long </entry>
</row>
]]>
<row>
<entry> ALsizei </entry>
<entry> non-negative 32-bit binary integer size </entry>
<entry> GLsizei </entry>
<entry> int </entry>
</row>
<row>
<entry> ALenum </entry>
<entry> enumerated 32-bit value </entry>
<entry> GLenum </entry>
<entry> unsigned int </entry>
</row>
<row>
<entry> ALbitfield </entry>
<entry> 32 bit bitfield </entry>
<entry> GLbitfield </entry>
<entry> unsigned int </entry>
</row>
<row>
<entry> ALfloat </entry>
<entry> 32-bit IEEE754 floating-point </entry>
<entry> GLfloat </entry>
<entry> float </entry>
</row>
<row>
<entry> ALclampf </entry>
<entry> Same as ALfloat, but in range [0, 1] </entry>
<entry> GLclampf </entry>
<entry> float </entry>
</row>
<row>
<entry> ALdouble </entry>
<entry> 64-bit IEEE754 floating-point </entry>
<entry> GLdouble </entry>
<entry> double </entry>
</row>
<row>
<entry> ALclampd </entry>
<entry> Same as ALdouble, but in range [0, 1] </entry>
<entry> GLclampd </entry>
<entry> double </entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<![ %Annote [
<note><title>Annotation on Type Sizes</title><para>
It would be desirable to guarantee the bit size of &AL; data
types, but this might affect the mapping to &OGL; types
for which the &OGL; specification only guarantees a minimum
size.
</para></note>
<note><title>Annotation on 64bit integral</title><para>
It would be desirable to define ulong and long, but again
we defer to &OGL; in this decision.
</para></note>
<note><title>Annotation on Enumeration</title><para>
&enum; is not a C or C++ enumeration, but implemented as
C preprocesor defines. This makes it easier to handle
extensions to the &AL; namespace, in particular in
dealing with delays in distributing updated reference
headers.
</para></note>
]]>
</sect2>
<sect2>
<title>Floating-Point Computation</title>
<para>
Any representable floating-point value is legal as input
to a &AL; command that requires floating point data.
The result of providing a value that is not a floating
point number to such a command is unspecified, but must not
lead to &AL; interruption or termination. In IEEE arithmetic,
for example, providing a negative zero or a denormalized
number to a GL command yields predictable results, while
providing an NaN or infinity yields unspecified results.
</para><para>
Some calculations require division. In such cases (including
implied divisions required by vector normalizations), a
division by zero produces an unspecified result but must
not lead to GL interruption or termination.
</para>
</sect2>
</sect1>
<sect1>
<title>AL State</title>
<para>
The &AL; maintains considerable state. This documents enumerates
each state variable and describes how each variable can be
changed. For purposes of discussion, state variables are
categorized somewhat arbitrarily by their function. For example,
although we describe operations that the &AL; performs on the
implied output buffer, the outbut buffer is not part of the
&AL; state. Certain states of &AL; objects (e.g. buffer states
with respect to queueing) are introduced for discussion purposes,
but not exposed through the API.
</para>
</sect1>
<sect1>
<title>AL Command Syntax</title>
<para>
&AL; commands are functions or procedures. Various groups of
commands perform the same operation but differ in how
arguments are supplied to them. To conveniently accomodate
this variation, we adopt the &OGL; nnotation for describing
commands and their arguments.
</para>
<![ %Annote [
<note><title>Annotation (Not all types supported yet)</title><para>
At this time &AL; does not support the full flexibility that
&OGL; offers. Certain entry points are supported only for
some data types. In general, &AL; tends to use less entry
points, using setter commands that use the same tokens
as the matching query commands.
</para></note>
]]>
</sect1>
<sect1>
<title>Basic AL Operation</title>
<para>
&AL; can be used for a variety of audio playback tasks, and is an
excellent complement to &OGL; for real-time rendering. A programmer who is
familiar with &OGL; will immediately notice the similarities between the
two APIs in that they describe their 3D environments using similar methods.
</para>
<para>
For an &OGL;/&AL; program, most of the audio programming will be in two
places in the code: initialization of the program, and the rendering loop.
An &OGL;/&AL; program will typically contain a section where the graphics and
audio systems are initialized, although it may be spread into multiple functions.
For OpenAL, initialization normally consists of creating a context, creating
the initial set of buffers, loading the buffers with sample data, creating
sources, attaching buffers to sources, setting locations and directions for
the listener and sources, and setting the initial values for state global
to &AL;.
</para>
<example>
<title>Initialization Example</title>
<para>
&sample.c;
</para>
<programlisting>
</programlisting>
</example>
<![ %Example [
<example>
<title>Initialization Example</title>
<programlisting>
&ExInitAL.c;
</programlisting>
</example>
]]>
<para>
The audio update within
the rendering loop normally consists of telling &AL; the current locations
of the sources and listener, updating the environment settings, and managing
buffers.
</para>
<![ %Example [
<example>
<title>Processing Loop</title>
<programlisting>
// PlaceCamera -- places OpenGL camera and updates OpenAL listener position and source state
void 3DEnvironemnt:PlaceCamera()
{
// update OpenGL camera position
glMatrixMode(GL_PROJECTION);
glLoadIdentity();
glFrustum(-0.1333, 0.1333, -0.1, 0.1, 0.2, 50.0);
gluLookAt(listenerPos[0], listenerPos[1], listenerPos[2],
(listenerPos[0] + sin(listenerAngle)), listenerPos[1], (listenerPos[2] - cos(listenerAngle)),
0.0, 1.0, 0.0);
// OpenAL stuff...
// place listener at camera
alListener3f(AL_POSITION, listenerPos[0], listenerPos[1], listenerPos[2]);
float directionvect[6];
directionvect[0] = (float) sin(listenerAngle);
directionvect[1] = 0;
directionvect[2] = (float) cos(listenerAngle);
directionvect[3] = 0;
directionvect[4] = 1;
directionvect[5] = 0;
alListenerfv(AL_ORIENTATION, directionvect);
// play phasor if in range, else stop playback
if (range() < 9)
{
alSourcePlay(source[1]);
} else
{
alSourceStop(source[1]);
}
}
</programlisting>
</example>
]]>
</sect1>
<sect1 id="errors">
<title>AL Errors</title>
<para>
The AL detects only a subset of those conditions that could be
considered errors. This is because in many cases error checking
would adversely impact the performance of an error-free program.
The command
<funcsynopsis><funcprototype>
<funcdef> &enum; <function> GetError </function></funcdef>
<void>
</funcprototype></funcsynopsis>
is used to obtain error information. Each detectable error is
assigned a numeric code. When an error is detected by AL,
a flag is set and the error code is recorded. Further errors,
if they occur, do not affect this recorded code. When GetError
is called, the code is returned and the flag is cleared, so that
a further error will again record its code. If a call to GetError
returns NO_ERROR then there has been no detectable error since
the last call to GetError (or since the AL was initialized).
</para>
<![ %RFC [
<note id="rfc-bk000926-04"><title>RFC: GL distributed error </title><para>
To allow for distributed implementations there may be several
flag/code pairs. In this case, after a call to GetError returns a
value other than NO_ERROR each subsequent call returns the
non-NO_ERROR code of another distinct flag-code pair (in
unspecified order), until all NO_ERROR codes have been returned.
When there are no more non-NO_ERROR codes, all flags be reset.
The initial state of all flags is cleared and the initial value
of all codes is NO_ERROR.
</para></note>
<note><title>Annotation (Looping GetError)</title><para>
&AL; applications are advised to loop calls of GetError to
make sure that all flags are reset. Only the first error
occurence for each flag/code pair is recorded, subsequent
errors are ignored. The result of a repeated GetError call
is not a stack trace or LIFO sequence. All error handling
is context specific.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Only First Error)</title><para>
Like &OGL; &AL; will ignore subsequent errors once an
error conditation has been encountered.
</para></note>
]]>
<para>
Error codes can be mapped to strings. The GetString function
returns a pointer to a constant (literal) string that is
identical to the identifier used for the enumeration value,
as defined in the specification.
</para>
<![ %Annote [
<note><title>Annotation/ Verbose Error String</title><para>
There is no need to maintain a separate GetErrorString
function (inspired by the proposed gluGetErrorStrings)
as the existing GetString entry point can be used.
</para></note>
]]>
<para>
<table>
<title>Error Conditions</title>
<tgroup cols="2" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<thead>
<row>
<entry>Name</>
<entry>Description</>
</row>
</thead>
<tbody>
<row>
<entry>NO_ERROR</>
<entry>"No Error" token.</>
</row>
<row>
<entry>INVALID_NAME</>
<entry>Invalid Name parameter.</>
</row>
<row>
<entry>INVALID_ENUM</>
<entry>Invalid parameter.</>
</row>
<row>
<entry>INVALID_VALUE</>
<entry>Invalid enum parameter value.</>
</row>
<row>
<entry>INVALID_OPERATION</>
<entry>Illegal call.</>
</row>
<row>
<entry>OUT_OF_MEMORY</>
<entry>Unable to allocate memory.</>
</row>
</tbody>
</tgroup>
</table>
The table summarizes the AL errors. Currently, when an error flag
is set, results of AL operations are undefined only if OUT_OF_MEMORY
has occured. In other cases, the command generating the error is
ignored so that it has no effect on AL state or output buffer
contents. If the error generating command returns a value,
it returns zero. If the generating command modifies values
through a pointer argument, no change is made to these values.
These error semantics apply only to AL errors, not to system errors
such as memory access errors.
</para>
<para>
Several error generation conditions are implicit in the description
of the various AL commands. First, if a command that requires
an enumerated value is passed a value that is not one of those
specified as allowable for that command, the error INVALID_ENUM
results. This is the case even if the argument is a pointer to
a symbolic constant if that value is not allowable for the given
command.
This will occur whether the value is allowable for other functions,
or an invalid integer value.
</para>
<para>
Integer parameters that are used as names for &AL; objects
such as Buffers and Sources are checked for validity. If an invalid
name parameter is specified in an &AL; command, an
INVALID_NAME error will be generated, and the command is ignored.
</para>
<para>
If a negative integer is provided where an argument of type
&sizei; is specified, the error INVALID_VALUE results. The same
error will result from attempts to set integral and floating
point values for attributes exceeding the legal range for
these. The specification does not guarantee that the implementation
emits INVALID_VALUE if a &NaN; or &Infty; value is
passed in for a &float; or &double; argument (as the specification
does not enforce possibly expensive testing of floating point
values).
</para>
<para>
Commands can be invalid. For example, certain commands might not be
applicable to a given object. There are also illegal combinations
of tokens and values as arguments to a command. &AL; responds to any
such illegal command with an INVALID_OPERATION error.
</para>
<![ %Scratch [
<para>
No longer true except for extensions. To be avoided
in general: &AL; has
mutually exclusive commands operating on similar objects.
One example is treating a streaming buffer as a
non-streaming buffer, another is appending data to a
non-streaming buffer.
</para>
]]>
<para>
If memory is exhausted as a side effect of the execution of an
AL command, either on system level or by exhausting the allocated
resources at AL's internal disposal, the error OUT_OF_MEMORY
may be generated. This can also happen independent of recent
commands if &AL; has to request memory for an internal task
and fails to allocate the required memory from the operating
system.
</para>
<para>
Otherwise errors are generated only for conditions that are
explicitely described in this specification.
</para>
<![ %RFC [
<note id="rfc-bk000807-01"><title>RFC: INVALID_SIZE?</title><para>
Specific error case in which the size argument is
negative, or mismatches internal conditions for a getter?
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000802-03"><title>RFC: INVALID_POINTER?</title><para>
GL seemingly does not specify a response to NULL pointer
destinations, and does not assign an error case. INVALID_VALUE
could be used, also we could introduce a separate INVALID_POINTER.
Is there a good reason not to catch these cases?
</para></note>
]]>
</sect1>
<sect1 id="control">
<title>Controlling AL Execution</title>
<para>
The application can temporarily disable certain AL capabilities
on a per Context basis. This allows the driver implementation
to optimize for certain subsets of operations.
Enabling and disabling capabilities is handled using a function
pair.
<funcsynopsis><funcprototype>
<funcdef> &void; <function> Enable </function></funcdef>
<paramdef> &enum; <parameter> target </parameter></paramdef>
</funcprototype></funcsynopsis>
<funcsynopsis><funcprototype>
<funcdef> &void; <function> Disable </function></funcdef>
<paramdef> &enum; <parameter> target </parameter></paramdef>
</funcprototype></funcsynopsis>
The application can also query whether a given capability is
currently enabled or not.
<funcsynopsis><funcprototype>
<funcdef> &bool; <function> IsEnabled </function></funcdef>
<paramdef> &enum; <parameter> target </parameter></paramdef>
</funcprototype></funcsynopsis>
If the token used to specify target is not legal,
an INVALID_ENUM error will be generated.
</para>
<para>
At this time, this mechanism is not used. There are no valid
targets.
</para>
<![ %Annote [
<note><title>Annotation (Enable/Disable)</title><para>
Currently, &AL; is controlled exploiting existing
commands. For example, to disable sound output but
not processing, the Listener can be muted setting
GAIN to zero. Selecting NONE as the distance model
disables distance attenuation. Setting DOPPLER_FACTOR
to zero disables the Doppler Effect. A redundant
mechanism to accomplish the same is not needed.
</para></note>
]]>
</sect1>
<sect1 id="objects">
<title>Object Paradigm</title>
<para>
&AL; is an object-oriented API, but it does not expose classes, structs,
or other explicit data structures to the application.
</para>
<sect2 id="object-overview-categories">
<title>Object Categories</title>
<para>
&AL; has three primary categories of Objects:
<itemizedlist>
<listitem>
<para>
one unique Listener per Context
</para>
</listitem>
<listitem>
<para>
multiple Buffers shared among Contexts
</para>
</listitem>
<listitem>
<para>
multiple Sources, each local to a Context
</para>
</listitem>
</itemizedlist>
In the following, "{Object}" will stand for either Source,
Listener, or Buffer.
</para>
</sect2>
<sect2 id="object-overview-dynamic">
<title>Static vs. Dynamic Objects</title>
<para>
The vast majority of &AL; objects are dynamic, and will be created
on application demand. There are also &AL; objects that do not have
to be created, and can not be created, on application demand.
Currently, the Listener is the only such static object in &AL;.
</para>
</sect2>
<sect2>
<title>Object Names</title>
<para>
Dynamic Objects are manipulated using an integer, which in
analogy to &OGL; is referred to as the object's "name". These
are of type unsigned integer (uint). Names can be valid
beyond the lifetime of the context they were requested
if the objects in question can be shared among contexts.
No guarantees or assumptions are
made in the specification about the precise values or their distribution
over the lifetime of the application. As objects might be shared,
Names are guaranteed to be
unique within a class of &AL; objects, but no guarantees are made
across different classes of objects. Objects that are unique
(singletons), like the Listener, do not require and do not have
an integer "name".
</para>
</sect2>
<sect2>
<title>Requesting Object Names</title>
<para>
&AL; provides calls to obtain Object Names. The application requests
a number of Objects of a given category using Gen{Object}s.
If the number n of Objects requested is negative,
an INVALID_VALUE error will caused. The actual values of the
Names returned are implementation dependent. No guarantees on
range or value are made. Unlike &OGL; &OAL does not offer alternative
means to define (bind) a Name.
</para>
<para>
Allocation of Object Names does not imply immediate allocation of
resources or creation of Objects: the implementation is free to
defer this until a given Object is actually used in mutator calls.
The Names are written at the memory location specified by the caller.
<funcsynopsis><funcprototype>
<funcdef> void <function> Gen{Object}s </function></funcdef>
<paramdef> &sizei; <parameter> n </parameter></paramdef>
<paramdef> &uint;* <parameter> objectNames </parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>
Requesting zero names is a legal NOP. Requesting a negative
number of names causes an INVALID_VALUE error.
&AL; will respond with an OUT_OF_MEMORY if the application
requests too many objects. The specification does not guarantee
that the &AL; implementation will allocate all resources
needed for the actual objects at the time the names are
reserved. In many cases (Buffers) this could only be
implemented by worst case estimation. Allocation of names
does not guarantee that all the named objects can actually
be used.
</para>
<![ %Scratch [
<note><para>
We do not re-use Names under any circumstance. Do we require
implementations throwing OUT_OF_MERMORY errors on allocation of
Names? No - we don't even specify buffer sizes. Ambiguity - could
an implementation throw OOM because of no names, or OOM because
of a (worst case) estimate of object sizes? Do we need OUT_OF_NAMES?
</para></note>
]]>
<![ %Scratch [
<warning><para>
The current headers include a sizei return parameter:
"Returns the number of ids actually allocated."
This violates the "failed commands are NOPs" design
and introduces ambiguity in error handling, and has
thus been changed breaking backwards compatibility.
</para></warning>
]]>
<![ %Annote [
<note><title>Annotation (No application selected Names)</title><para>
Unlike GL, applications are not free to choose Names; all
Names have to be requested. Aside from possible benefits for
the implementation, and avoidance of errors in projects
that have many modules using the AL implementation (a problem
encountered in GL, when the two generation mechanisms are
mixed), this also leaves open the door to feed different
kinds of objects by Name through the same API entry points.
</para></note>
]]>
<![ %Annote [
<note><title>Annotate (Negative/zero sizei)</title><para>
The specification does not guarantee that sizei is an
unsigned integer, but legal values have to be non-negative.
However, requesting zero names is a legal NOP.
</para></note>
]]>
<![ %RFC [
<note id=rfc-bk000626-02><title>RFC: Resource Release Hint</title><para>
Do we need a hint that resource release has to be done on DeleteXXX,
instead of leaving this housekeeping to &AL;?
</para></note>
<note id=rfc-bk000626-03><title>RFC: Zero Name</title><para>
Do we reserve the name "0"? &OGL; provides an alternative mechanism
which lets the application pick texture names, which we discarded
because it is prone to create error conditions when mixing both
approaches. As all our names are generated using GenXXXX, there
is no real need to treat "0" special.
</para></note>
]]>
</sect2>
<sect2>
<title>Releasing Object Names</title>
<para>
&AL; provides calls to the application to release Object Names
using Delete{Object}s, implicitly requesting deletion of the
Objects associated with the Names released. If the number n of Objects named
is negative, an INVALID_VALUE error will be caused.
If one or more of the specified Names is not valid, an INVALID_NAME
error will be caused. Implementation behavior following any error
is undefined.
</para>
<para>
Once deleted (even if an error occured on deletion), the Names are
no longer valid for use with any &AL; function calls including
calls to Delete{Objects}s. Any such use will cause an INVALID_NAME
error.
</para>
<para>
The &AL; implementation is free to defer actual release of
resources. Ideally, resources should be released as soon as
possible, but no guarantees are made.
<funcsynopsis><funcprototype>
<funcdef>&void;<function>Delete{Object}s</function></funcdef>
<paramdef>&sizei;<parameter>n</parameter></paramdef>
<paramdef>&uint;*<parameter>objectNames</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<![ %Annote [
<note><title>Annotation</title><para>
GenXXX and DeleteXXX can not reasonably be expected to be used
for controlling driver-side resource management from the
application. A driver might never release a Source once allocated
during the lifetime of the application.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000724-18"><title>RFC: Deletion Errors</title><para>
chasan@acm.org:
What happens if an active source (or its associated buffer) is deleted?
The source should be stopped? Or the delete operation is invalid?
</para></note>
]]>
</sect2>
<sect2>
<title>Validating an Object Name</title>
<para>
&AL; provides calls to validate the Name of an Object.
The application can verify whether an Object Name is valid
using the Is{Object} query. There is no vector (array)
version of this function as it defeats the purpose of
unambiguous (in)valdiation. Returns &TRUE; if id is a
valid Object Name, and &FALSE; otherwise. Object Names are
valid between request (Gen{Object}s) and release (Delete{Object}s).
Is{Object} does not distinguish between invalid and deleted Names.
<funcsynopsis><funcprototype>
<funcdef>&bool;<function>Is{Object}</function></funcdef>
<paramdef>&uint;<parameter>objectName</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<![ %RFC [
<note><title>RFC/bk000504:</title><para>
If zero is a valid name, this function will have to accept
it without an actyual object (or only an internal dummy)
being associated with it. I recommend that implementations
never return "0" as an object name.
</para></note>
]]>
</sect2>
<sect2>
<title>Setting Object Attributes</title>
<para>
For &AL; Objects, calls to control their attributes are provided.
These depend on the actual properties of a given Object
Category. The precise API is discussed for each category,
below. Each &AL; command affecting the state of
a named Object is usually of the form
<funcsynopsis><funcprototype>
<funcdef> void <function> {Object}{n}{sifd}{v} </function></funcdef>
<paramdef> &uint; <parameter> objectName </parameter></paramdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &type; <parameter> values </parameter></paramdef>
</funcprototype></funcsynopsis>
In the case of unnamed (unique) Objects, the (integer) objectName
is omitted, as it is implied by the {Object} part of function name:
<funcsynopsis><funcprototype>
<funcdef> void <function> {Object}{n}{sifd}{v} </function></funcdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &type; <parameter> values </parameter></paramdef>
</funcprototype></funcsynopsis>
For example, the Listener3d command would not require an (integer)
objectName argument.
</para>
<para>
The objectName specifies the &AL; object affected by this call.
Use of an invalid Name will cause an INVALID_NAME error.
</para>
<para>
The Object's Attribute to be affected has to be named
as paramName. &AL; parameters applicable to one category
of Objects are not necessarily legal for another catetgory
of &AL; Objects. Specification of a parameter illegal for
a given object will cause an INVALID_OPERATION error.
</para>
<para>
Not all possible values for a type will be legal for a
given objectName and parameterName. Use of an illegal value
or a NULL value pointer will cause an INVALID_VALUE error.
</para>
<para>
Any command that causes an error is a NOP.
</para>
</sect2>
<sect2>
<title>Querying Object Attributes</title>
<para>
For named and for unique &AL; Objects, calls to query their
current attributes are provided.
These depend on the actual properties of a given Object
Category. The performance of such queries is implementation
dependent, no performance guarantees are made. The valid values for the
parameter paramName are identical to the ones legal for the complementing
attribute setting function.
<funcsynopsis><funcprototype>
<funcdef> void <function> Get{Object}{n}{sifd}{v} </function></funcdef>
<paramdef> &uint; <parameter> objectName </parameter></paramdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &type;* <parameter> destination </parameter></paramdef>
</funcprototype></funcsynopsis>
For unnamed unique Objects, the objectName is omitted as it is
implied by the function name:
<funcsynopsis><funcprototype>
<funcdef> void <function> Get{Object}{n}{sifd}{v} </function></funcdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &type;* <parameter> destination </parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>
The precise API is discussed for each category separately, below.
Unlike their matching mutators, Query functions for non-scalar
properties (vectors etc.) are only available in array form.
</para>
<para>
Use of an invalid Name will cause an INVALID_NAME error.
Specification of an illegal parameter type (token) will cause
an INVALID_ENUM error. A call with a destination
NULL pointer will be quietly ignored. The &AL; state will not
be affected by errors. In case of errors, destination memory
will not be changed.
</para>
</sect2>
<sect2>
<title>Object Attributes</title>
<para>
Attributes affecting the processing of sounds can be set for various
&AL; Object categories, or might change as an effect of &AL; calls.
The vast majority of these Object properties are specific to the
&AL; Object category, in question, but some are applicable to two
or more categories, and are listed separately.
</para>
<para>
The general form in which this document describes parameters is
<table>
<title>{Object} Parameters</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<colspec colname=c1>
<colspec colname=c2>
<colspec colname=c3>
<colspec colname=c4>
<thead>
<row>
<entry>&Par;</>
<entry>&Sig;</>
<entry>&Val</>
<entry>&Def;</>
</row>
</thead>
<tbody>
<row>
<entry>paramName</>
<entry>T</>
<entry> range or set </>
<entry> scalar or n-tuple </>
</row>
</tbody>
</tgroup>
</table>
Description:
The description specifies additional restrictions and details.
paramName is given as the &AL; enum defined as its name.
T can be a list of legal signatures, usually the array form
as well as the flat (unfolded) form.
</para>
<![ %RFC [
<note id="rfc-bk000626-04"><title>RFC: Initial (Default) State</title><para>
The default state of objects will have to be specified here.
There will be no commands that allow the application to set
other defaults.
</para></note>
]]>
</sect2>
</sect1>
</chapter>

2
neo/openal/docs/chp-queueing.sgml Normal file
View File

@@ -0,0 +1,2 @@
<!-- Content has been moved into chp-rendering.sgml -->

2076
neo/openal/docs/chp-rendering.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

730
neo/openal/docs/chp-state.sgml Normal file
View File

@@ -0,0 +1,730 @@
<chapter id="state-requests">
<title>State and State Requests</title>
<para>
The majority of &AL; state is associated with individual &AL; objects,
and has to be set and queried referencing the objects. However, some
state - e.g. processing errors - is
defined context specific. &AL; has global state that affects all
objects and processing equally. This state is set using a variety
of functions, and
can be queried using query functions. The majority of queries
has to use the interface described in "Simple Queries".
</para>
<sect1 id="state-query">
<title>Querying &AL; State</title>
<sect2>
<title>Simple Queries</title>
<para>
Like &OGL;, &AL; uses a simplified interface for querying global
state. The following functions accept a set of enumerations.
<funcsynopsis><funcprototype>
<funcdef> void <function> GetBooleanv </function></funcdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &bool;* <parameter> dest </parameter></paramdef>
</funcprototype></funcsynopsis>
<funcsynopsis><funcprototype>
<funcdef> void <function> GetIntegerv </function></funcdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &int;* <parameter> dest </parameter></paramdef>
</funcprototype></funcsynopsis>
<funcsynopsis><funcprototype>
<funcdef> void <function> GetFloatv </function></funcdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &float;* <parameter> dest </parameter></paramdef>
</funcprototype></funcsynopsis>
<funcsynopsis><funcprototype>
<funcdef> void <function> GetDoublev </function></funcdef>
<paramdef> &enum; <parameter> paramName </parameter></paramdef>
<paramdef> &double;* <parameter> dest </parameter></paramdef>
</funcprototype></funcsynopsis>
Legal values are e.g. DOPPLER_FACTOR, DOPPLER_VELOCITY, DISTANCE_MODEL.
</para>
<para>
NULL destinations are quietly ignored. INVALID_ENUM is the
response to errors in specifying paramName. The amount of memory
required in the destination depends on the actual state requested.
Usually, state variables are returned in only one or some of the
formats above.
</para>
<para>
To query state controlled by Enable/Disable there is an additional
IsEnabled function defined (see "Controlling &AL; Execution").
</para>
</sect2>
<sect2>
<title>Data Conversions</title>
<para>
If a Get command is issued that returns value types different from
the type of the value being obtained, a type converswion is
performed. If GetBooleanv is called, a floating-point or integer
value converts to FALSE if and only if it is zero (otherwise
it converts to TRUE). If GetIntegerv is called, a boolean value
is interpreted as either 1 or 0, and a floating-point value is
rounded to the nearest integer. If GetFloatv is called, a boolean
value is interpreted as either 1.0 or 0.0, an integer is
coerced to floating point, and a double-presicion foating-point
value is converted to single precision. Analogous conversions are
carried out in the case of GetDoublev. If a value is so large
in magnitude that it cannot be represented with the requested
type, then the nearest value is representable using the requested
type is returned.
</para>
<![ %Annote [
<note><title>Annotation (Query of Modes)</title><para>
Modes (e.g. the current distance model) can be queried
using the respective tokens. The recommended query
command is GetIntegerv.
</para></note>
]]>
</sect2>
<sect2>
<title>String Queries</title>
<para>
The application can retrieve state information global to the current
&AL; Context. GetString will return a pointer to a constant string.
Valid values for param are VERSION, RENDERER, VENDOR, and EXTENSIONS,
as well as the error codes defined by &AL;. The application can
use GetString to retrieve a string for an error code.
<funcsynopsis><funcprototype>
<funcdef> const &ubyte;* <function> GetString </function></funcdef>
<paramdef> &enum; <parameter> paramName</parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
</sect2>
</sect1>
<sect1 id="time">
<title>Time and Frequency</title>
<para>
By default, &AL; uses seconds and Hertz as units for
time and frequency, respectively.
A float or integral value of one
for a variable that specifies quantities like duration,
latency, delay, or any other parameter measured as time,
specifies 1 second.
For frequency, the basic unit is 1/second, or Hertz.
In other words, sample frequencies and frequency
cut-offs or filter parameters specifying frequencies
are expressed in units of Hertz.
</para>
<![ %RFC [
<note id="rfc-bk000927-01"><title>RFC: Query and Factor?</title><para>
Will time be an &AL; state that can be queried and scaled?
&AL; usually (always) implements a real-time
process with the constraint that it has to be
synchronized with the time as experienced by the user.
Do the units used with respect to time and frequency have
a fixed meaning?
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000803-03"><title>RFC: Setting Time/Long</title><para>
Given a frequency range from a few Hz to 50kHz or more,
we need a temporal resolution of 20 microseconds or less.
For simplicity that means we either resolve Milliseconds
and loose precision, or we resolve microseconds.
Applications might run hours or days, which is 10E5 seconds
or more. If we cover 12 orders of magnitude (10E6 to 10E-6)
32bit unsigned integer will not suffice. Do we introduce
a 64 signed integer for the purpose of specifying time
over a duration of several days at microseconds resolution,
or do we use two 32bit integers, and how do we split them?
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000806-03"><title>RFC: Duration Query</title>
<para>
The application might want to cull Sources based on
how many milliseconds are left for their current buffer
or queue (either to stop those that will stop soon
anyway, or to stop those that will take too long,
depending).
</para>
<para>
We need to divorce sample (memory) count from duration,
because of compression and differences between
internal and external sample format.
</para>
<para>
Duration can be queried in microsecond resolution in
case we want to account for O(10Khz) sampling
frequencies properly, or milliseconds if we
do not anticipate the need to go beyond typical
operating system time resolution.
</para>
<para>
We need query as double, float, and possibly
long (as of now an undefined data type).
We might need an INVALID_RANGE error on the getter,
especially if large reptition counters can be set.
For paused source, the remainder will be the same
as for playing sources. The application can query
the Source State to find out the additional
information. INFINITE is not needed,
no is UNKNOWN as we operate on known
queues.
</para></note>
]]>
<![ %Scratch [
<![ %Annote [
<note><title>Annotation (Buffer vs. Queue Duration)</title><para>
Sourcel( sName , REMAINDER, &amp;rem ) queries the remainder
for the current buffer (zero if the Source is STOPPED,
duration of the first buffer if the source is INITIAL).
Sourcel( sName, REMAINDER_QUEUE, &amp;rem ) queries the remainder
of the entire queue.
A STOPPED Source has remainder==0.
An INITIAL Source has full remainder.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (DURATION vs. REMAINDER)</title><para>
DURATION is a buffer attribute independent of
execution state. REMAINDER is a Source attribute
that encapsulates part of the execution state.
Sources and Buffers should not share these attributes:
there is no Buffer REMAINDER and no Source DURATION.
</para></note>
]]>
]]>
</sect1>
<sect1 id="scaling">
<title>Space and Distance</title>
<para>
&AL; does not define the units of measurement for distances.
The application is free to use meters, inches, or parsecs.
&AL; provides means for simulating the natural attenuation
of sound according to distance, and to exagerate or reduce
this effect. However, the resulting effects do not depend on
the distance unit used by the application to express source
and listener coordinates. &AL; calculations are scale
invariant.
</para>
<para>
The specification assumes Euclidean calculation of
distances, and mandates that if two Sources are
sorted with respect to the Euclidean metric, the
distance calculation used by the implementation has
to preserve that order.
</para>
<![ %Annote [
<note><title>Annotation (No DistanceFactor)</title><para>
&AL; does not provide a global, per Context DISTANCE_FACTOR,
as all calculations are scale invariant.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Distance Calculations)</title><para>
The specification does not enforce that distances
are calculated using the euclidean norm, to permit
using computationally cheaper approximations.
Implementations that opt to use approximations
might cause audible artifacts. The specification does
not enforce any upper limits on distance calculation
errors yet.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000915-02"><title>RFC: Limiting Errors</title><para>
Do we limit permissible errors on distance or gain
calculations? How much quality
and accuracy do we expect from conformant implementations?
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (DS3D DistanceFactor)</title><para>
The DS3D documentation explicitely states that the default
unit is 1 meter. &AL; does not specify any units.
&AL; calculations are scale invariant. The main purpose
of the DS3D DistanceFactor (modifying Doppler Shift
by scaling velocity but not reference velocity) is
accomplished using DOPPLER_VELOCITY in &AL;. &AL;
does not have an equivalent to A3D's SetUnitsPerMeter
either.
<!-- http://msdn.microsoft.com/library/psdk/directx/dsover_6jj8.htm -->
</para></note>
]]>
</sect1>
<sect1 id="attenuation-by-distance">
<title>Attenuation By Distance</title>
<para>
Samples usually use the entire dynamic range of the
chosen format/encoding, independent of their real world
intensity. In other words, a jet engine and a clockwork
both will have samples with full amplitude. The application
will then have to adjust Source GAIN accordingly to account
for relative differences.
</para>
<para>
Source GAIN is then attenuated by distance.
The effective attenuation of a Source depends on many
factors, among which distance attenuation and source
and Listener GAIN are only some of the contributing
factors. Even if the source and Listener GAIN exceed 1.0
(amplification beyond the guaranteed dynamic range),
distance and other attenuation might ultimately limit
the overall GAIN to a value below 1.0.
</para>
<para>
&AL; currently supports three modes of operation
with respect to distance attenuation. It supports
two distance-dependent attenuation models, including one
that is similar to the IASIG I3DL2 (and DS3D) model.
The application chooses one of these two models (or
chooses to disable distance-dependent attenuation)
on a per-context basis.
<funcsynopsis><funcprototype>
<funcdef> void <function> DistanceModel </function></funcdef>
<paramdef> &enum; <parameter> modelName </parameter></paramdef>
</funcprototype></funcsynopsis>
Legal arguments are NONE, INVERSE_DISTANCE, and
INVERSE_DISTANCE_CLAMPED. NONE bypasses all distance
attenuation calculation for all Sources. The implementation
is expected to optimize this situation. INVERSE_DISTANCE_CLAMPED
is the DS3D model, with REFERENCE_DISTANCE indicating both the
reference distance and the distance below which gain will
be clamped. INVERSE_DISTANCE is equivalent to the DS3D model
with the exception that REFERENCE_DISTANCE does not imply any
clamping. The &AL; implementation is still free to apply
any range clamping as necessary. The current distance model
chosen can be queried using GetIntegerv and DISTANCE_MODEL.
</para>
<![ %Annote [
<note><title>Annotation (Inverse Square Law)</title><para>
The "inverse square law" used in physics applies to sound
intensity (energy), which is proportional to the square
of linear gain (amplitude). Thus the inverse distance model
describes a physically correct inverse square behavior
if ROLLOFF_FACTOR is set to 1.0.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Enable/Disable Attenuation)</title><para>
As ROLLOFF_FACTOR is a per-Source attribute, setting it to zero
can not be used to globally enable or disable distance
attenuation, which (e.g. when using tables) can be resource
intensive. Using Enable/Disable/IsEnabled with a DISTANCE_ATTENUATION
token is redundant with respect to the possibility that support
for different distance models might be desired at a later time.
</para></note>
]]>
<sect2>
<title>Inverse Distance Rolloff Model</title>
<para>
The following formula describes the distance attenutation
defined by the Rolloff Attenutation Model, as logarithmic
calculation.
<literallayout>
G_dB = GAIN - 20*log10(1 + ROLLOFF_FACTOR*(dist-REFERENCE_DISTANCE)/REFERENCE_DISTANCE );
G_dB = min(G_dB,MAX_GAIN);
G_dB = max(G_dB,MIN_GAIN);
</literallayout>
The REFERENCE_DISTANCE parameter used here is a per-Source attribute
that can be set and queried using the REFERENCE_DISTANCE token.
REFERENCE_DISTANCE is the distance at which the Listener will
experience GAIN (unless the implementation had to clamp effective
GAIN to the available dynamic range).
ROLLOFF_FACTOR is per-Source parameter the application can use
to increase or decrease the range of a source by decreasing
or increasing the attenuation, respectively. The default value
is 1. The implementation is free to optimize for a
ROLLOFF_FACTOR value of 0, which indicates that the application
does not wish any distance attenuation on the respective Source.
</para>
<![ %Annote [
<note><title>Annotation (Linear Calculation)</title><para>
The logarithmic formula above is equivalent to
<literallayout>
G = gain_linear / ( 1 + ROLLOFF_FACTOR*((dist-REFERENCE_DISTANCE)/REFERENCE_DISTANCE) );
G = min(G,max_gain_linear);
G = max(G,min_gain_linear);
</literallayout>
with linear gains calculated from the logarithmic GAIN,
MIN_GAIN, MAX_GAIN accordingly.
By means of explanation: linear GAIN is applied to the sample, which describes
an amplitude ultimately (DAC) converted into voltage. The actual power of the
signal is proportional to the square of the amplitude (voltage). Logarithmic
measurement is done by comparing the actual power with a reference value,
i.e. the power (e.g in Watt) at the reference distance. The original Bel unit
of measure (named after Alexander Graham Bell) was defined to account for the
logarithmic response of the human ear: our subjective impression of "loudness"
is not linear in the power of the acoustic signal. For practical purposes (range
of volumes the human ear can handle) the deciBel (dB) is a better unit:
<literallayout>
dB = 10 * log( P/P0 ) = 10 * log( sqr(A/A0 ) = 20 * log( A/A0 )
</literallayout>
Common power/amplitude ratios and attenuations per distance are:
<table>
<title>Logarithmic Scale and Gain</title>
<tgroup cols="4" align="left" colsep=1 rowsep=1>
<thead>
<row>
<entry>Distance</>
<entry>Attenuation</>
<entry>Power Ratio</>
<entry>Amplitude Ratio</>
</row>
</thead>
<tbody>
<row>
<entry>REF</>
<entry> 0dB </>
<entry> 1:1 </>
<entry> 1:1 </>
</row>
<row>
<entry> 2*REF </>
<entry> -6dB </>
<entry> 1:4 </>
<entry> 1:2 </>
</row>
<row>
<entry> 4*REF </>
<entry> -12dB </>
<entry> 1:16 </>
<entry> 1:4 </>
</row>
<row>
<entry> 8*REF </>
<entry> -18dB </>
<entry> 1:64 </>
<entry> 1:8 </>
</row>
<row>
<entry> 0.5*REF </>
<entry> 6dB </>
<entry> 2:1 </>
<entry> 4:1 </>
</row>
<row>
<entry> 0.25*REF </>
<entry> 12dB </>
<entry> 4:1 </>
<entry> 16:1 </>
</row>
</tbody>
</tgroup>
</table>
The logarithmic gain will drop from zero (linear gain 1) to negative infinity
(approaching linear gain 0). A linear gain of zero can not be represented
logarithmically. Any doubling of the reference distance will add another
-6dB (i.e. 6dB of attenuation). This approximates an inverse square law falloff
of signal power with distance, as long as the distance exceeds the reference
distance.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Rolloff quantization)</title><para>
Implementations that use lookup tables to speed up
distance attenuation calculation may opt to map
ROLLOFF_FACTOR to a limited set of internally used
values, to minimize expense of per-Source calculations
and setup/memory costs.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Gain Clamping)</title><para>
In the absence of user MIN_GAIN and MAX_GAIN selections,
clamping is implied by implementation constraints, and
clamping behavior might change.
The &AL; implementation should not clamp intermediate
values of effective gain to unit range.
Any clamping, if necessary, should be applied at the latest
possible stage. In other words, GAIN&gt;1 is perfectly
valid as the implementation is free to clamp the value as
needed for maximum mixing accuracy and to account for the
actual dynamic range of the output device.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (Extended Dynamic Range)</title><para>
For applications that
change GAIN but do not want to adjust ROLLOFF_FACTOR
and REFERENCE_DISTANCE to account for different ranges,
the separation in this distance model might allow for
more intuitive adjustments:
If we put a damper on the jet engine by lowering GAIN,
we still want the listener to perceive the full volume,
but now at a closer distance, without changing the
reference distance.
</para></note>
]]>
</sect2>
<sect2>
<title>Inverse Distance Clamped Model</title>
<para>
This is essentially the Inverse Distance model,
extended to guarantee that for distances below
REFERENCE_DISTANCE, gain is clamped. This mode
is equivalent to the IASIG I3DL2 (and DS3D) distance
model.
<literallayout>
dist = max(dist,REFERENCE_DISTANCE);
dist = min(dist,MAX_DISTANCE);
G_dB = GAIN - 20*log10(1 + ROLLOFF_FACTOR*(dist-REFERENCE_DISTANCE)/REFERENCE_DISTANCE )
G_dB = min(G_dB,MAX_GAIN);
G_dB = max(G_dB,MIN_GAIN);
</literallayout>
</para>
<![ %Annote [
<note><title>Annotation (DS3D MIN_DISTANCE)</title><para>
The DS3D attenuation model is extended by an explicit
clamping mechanism. REFERENCE_DISTANCE is equivalent
to DS3D MIN_DISTANCE if the INVERSE_DISTANCE_CLAMPED
mode is used.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (High Frequency Rolloff)</title><para>
To simulate different atmospheric conditions, a frequency
dependent attenuation is used in A3D and EAX.
At this time &AL; does not have a mechanism to specify
lowpass filtering parameterized by distance.
</para></note>
]]>
</sect2>
</sect1>
<sect1 id="order-distance">
<title>Evaluation of Gain/Attenuation Related State</title>
<para>
While amplification/attenuation commute (mulplication of
scaling factors), clamping operations do not. The order
in which various gain related operations are applied is:
Distance attenuation is calculated first, including
minimum (REFERENCE_DISTANCE) and maximum (MAX_DISTANCE)
thresholds. If the Source is directional (CONE_INNER_ANGLE
less than CONE_OUTER_ANGLE), an angle-dependent attenuation
is calculated depending on CONE_OUTER_GAIN, and multiplied
with the distance dependent attenuation.
The resulting attenuation factor for the given angle and
distance between Listener and Source is multiplied
with Source GAIN. The effective GAIN computed this way
is compared against MIN_GAIN and MAX_GAIN thresholds.
The result is guaranteed to be clamped to [MIN_GAIN, MAX_GAIN],
and subsequently multiplied by Listener GAIN which serves
as an overall volume control. The implementation is free
to clamp Listener GAIN if necessary due to hardware or
implementation constraints.
</para>
</sect1>
<sect1 id="culling-by-distance">
<title>No Culling By Distance</title>
<para>
With the DS3D compatible Inverse Clamped Distance Model,
&AL; provides a per-Source MAX_DISTANCE attribute
that can be used to define a distance beyond which the Source will
not be further attenuated by distance.
The DS3D distance attenuation model and its clamping of volume
is also extended by a mechanism to cull (mute) sources from proccessing,
based on distance. However, &AL; does not
support culling a Source from processing based on a distance
threshold.
</para>
<para>
At this time &AL; is not meant to support culling at all. Culling
based on distance, or bounding volumes, or other criteria, is best
left to the application. For example, the application might
employ sophisticated techniques to determine whether sources
are audible that are beyond the scope of &AL;. In particular,
rule based culling inevitably introduces acoustic artifacts.
E.g. if the Listener-Source distance is nearly equal to the
culling threshold distance, but varies above and below, there
will be popping artifacts in the absence of hysteresis.
</para>
<![ %Annote [
<note><title>Annotation (No MAX_DISTANCE plus MUTE)</title><para>
&AL; does support the AUDIBLE mode with MAX_DISTANCE (clamping),
but does not support culling. Applications that employ this
DS3D feature will have to perform their own distance calculation
and mute the source (Source GAIN equals zero) as desired.
</para></note>
]]>
<![ %RFC [
<note id="rfc-bk000803-07"><title>RFC: DS3D-like Extension</title><para>
For ease of portability, should we define an Extension that
provides MAX_DISTANCE for MUTE mode?
</para></note>
]]>
</sect1>
<![ %Scratch [
<sect1 id="sound-speed">
<title>NO Sound Propagation Speed</title>
<para>
&AL; implementations can choose to model sound propagation with
limited speed for certain effects, e.g. early reflections.
In addition, the Doppler Effect is defined with respect to the
speed of sound in the predominant medium. The application can
set the speed of sound as a scalar value. The speed is defined
with respect to the scaled unit. If D I S T A N C E _ S C A L E is changed,
this will affect both the distance and the propagation speed,
leaving the propagation time unaffected.
<funcsynopsis><funcprototype>
<funcdef> void <function> PropagationSpeed </function></funcdef>
<paramdef> &float; <parameter> propSpeed </parameter></paramdef>
</funcprototype></funcsynopsis>
</para>
<para>
A negative scale will result in an INVALID_VALUE error, the
command is then ignored. The default value is 1. The current
setting can be queried using GetFloatv and PROPAGATION_SPEED.
</para>
</sect1>
]]>
<sect1 id="doppler-scale">
<title>Velocity Dependent Doppler Effect</title>
<para>
The Doppler Effect depends on the velocities of Source and
Listener relative to the medium, and the propagation speed
of sound in that medium. The application might want to
emphasize or de-emphasize the Doppler Effect as physically
accurate calculation might not give the desired results. The
amount of frequency shift (pitch change) is proportional
to the speed of listener and source along their line of
sight. The application can increase or decrease that
frequency shift by specifying the scaling factor &AL;
should apply to the result of the calculation.
</para>
<para>
The Doppler Effect as implemented by &AL; is described
by the formula below. Effects of the medium (air, water)
moving with respect to listener and source are ignored.
DOPPLER_VELOCITY is the propagation speed relative to
which the Source velocities are interpreted.
<literallayout>
VD: DOPPLER_VELOCITY
DF: DOPPLER_FACTOR
vl: Listener velocity (scalar, projected on source-listener vector)
vs: Source velocity (scalar, projected on source-listener vector)
f: Frequency of sample
f': effective Doppler shifted frequency
f' = DF * f * (VD-vl)/(VD+vs)
vl<0, vs>0 : source and listener approaching each other
vl>0, vs<0 : source and listener moving away from each other
</literallayout>
The implementation has to clamp the projected Listener
velocity vl, if abs(vl) is greater or equal to VD. It similarly has to
clamp the projected Source velocity vs if abs(vs) is greater or equal
to VD.
</para>
<para>
There are two API calls global to the current context that provide
control of the two related parameters. DOPPLER_FACTOR is a simple
scaling to exaggerate or deemphasize the Doppler (pitch) shift
resulting from the calculation.
<funcsynopsis><funcprototype>
<funcdef> void <function> DopplerFactor </function></funcdef>
<paramdef> &float; <parameter> dopplerFactor </parameter></paramdef>
</funcprototype></funcsynopsis>
A negative value will result in an INVALID_VALUE error, the
command is then ignored. The default value is 1. The current
setting can be queried using GetFloatv and DOPPLER_FACTOR.
The implementation is free to optimize the case of DOPPLER_FACTOR
being set to zero, as this effectively disables the effect.
</para>
<![ %Annote [
<note><title>Annotation (No Enable)</title><para>
There is currently no mechanism to switch on/off Doppler
calculation using e.g. a DOPPLER_SHIFT token and Enable/Disable.
For the time being, DopplerFactor(0) may be used to signal
to the implementation that no Doppler Effect calculation is
required.
</para></note>
]]>
<para>
DOPPLER_VELOCITY allows the application to change the
reference (propagation) velocity used in the Doppler Effect
calculation. This permits the application to use a velocity
scale appropriate to its purposes.
<funcsynopsis><funcprototype>
<funcdef> void <function> DopplerVelocity </function></funcdef>
<paramdef> &float; <parameter> dopplerVelocity</parameter></paramdef>
</funcprototype></funcsynopsis>
A negative or zero value will result in an INVALID_VALUE error, and the
command is ignored. The default value is 1.
The current setting can be queried using GetFloatv and DOPPLER_VELOCITY.
</para>
<![ %Annote [
<note><title>Annotation (No Sideeffects on Delay)</title><para>
To permit independent control of Doppler Effect as opposed
to other, sound wave propagation related effects (delays,
echos, reverberation), DOPPLER_VELOCITY is not taken into
account for any other calculation than Doppler Shift.
</para></note>
]]>
<![ %Annote [
<note><title>Annotation (SetUnitsPerMeter)</title><para>
DOPPLER_VELOCITY accomplishes the purposes of DS3D
scaling parameters in a straightforward way, without
introducing the undesirable connotations of real world
units.
</para></note>
]]>
</sect1>
</chapter>

5
neo/openal/docs/ent-examples.sgml Normal file
View File

@@ -0,0 +1,5 @@
<!NOTATION ASCII system "ASCII" >
<!ENTITY sample.c system "examples/init_al.c" CDATA CGM-CHAR>
<!ENTITY ExInitAL.c system "examples/init_al.c" CDATA ASCII >

3
neo/openal/docs/ent-extensions.sgml Normal file
View File

@@ -0,0 +1,3 @@
<!-- ENTITY ExtLoopPoint.txt system "extensions/ext-loop-point.txt" CDATA linespecific -->

12
neo/openal/docs/ent-marks-annotated.sgml Normal file
View File

@@ -0,0 +1,12 @@
<!-- Annotated Specification Target -->
<!ENTITY % Level1 "INCLUDE" > <!-- Reference -->
<!ENTITY % Level2 "INCLUDE" > <!-- Specification -->
<!ENTITY % RFC "IGNORE" > <!-- Specification Draft -->
<!ENTITY % Annote "INCLUDE" > <!-- Annotation -->
<!ENTITY % Ext1 "INCLUDE" > <!-- ARB EXTensions -->
<!ENTITY % Ext2 "INCLUDE" > <!-- Vendor EXTensions (if applicable) -->
<!ENTITY % Example "IGNORE" > <!-- Example Code Vendor EXTensions -->
<!ENTITY % Revision "IGNORE" > <!-- CVS Revision History Tags (per-file) -->
<!ENTITY % Scratch "IGNORE" > <!-- Internal working notes/tmeporary -->

12
neo/openal/docs/ent-marks-full.sgml Normal file
View File

@@ -0,0 +1,12 @@
<!-- Annotated Specification Target -->
<!ENTITY % Level1 "INCLUDE" > <!-- Reference -->
<!ENTITY % Level2 "INCLUDE" > <!-- Specification -->
<!ENTITY % RFC "INCLUDE" > <!-- Specification Draft -->
<!ENTITY % Annote "INCLUDE" > <!-- Annotation -->
<!ENTITY % Ext1 "INCLUDE" > <!-- ARB EXTensions -->
<!ENTITY % Ext2 "INCLUDE" > <!-- Vendor EXTensions (if applicable) -->
<!ENTITY % Example "INCLUDE" > <!-- Example Code Vendor EXTensions -->
<!ENTITY % Revision "IGNORE" > <!-- CVS Revision History Tags (per-file) -->
<!ENTITY % Scratch "IGNORE" > <!-- Internal working notes/tmeporary -->

12
neo/openal/docs/ent-marks-reference.sgml Normal file
View File

@@ -0,0 +1,12 @@
<!-- Reference Target --->
<!ENTITY % Level1 "INCLUDE" > <!-- Reference -->
<!ENTITY % Level2 "INCLUDE" > <!-- Specification -->
<!ENTITY % RFC "IGNORE" > <!-- Specification Draft -->
<!ENTITY % Annote "IGNORE" > <!-- Annotation -->
<!ENTITY % Ext1 "INCLUDE" > <!-- ARB EXTensions -->
<!ENTITY % Ext2 "INCLUDE" > <!-- Vendor EXTensions (if applicable) -->
<!ENTITY % Example "IGNORE" > <!-- Example Code Vendor EXTensions -->
<!ENTITY % Revision "IGNORE" > <!-- CVS Revision History Tags (per-file) -->
<!ENTITY % Scratch "IGNORE" > <!-- Internal working notes/tmeporary -->

12
neo/openal/docs/ent-marks-specification.sgml Normal file
View File

@@ -0,0 +1,12 @@
<!-- Specification Target -->
<!ENTITY % Level1 "INCLUDE" > <!-- Reference -->
<!ENTITY % Level2 "INCLUDE" > <!-- Specification -->
<!ENTITY % RFC "IGNORE" > <!-- Specification Draft -->
<!ENTITY % Annote "IGNORE" > <!-- Annotation -->
<!ENTITY % Ext1 "INCLUDE" > <!-- ARB EXTensions -->
<!ENTITY % Ext2 "INCLUDE" > <!-- Vendor EXTensions (if applicable) -->
<!ENTITY % Example "IGNORE" > <!-- Example Code Vendor EXTensions -->
<!ENTITY % Revision "IGNORE" > <!-- CVS Revision History Tags (per-file) -->
<!ENTITY % Scratch "IGNORE" > <!-- Internal working notes/tmeporary -->

43
neo/openal/docs/ent-names.sgml Normal file
View File

@@ -0,0 +1,43 @@
<!ENTITY coLoki "Loki Software" >
<!ENTITY coCreat "Creative Labs" >
<!ENTITY OAL "OpenAL" >
<!ENTITY AL "AL" >
<!ENTITY OGL "OpenGL" >
<!ENTITY NONE "NONE" >
<!ENTITY TRUE "TRUE" >
<!ENTITY FALSE "FALSE" >
<!ENTITY NaN "NaN" >
<!ENTITY Infty "Infinity" >
<!ENTITY type "T " >
<!ENTITY void "void " >
<!ENTITY bool "boolean " >
<!ENTITY byte "byte " >
<!ENTITY ubyte "ubyte " >
<!ENTITY short "short " >
<!ENTITY ushort "ushort " >
<!ENTITY int "int " >
<!ENTITY uint "uint " >
<!ENTITY long "long " >
<!ENTITY ulong "ulong " >
<!ENTITY enum "enum " >
<!ENTITY sizei "sizei " >
<!ENTITY bitfield "bitfield " >
<!ENTITY float "float " >
<!ENTITY double "double " >
<!ENTITY clampf "clampf " >
<!ENTITY clampd "clampd " >
<!-- ALC Context -->
<!ENTITY device "ALCdevice" >
<!ENTITY context "ALCcontext" >
<!ENTITY Par "Name" > <!-- enum as well as identifier -->
<!ENTITY Sig "Signature" > <!-- legal types -->
<!ENTITY Val "Values" > <!-- legal values/ranges -->
<!ENTITY Def "Default" > <!-- default value -->

21
neo/openal/docs/index.html Normal file
View File

@@ -0,0 +1,21 @@
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title> Index</title>
</head>
<body>
<h1>Index</h1>
<p>
This document has been removed.
See <a href="http://www.openal.org/">www.openal.org</a>
for information.
</p>
</body>
</html>
</html>

109
neo/openal/docs/oalspecs.sgml Normal file
View File

@@ -0,0 +1,109 @@
<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
<!-- INCLUDE or IGNORE for marked sections -->
<!ENTITY % Marks system "ent-marks.sgml" >
<!-- keywords and other standard entities -->
<!ENTITY % Entities system "ent-names.sgml" >
<!-- C programs and other example entities -->
<!ENTITY % Examples system "ent-examples.sgml" >
<!-- Extensions as external ASCII documents -->
<!ENTITY % Extensions system "ent-extensions.sgml" >
%Marks;
%Entities;
%Examples;
%Extensions;
<!-- book sections -->
<!ENTITY CREDITS system "../CREDITS" >
<!ENTITY secBookInfo system "sec-bookinfo.sgml" >
<!ENTITY chpIntroduction system "chp-introduction.sgml" >
<!ENTITY chpOperation system "chp-operation.sgml" >
<!ENTITY chpState system "chp-state.sgml" >
<!ENTITY chpRendering system "chp-rendering.sgml" >
<!ENTITY chpBuffers system "chp-buffers.sgml" >
<!ENTITY chpQueueing system "chp-queueing.sgml" >
<!ENTITY chpMultiChannel system "chp-multichannel.sgml" >
<!ENTITY alcContext system "alc-context.sgml" >
<!ENTITY appConstants system "app-constants.sgml" >
<!ENTITY appExtensions system "app-extensions.sgml" >
<!ENTITY appExtensionProcess system "app-extensionprocess.sgml" >
<!ENTITY appAnnotations system "app-annotations.sgml" >
<!-- misc. specifics -->
<!ENTITY DocVersion "1.0 (draft)" >
<!ENTITY DocDate "2000/10/10" >
<!ENTITY ALVersion "1.0" >
<!ENTITY ALCVersion "1.0" >
]>
<!-- INDEX -->
<book id="index">
<!-- HEADING -->
&secBookInfo;
<!-- INTRODUCTION -->
&chpIntroduction;
<!-- CHAPTERS -->
&chpOperation;
&chpState;
&chpRendering;
&chpBuffers;
&chpQueueing;
<![ %Scratch [
&chpMultiChannel;
]]>
&alcContext;
<!-- APPENDICITIS [sic] -->
&appConstants;
&appExtensions;
&appExtensionProcess;
<![ %Scratch [
&appAnnotations;
]]>
<![ %Revision [
<appendix>
<title>Main Document CVS Revision History</title>
<para><literallayout>
CVS Document: $Id: oalspecs.sgml,v 1.15 2000/11/10 23:10:44 bk Exp $
CVS Revision: $Revision: 1.15 $
$Log: oalspecs.sgml,v $
Revision 1.15 2000/11/10 23:10:44 bk
Cleanup.
Revision 1.14 2000/11/04 00:11:40 bk
Maintenance update
Revision 1.13 2000/10/26 03:01:55 bk
Fixed typo for ALC entity.
Revision 1.12 2000/10/26 02:59:46 bk
External entities.
</literallayout><para>
</appendix>
]]>
</book>

53
neo/openal/docs/sec-bookinfo.sgml Normal file
View File

@@ -0,0 +1,53 @@
<bookinfo>
<title>
&OAL; Specification and Reference
</title>
<!--
<editor>
<firstname>Bernd</firstname>
<surname>Kreimeier</surname>
</editor>
-->
<edition>Version 1.0 Draft</edition>
<pubdate>June 2000</pubdate>
<copyright>
<year>1999-2000</year>
<holder>Loki Software</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
</para>
</legalnotice>
<legalnotice>
<para>
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the copyright owners.
</para>
</legalnotice>
<legalnotice>
<para> UNIX is a trademark of X/Open Group.</para>
<para> X Window System is a trademark of X Consortium, Inc.</para>
<para> Linux is a trademark of Linus Torvalds.</para>
<para> Windows is a trademark of Microsoft Corp.</para>
<para> Macintosh and Apple are trademarks of Apple Computer, Inc.</para>
<para> Loki and &OAL; are trademarks of Loki Software, Inc.</para>
<para> All other trademarks are property of their respective owners.</para>
</legalnotice>
<releaseinfo>
Draft document of &OAL; Specification.
</releaseinfo>
</bookinfo>

18
neo/openal/docs/specification.html Normal file
View File

@@ -0,0 +1,18 @@
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>OpenAL Specification</title>
</head>
<body>
<h1>OpenAL Specification</h1>
<p>
This document has been removed.
See <a href="index.html">Index</a>
for the specification.
</p>
</body>
</html>

16
neo/openal/docs/white-paper.html Normal file
View File

@@ -0,0 +1,16 @@
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>OpenAL Whitepaper</title>
</head>
<body>
<h1>OpenAL Whitepaper</h1>
<p>
This document has been removed.
See <a href="index.html">Index</a>
for the specification.
</p>
</body>
</html>