---------------------------------------------------------------------------------- |-- Module : Sound.OpenAL.AL-- Copyright : (c) Sven Panne 2003-2009-- License : BSD-style (see the file LICENSE)-- -- Maintainer : sven.panne@aedion.de-- Stability : stable-- Portability : portable---- 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).----------------------------------------------------------------------------------moduleSound.OpenAL.AL(-- * OpenAL Fundamentals-- $OpenALFundamentals-- * Basic AL Operation-- $BasicALOperation-- * Time and Frequency-- $TimeAndFrequency-- * Space and Distance-- $SpaceAndDistance-- * Coordinate System-- $CoordinateSystemmoduleSound.OpenAL.AL.BasicTypes,moduleSound.OpenAL.AL.Errors,moduleSound.OpenAL.AL.StringQueries,moduleSound.OpenAL.AL.Attenuation,moduleSound.OpenAL.AL.Doppler,moduleSound.OpenAL.AL.Listener,moduleSound.OpenAL.AL.Source,moduleSound.OpenAL.AL.Buffer,moduleSound.OpenAL.AL.Extensions)whereimportSound.OpenAL.AL.BasicTypesimportSound.OpenAL.AL.ErrorsimportSound.OpenAL.AL.StringQueriesimportSound.OpenAL.AL.AttenuationimportSound.OpenAL.AL.DopplerimportSound.OpenAL.AL.ListenerimportSound.OpenAL.AL.SourceimportSound.OpenAL.AL.BufferimportSound.OpenAL.AL.Extensions---------------------------------------------------------------------------------- $OpenALFundamentals-- 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: 'Buffer's, 'Source's, 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.---------------------------------------------------------------------------------- $BasicALOperation-- 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.---------------------------------------------------------------------------------- $TimeAndFrequency-- 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.---------------------------------------------------------------------------------- $SpaceAndDistance-- 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.---------------------------------------------------------------------------------- $CoordinateSystem-- 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.