--------------------------------------------------------------------------------
-- |
-- Module      :  Sound.OpenAL.AL
-- Copyright   :  (c) Sven Panne 2003-2016
-- License     :  BSD3
-- 
-- Maintainer  :  Sven Panne <svenpanne@gmail.com>
-- 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).
--
--------------------------------------------------------------------------------

module Sound.OpenAL.AL (
   -- * OpenAL Fundamentals
   -- $OpenALFundamentals

   -- * Basic AL Operation
   -- $BasicALOperation

   -- * Time and Frequency
   -- $TimeAndFrequency

   -- * Space and Distance
   -- $SpaceAndDistance

   -- * Coordinate System
   -- $CoordinateSystem

   module Sound.OpenAL.AL.BasicTypes,
   module Sound.OpenAL.AL.Errors,
   module Sound.OpenAL.AL.StringQueries,
   module Sound.OpenAL.AL.Attenuation,
   module Sound.OpenAL.AL.Doppler,
   module Sound.OpenAL.AL.Listener,
   module Sound.OpenAL.AL.Source,
   module Sound.OpenAL.AL.Buffer,
   module Sound.OpenAL.AL.Extensions
) where

import Sound.OpenAL.AL.BasicTypes
import Sound.OpenAL.AL.Errors
import Sound.OpenAL.AL.StringQueries
import Sound.OpenAL.AL.Attenuation
import Sound.OpenAL.AL.Doppler
import Sound.OpenAL.AL.Listener
import Sound.OpenAL.AL.Source
import Sound.OpenAL.AL.Buffer
import Sound.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.