OpenAL-1.7.0.5: A binding to the OpenAL cross-platform 3D audio API

Copyright (c) Sven Panne 2003-2016 BSD3 Sven Panne stable portable Safe Haskell2010

Sound.OpenAL.AL

Description

This module corresponds to chapters 2 (OpenAL Operation), 3 (State and State Requests), 4 (Listener and Sources) and 5 (Buffers) of the OpenAL Specification and Reference (version 1.1).

Synopsis

# OpenAL Fundamentals

OpenAL is concerned with rendering audio into an output buffer and collecting audio data from an input buffer. OpenAL's primary use is assumed to be for spatialized audio. There is no support for MIDI.

OpenAL has three fundamental primitives or objects: Buffers, Sources, and a single listener (see Sound.OpenAL.AL.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 OpenAL operations performed by sending commands in the form of function or procedure calls.

Sources store locations, directions, and other attributes of an object in 3D space and have a buffer associated with them for playback. When the program wants to play a sound, it controls execution through a source object. Sources are processed independently from each other.

Buffers store compressed or uncompressed 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.

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.

# Basic AL Operation

OpenAL can be used for a variety of audio playback tasks, and is an excellent complement to OpenGL for real-time rendering, see Graphics.Rendering.OpenGL. A programmer who is familiar with OpenGL will immediately notice the similarities between the two APIs in that they describe their 3D environments using similar methods.

For an OpenGL/OpenAL program, most of the audio programming will be in two places in the code: initialization of the program, and the rendering loop. An OpenGL/OpenAL 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 OpenAL.

# Time and Frequency

By default, OpenAL 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.

# Space and Distance

OpenAL does not define the units of measurement for distances. The application is free to use meters, inches, or parsecs. OpenAL provides means for simulating the natural attenuation of sound according to distance, and to exaggerate 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. OpenAL calculations are scale invariant. 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.

# Coordinate System

OpenAL - like OpenGL - uses a right-handed Cartesian coordinate system (RHS), where in a frontal default view X (thumb) points right, Y (index finger) points up, and Z (middle finger) points towards the viewer/camera. To switch from a left handed coordinate system (LHS) to a right handed coordinate systems, flip the sign on the Z coordinate.