<chapter id="introduction">
<title>Introduction</title>
<![ %Revision [
<para><literallayout>
CVS Document: $Id: chp-introduction.sgml,v 1.1.1.1 2002/03/18 14:41:42 garinh Exp $
CVS Revision: $Revision: 1.1.1.1 $
$Log: chp-introduction.sgml,v $
Revision 1.1.1.1 2002/03/18 14:41:42 garinh
initial import
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 -->
