Introduction

]]>

Formatting and Conventions 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. Annotation (Terminology) "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. ]]> 1.8/1.7./1.6/1.5 September-August 2000 bk Final Draft for Public Review 1.4 June 2000 bk First Draft for Public Review 1.2 March 2000 mkv Draft released for GDC TODO - 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. ]]>

What is the &OAL; Audio System? &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. 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. &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. 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.

Programmer's View of &OAL; 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. 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. Annotation (&OAL; and &OGL; use) 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. ]]>

Implementor's View of &OAL; 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. &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. Annotation (Native audio APIs) Implementors can choose to implement &OAL; on top of an existing native audio API. ]]>

Our View 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.

Requirements, Conformance and Extensions The specification has to guarantee a minimum number of resources. However, implementations are encouraged to compete on performance, available resources, and output quality. RFC: suggested requirements 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. ]]> RFC: no requirements 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. ]]> 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. The current sample implementation and documentation for &OAL; can be obtained from openal.org. &OAL; is also available from the the &OAL; CVS repository. For more information on how to get &OAL; from CVS also see &coLoki; CVS.

Architecture Review and Acknowledgements 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. 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;