mirror of
https://github.com/dhewm/dhewm3.git
synced 2024-12-18 08:51:46 +00:00
304 lines
No EOL
12 KiB
Text
304 lines
No EOL
12 KiB
Text
|
|
<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 -->
|
|
|
|
|