-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A binding to the OpenAL cross-platform 3D audio API
--   
--   A Haskell binding for the OpenAL cross-platform 3D audio API,
--   appropriate for use with gaming applications and many other types of
--   audio applications. For more information about OpenAL, please see:
--   <a>http://connect.creativelabs.com/openal/</a>.
@package OpenAL
@version 1.4.0.2


-- | This module corresponds to the introductory parts of chapter 6 (AL
--   Contexts and the ALC API) of the OpenAL Specification and Reference
--   (version 1.1).
--   
--   The context API makes use of ALC types which are defined separately
--   from the AL types - there is an <a>ALCboolean</a>, <a>ALCchar</a>,
--   etc.
module Sound.OpenAL.ALC.BasicTypes

-- | 8-bit boolean
type ALCboolean = Int8

-- | Character
type ALCchar = Int8

-- | Signed 8-bit 2's complement integer
type ALCbyte = Int8

-- | Unsigned 8-bit integer
type ALCubyte = Word8

-- | Signed 16-bit 2's complement integer
type ALCshort = Int16

-- | Unsigned 16-bit integer
type ALCushort = Word16

-- | Signed 32-bit 2's complement integer
type ALCint = Int32

-- | Unsigned 32-bit integer
type ALCuint = Word32

-- | Non-negatitve 32-bit binary integer size
type ALCsizei = Int32

-- | Enumerated 32-bit value
type ALCenum = Int32

-- | 32-bit IEEE754 floating-point
type ALCfloat = Float

-- | 64-bit IEEE754 floating-point
type ALCdouble = Double


-- | This module corresponds to section 6.1 (Managing Devices) of the
--   OpenAL Specification and Reference (version 1.1).
--   
--   ALC introduces the notion of a device. A device can be, depending on
--   the implementation, a hardware device, or a daemon/OS service/actual
--   server. This mechanism also permits different drivers (and hardware)
--   to coexist within the same system, as well as allowing several
--   applications to share system resources for audio, including a single
--   hardware output device. The details are left to the implementation,
--   which has to map the available backends to unique device specifiers.
module Sound.OpenAL.ALC.Device

-- | The abstract device type.
data Device

-- | <a>openDevice</a> allows the application (i.e. the client program) to
--   connect to a device (i.e. the server). If the function returns
--   <a>Nothing</a>, then no sound driver/device has been found. The
--   argument to <a>openDevice</a> specifies a certain device or device
--   configuration. If it is <a>Nothing</a>, the implementation will
--   provide an implementation specific default, see
--   <a>defaultDeviceSpecifier</a>. Otherwise it is <a>Just</a> an
--   implementation-dependent string. You can use
--   <a>allDeviceSpecifiers</a> to get a list of the known OpenAL devices.
--   
--   <i>Notes for Windows:</i> There are 3 possible device strings, each
--   having a deprecated equivalent for legacy applications only:
--   
--   <ul>
--   <li><tt>"Generic Hardware"</tt> (legacy string:
--   <tt>"DirectSound3D"</tt>)</li>
--   <li><tt>"Generic Software"</tt> (legacy string:
--   <tt>"DirectSound"</tt>)</li>
--   <li><tt>"Generic Software Fallback"</tt> (legacy string:
--   <tt>"MMSYSTEM"</tt>)</li>
--   </ul>
--   
--   <i>Notes for Linux\</i>*nix:/ If an <tt>.openalrc</tt> file is present
--   in the user's home directory, it is loaded first, otherwise
--   <tt>/etc/openalrc</tt> is tried. The bindings (if any) of
--   <tt>devices</tt>, <tt>direction</tt>, <tt>sampling-rate</tt>, and
--   <tt>speaker-num</tt> (see below) after loading one of these files take
--   precedence over any bindings done via the argument to
--   <a>openDevice</a>.
--   
--   The syntax of these files is lisp-based and a sequence of expressions,
--   where an expression is one the following:
--   
--   <ul>
--   <li>A boolean value of the form <tt>#f</tt> or <tt>#t</tt>, which
--   evaluate to <i>false</i> and <i>true</i>, respectively.</li>
--   <li>An non-negative integer value, i.e. a sequence of decimal digits,
--   evaluating to itself.</li>
--   <li>A (signed) floating point value, as recoginzed by C's
--   <tt>atof()</tt>, evaluating to itself.</li>
--   <li>A pointer value of the form <tt>#p<i>num</i></tt>, where
--   <i>num</i> can be an octal, decimal or hexadecimal value, as
--   recoginzed by C`s <tt>strtol()</tt>, evaluating to itself. This kind
--   of expression is currently unused.</li>
--   <li>A string, i.e. a sequence of printable/whitespace characters
--   between double quotes, evaluating to itself.</li>
--   <li>A symbol, i.e. a sequence of almost all characters which don't
--   form a simple expression like the ones mentioned below, e.g.
--   <tt>foo</tt>, <tt>bar1</tt>, <tt>3baz</tt>, ... The symbol evaluates
--   to the value currently bound to it.</li>
--   <li>A function application of the form <tt>(<i>symbol</i>
--   <i>expression</i>...)</tt>. The function bound to the symbol is
--   applied to the evaluated arguments.</li>
--   <li>A quotation of the form <tt>(quote <i>expression</i>)</tt> or
--   <tt>'<i>expression</i></tt>, evaluating to the unevaluated
--   <i>expression</i> itself.</li>
--   <li>A definition of the form <tt>(define <i>symbol</i>
--   <i>expression</i>)</tt>, binding <i>symbol</i> to the value of
--   <i>expression</i>. The whole expression evaluates to the value of
--   <i>expression</i>, too.</li>
--   <li>A conjunction of boolean expressions of the form <tt>(and
--   <i>expression</i>...)</tt>. Each <i>expression</i> is evaluated in
--   turn, and if one of them evaluates to <i>false</i>, the value of the
--   whole expression is <i>false</i>. Otherwise the value is
--   <i>true</i>.</li>
--   <li>An extension loading mechanism of the form <tt>(load-extension
--   <i>libraryName</i>)</tt>, where <i>libraryName</i> has to evaluate to
--   a string. This tries to load the dynamic library with up to 3 special
--   entry points: <tt>alExtension_03282000</tt> (pointing to a mandatory
--   NULL-terminated sequence of pairs of pointers to names and extension
--   functions), <tt>alExtInit_03282000</tt> (an optional initialization
--   function), and <tt>alExtFini_03282000</tt> (an optional cleanup
--   function). If the extension could be loaded successfully, the whole
--   expression evaluates to <i>true</i>, otherwise to <i>false</i>.</li>
--   </ul>
--   
--   Some symbols have a special meaning for OpenAL:
--   
--   <ul>
--   <li><i><tt>devices</tt></i> Has the form <tt>(<i>devspec</i>...)</tt>,
--   where <i>devspec</i> is either a symbol/string specifying a device or
--   <tt>(<i>device</i> <i>device-param</i>...)</tt>, specifying a device
--   with additional parameters. These optional device parameters are
--   stored in a variable <tt>device-params</tt>, but are currently unused.
--   The first device which can successfully opened is used.</li>
--   <li><i><tt>direction</tt></i> Type string or symbol: <tt>"read"</tt>
--   specifies that the device should be an input device, everything else
--   means output device (default).</li>
--   <li><i><tt>sampling-rate</tt></i> Type integer or float: Specifies the
--   internal mixing frequency, default is 44.1kHz.</li>
--   <li><i><tt>speaker-num</tt></i> Type integer or float: Specifies the
--   number of speakers, which can be 1, 2 (default), or 4.</li>
--   <li><i><tt>alsa-device</tt></i> Type string, <tt>alsa</tt> backend
--   only: Specifies both <tt>alsa-out-device</tt> and
--   <tt>alsa-in-device</tt>, default <tt>"plughw:0,0"</tt>.</li>
--   <li><i><tt>alsa-out-device</tt></i> Type string, <tt>alsa</tt> backend
--   only: Specifies the ALSA output device, defaults to the value of
--   <tt>alsa-device</tt>.</li>
--   <li><i><tt>alsa-in-device</tt></i> Type string, <tt>alsa</tt> backend
--   only: Specifies the ALSA input device, defaults to the value of
--   <tt>alsa-device</tt>.</li>
--   <li><i><tt>native-in-device</tt></i> Type string, <tt>native</tt>
--   backend on IRIX only.</li>
--   <li><i><tt>native-out-device</tt></i> Type string, <tt>native</tt>
--   backend on IRIX only.</li>
--   <li><i><tt>native-rear-out-device</tt></i> Type string,
--   <tt>native</tt> backend on IRIX only.</li>
--   <li><i><tt>native-use-select</tt></i> Type boolean, <tt>native</tt>
--   backend on Linux only: If <tt>#t</tt>, wait up to 0.8sec for the
--   device to become ready for writing. If <tt>#f</tt>, just try to write
--   and hope it won't hang forever. The latter might be necessary for some
--   drivers which don't implement <tt>select()</tt> , like some Aureal
--   drivers.</li>
--   <li><i><tt>lin-dsp-path</tt></i> Type string, <tt>native</tt> backend
--   on Linux only: Path to DSP device for writing, tried before
--   <tt>/dev/sound/dsp</tt> and <tt>/dev/sound</tt> if set.</li>
--   <li><i><tt>lin-dsp-read-path</tt></i> Type string, <tt>native</tt>
--   backend on Linux only: Path to DSP device for reading, tried before
--   <tt>/dev/sound/dsp</tt> and <tt>/dev/sound</tt> if set. Defaults to
--   the value of <tt>lin-dsp-path</tt>.</li>
--   <li><i><tt>native-backend-debug</tt></i> Type boolean, <tt>native</tt>
--   backend on Darwin only: If set to <tt>#f</tt>, be a bit verbose on
--   stderr about what's going on in the backend.</li>
--   <li><i><tt>source-rolloff-factor</tt></i> Type integer or float: Value
--   of the initial rolloff factor for sources, default is
--   <tt>1.0</tt>.</li>
--   <li><i><tt>listener-position</tt></i> List of 3 integers or floats:
--   Value of the initial listener position, default is <tt>(0 0
--   0)</tt>.</li>
--   <li><i><tt>listener-velocity</tt></i> List of 3 integers or floats:
--   Value of the initial listener velocity, default is <tt>(0 0
--   0)</tt>.</li>
--   <li><i><tt>listener-orientation</tt></i> List of 6 integers or floats:
--   Value of the initial listener orientation (at/up), default is <tt>(0 0
--   -1 0 1 0)</tt>.</li>
--   </ul>
--   
--   The string given to <a>openDevice</a> has to be of the form
--   <tt>'((<i>symbol</i> <i>expression</i>) ...)</tt>, which means
--   basically a sequence of <tt>define</tt> expressions. Example:
--   
--   <pre>
--   "'((sampling-rate 8000) (native-backend-debug #f))"
--   </pre>
--   
--   <i>Note:</i> The information above has been reverse-engineered from
--   the OpenAL SI and could be inaccurate. Any corrections and/or
--   additions are highly welcome.
openDevice :: Maybe String -> IO (Maybe Device)

-- | <a>closeDevice</a> allows the application (i.e. the client program) to
--   disconnect from a device (i.e. the server). It returns <a>True</a> for
--   success and <a>False</a> for failure. Once closed, the <a>Device</a>
--   is invalid.
--   
--   <i>Note:</i> Older OpenAL implementations will always report a
--   success!
closeDevice :: Device -> IO Bool

-- | Contains <a>Just</a> the specifier string for the default device or
--   <a>Nothing</a> if there is no sound support at all.
defaultDeviceSpecifier :: GettableStateVar (Maybe String)

-- | Contains the specifier string for the given device.
deviceSpecifier :: Device -> GettableStateVar String

-- | Contains a list of specifiers for all available devices.
allDeviceSpecifiers :: GettableStateVar [String]


-- | This module corresponds to section 6.2 (Managing Rendering Contexts)
--   of the OpenAL Specification and Reference (version 1.1).
--   
--   All operations of the AL core API affect a current AL context. Within
--   the scope of AL, the ALC is implied - it is not visible as a handle or
--   function parameter. Only one AL Context per process can be current at
--   a time. Applications maintaining multiple AL Contexts, whether
--   threaded or not, have to set the current context accordingly.
--   Applications can have multiple threads that share one more or
--   contexts. In other words, AL and ALC are threadsafe.
module Sound.OpenAL.ALC.Context

-- | Frequency, specified in samples per second, i.e. units of Hertz [Hz].
--   Note that the underlying OpenAL API currently uses integral
--   frequencies only, but we want to mirror physical reality here more
--   closely.
type Frequency = Float

-- | The application can choose to specify certain attributes for a context
--   at context-creation time. Attributes not specified explicitly are set
--   to implementation dependent defaults.
data ContextAttribute

-- | Frequency for mixing output buffer, in units of Hz
Frequency :: Frequency -> ContextAttribute

-- | Refresh intervals, in units of Hz
Refresh :: Frequency -> ContextAttribute

-- | Flag, indicating a synchronous context
Sync :: Bool -> ContextAttribute

-- | A hint indicating how many sources should be capable of supporting
--   mono data
MonoSources :: Int -> ContextAttribute

-- | A hint indicating how many sources should be capable of supporting
--   stereo data
StereoSources :: Int -> ContextAttribute

-- | The abstract context type.
data Context

-- | Create a context for a given device and given attributes. Context
--   creation will fail in the following cases: a) if the application
--   requests attributes that, by themselves, can not be provided b) if the
--   combination of specified attributes can not be provided c) if a
--   specified attribute, or the combination of attributes, does not match
--   the default values for unspecified attributes If context creation
--   fails, <a>Nothing</a> will be returned, otherwise <a>Just</a> the new
--   context. Note that <a>createContext</a> does <i>not</i> set the
--   current context, this must be done separately via
--   <a>currentContext</a>.
createContext :: Device -> [ContextAttribute] -> IO (Maybe Context)

-- | Contains <a>Just</a> the current context with respect to OpenAL
--   operation, or <a>Nothing</a> if there is no current context. Setting
--   it to the latter is useful when shutting OpenAL down. The state
--   variable applies to the device that the context was created for. For
--   each OS process (usually this means for each application), only one
--   context can be current at any given time. All AL commands apply to the
--   current context. Commands that affect objects shared among contexts
--   (e.g. buffers) have side effects on other contexts.
currentContext :: StateVar (Maybe Context)

-- | The current context is the only context accessible to state changes by
--   AL commands (aside from state changes affecting shared objects).
--   However, multiple contexts can be processed at the same time. To
--   indicate that a context should be processed (i.e. that internal
--   execution state like offset increments are supposed to be performed),
--   the application has to use <a>processContext</a>. Repeated calls to
--   <a>processContext</a> are legal, and do not affect a context that is
--   already marked as processing. The default state of a context created
--   by <a>createContext</a> is that it is processing.
processContext :: Context -> IO ()

-- | The application can suspend any context from processing (including the
--   current one). To indicate that a context should be suspended from
--   processing (i.e. that internal execution state like offset increments
--   is not supposed to be changed), the application has to use
--   <a>suspendContext</a>. Repeated calls to <a>suspendContext</a> are
--   legal, and do not affect a context that is already marked as
--   suspended.
suspendContext :: Context -> IO ()

-- | Destroy the given context. Note that the the correct way to destroy a
--   context is to first release it by setting <a>currentContext</a> to
--   <a>Nothing</a>. Applications should not attempt to destroy a current
--   context, doing so will not work and will result in an
--   <tt>ALCInvalidOperation</tt> error.
destroyContext :: Context -> IO ()

-- | Contains <a>Just</a> the device of the given context or <a>Nothing</a>
--   if the context is invalid.
contextsDevice :: Context -> GettableStateVar (Maybe Device)

-- | Contains the attribute list for the current context of the specified
--   device.
allAttributes :: Device -> GettableStateVar [ContextAttribute]
instance Eq ContextAttribute
instance Ord ContextAttribute
instance Show ContextAttribute


-- | This module corresponds to the extension handling parts of section 6.3
--   (ALC Queries) of the OpenAL Specification and Reference (version 1.1).
module Sound.OpenAL.ALC.Extensions

-- | Contains a list of available context extensions.
alcExtensions :: Device -> GettableStateVar [String]

-- | To verify that a given extension is available for the current context
--   and the device it is associated with, use
--   <a>alcIsExtensionPresent</a>. For invalid and unsupported string
--   tokens it contains <a>False</a>. Using <a>Nothing</a> as the device is
--   acceptable. The extension name is not case sensitive: The
--   implementation will convert the name to all upper-case internally (and
--   will express extension names in upper-case).
alcIsExtensionPresent :: Maybe Device -> String -> GettableStateVar Bool

-- | The application is expected to verify the applicability of an
--   extension or core function entry point before requesting it by name,
--   by use of <a>alcIsExtensionPresent</a>. Extension entry points can be
--   retrieved using <a>alcProcAddress</a>. Entry points can be device
--   specific, but are not context specific. Using <a>Nothing</a> as the
--   device does not guarantee that the entry point is returned, even if
--   available for one of the available devices.
alcProcAddress :: Maybe Device -> String -> GettableStateVar (FunPtr a)

-- | Enumeration/token values are device independent, but tokens defined
--   for extensions might not be present for a given device. Using
--   <a>Nothing</a> as the device is legal, but only the tokens defined by
--   the AL core are guaranteed. Availability of extension tokens depends
--   on the ALC extension.
alcEnumValue :: Maybe Device -> String -> GettableStateVar ALCenum

-- | Contains the "<i>major</i>.<i>minor</i>" specification revision for
--   this implementation.
alcVersion :: GettableStateVar String


-- | This module corresponds to section 6.3.6 (Query for Error Conditions)
--   of the OpenAL Specification and Reference (version 1.1).
module Sound.OpenAL.ALC.Errors

-- | ALC errors consist of a general error category and a description of
--   what went wrong.
data ALCError
ALCError :: ALCErrorCategory -> String -> ALCError

-- | General ALC error categories.
data ALCErrorCategory
ALCInvalidEnum :: ALCErrorCategory
ALCInvalidValue :: ALCErrorCategory
ALCInvalidOperation :: ALCErrorCategory
ALCInvalidDevice :: ALCErrorCategory
ALCInvalidContext :: ALCErrorCategory
ALCOutOfMemory :: ALCErrorCategory

-- | OpenAL detects only a subset of those conditions that could be
--   considered errors. This is because in many cases error checking would
--   adversely impact the performance of an error-free program. The state
--   variable <a>alcErrors</a> is used to obtain error information. When an
--   error is detected by ALC, a flag is set and the error code is
--   recorded. Further errors, if they occur, do not affect this recorded
--   code. When <a>alcErrors</a> is read, the error for the given device is
--   returned and the flag is cleared, so that a further error will again
--   record its code. If reading <a>alcErrors</a> returns <tt>[]</tt> then
--   there has been no detectable error since the last time
--   <a>alcErrors</a> (or since the ALC was initialized).
--   
--   When an error flag is set, results of ALC operations are undefined
--   only if <a>ALCOutOfMemory</a> has occurred. In other cases, the
--   command generating the error is ignored so that it has no effect on
--   ALC state or output buffer contents. If the error generating command
--   returns a value, it returns zero. If the generating command modifies
--   values through a pointer argument, no change is made to these values.
--   These error semantics apply only to ALC errors, not to system errors
--   such as memory access errors.
alcErrors :: Device -> GettableStateVar [ALCError]
instance Eq ALCErrorCategory
instance Ord ALCErrorCategory
instance Show ALCErrorCategory
instance Eq ALCError
instance Ord ALCError
instance Show ALCError


-- | This module corresponds to section 2.2 (Primitive Types) of the OpenAL
--   Specification and Reference (version 1.1).
module Sound.OpenAL.AL.BasicTypes

-- | 8-bit boolean
type ALboolean = Int8

-- | Character
type ALchar = Int8

-- | Signed 8-bit 2's complement integer
type ALbyte = Int8

-- | Unsigned 8-bit integer
type ALubyte = Word8

-- | Signed 16-bit 2's complement integer
type ALshort = Int16

-- | Unsigned 16-bit integer
type ALushort = Word16

-- | Signed 32-bit 2's complement integer
type ALint = Int32

-- | Unsigned 32-bit integer
type ALuint = Word32

-- | Non-negatitve 32-bit binary integer size
type ALsizei = Int32

-- | Enumerated 32-bit value
type ALenum = Int32

-- | 32-bit IEEE754 floating-point
type ALfloat = Float

-- | 64-bit IEEE754 floating-point
type ALdouble = Double


-- | This is a purely internal module for (un-)marshaling ALboolean.
module Sound.OpenAL.AL.ALboolean
marshalALboolean :: Bool -> ALboolean
unmarshalALboolean :: ALboolean -> Bool


-- | This is a purely internal module for (un-)marshaling Buffer.
module Sound.OpenAL.AL.BufferInternal

-- | The abstract buffer type.
newtype Buffer
Buffer :: ALuint -> Buffer
bufferID :: Buffer -> ALuint
marshalBuffer :: Maybe Buffer -> ALuint
unmarshalBuffer :: ALuint -> Maybe Buffer
instance Eq Buffer
instance Ord Buffer
instance Show Buffer
instance ObjectName Buffer
instance Storable Buffer


-- | This is a purely internal module for (un-)marshaling Format.
module Sound.OpenAL.AL.Format

-- | Valid sound formats. An implementation may expose other formats, see
--   <a>Sound.OpenAL.ALC.Extensions</a> for information on determining if
--   additional formats are supported.
data Format
Mono8 :: Format
Mono16 :: Format
Stereo8 :: Format
Stereo16 :: Format
marshalFormat :: Format -> ALenum
unmarshalFormat :: ALenum -> Format
instance Eq Format
instance Ord Format
instance Show Format


-- | This module corresponds to chapter 6 (Buffers) of the OpenAL
--   Specification and Reference (version 1.1).
--   
--   A buffer encapsulates OpenAL state related to storing sample data. The
--   application can request and release buffer objects, and fill them with
--   data. Data can be supplied compressed and encoded as long as the
--   format is supported. Buffers can, internally, contain waveform data as
--   uncompressed or compressed samples.
--   
--   Unlike source (see <a>Sound.OpenAL.AL.Source</a>) and listener (see
--   <a>Sound.OpenAL.AL.Listener</a>) objects, buffer objects can be shared
--   among AL contexts. Buffers are referenced by sources. A single buffer
--   can be referred to by multiple sources. This separation allows drivers
--   and hardware to optimize storage and processing where applicable.
--   
--   The simplest supported format for buffer data is PCM. PCM data is
--   assumed to use the processor's native byte order. Other formats use
--   the byte order native to that format.
--   
--   At this time, buffer states are defined for purposes of discussion.
--   The states described in this section are not exposed through the API
--   (can not be queried, or be set directly), and the state description
--   used in the implementation might differ from this.
--   
--   A buffer is considered to be in one of the following states, with
--   respect to all sources:
--   
--   <ul>
--   <li><i><i>unused</i></i> The buffer is not included in any queue for
--   any source. In particular, the buffer is neither pending nor current
--   for any source. The buffer name can be deleted at this time.</li>
--   <li><i><i>processed</i></i> The buffer is listed in the queue of at
--   least one source, but is neither pending nor current for any source.
--   The buffer can be deleted as soon as it has been unqueued for all
--   sources it is queued with.</li>
--   <li><i><i>pending</i></i> There is at least one source for which the
--   buffer has been queued, for which the buffer data has not yet been
--   dereferenced. The buffer can only be unqueued for those sources that
--   have dereferenced the data in the buffer in its entirety, and cannot
--   be deleted or changed.</li>
--   </ul>
--   
--   The buffer state is dependent on the state of all sources that is has
--   been queued for. A single queue occurrence of a buffer propagates the
--   buffer state (over all sources) from <i>unused</i> to <i>processed</i>
--   or higher. Sources that are in the <tt>Stopped</tt> or
--   <tt>Initial</tt> states still have queue entries that cause buffers to
--   be <i>processed</i>.
--   
--   A single queue entry with a single source for which the buffer is not
--   yet <i>processed</i> propagates the buffer's queuing state to
--   <i>pending</i>.
--   
--   Buffers that are <i>processed</i> for a given source can be unqueued
--   from that source's queue. Buffers that have been unqueued from all
--   sources are <i>unused</i>. Buffers that are <i>unused</i> can be
--   deleted, or changed by writing <a>bufferData</a>.
module Sound.OpenAL.AL.Buffer

-- | The abstract buffer type.
data Buffer
data MemoryRegion a
MemoryRegion :: (Ptr a) -> ALsizei -> MemoryRegion a

-- | Valid sound formats. An implementation may expose other formats, see
--   <a>Sound.OpenAL.ALC.Extensions</a> for information on determining if
--   additional formats are supported.
data Format
Mono8 :: Format
Mono16 :: Format
Stereo8 :: Format
Stereo16 :: Format
data BufferData a
BufferData :: (MemoryRegion a) -> Format -> Frequency -> BufferData a

-- | A special case of buffer state is the actual sound sample data stored
--   in association with the buffer. Applications can specify sample data
--   using <a>bufferData</a>.
--   
--   The data specified is copied to an internal software, or if possible,
--   hardware buffer. The implementation is free to apply decompression,
--   conversion, resampling, and filtering as needed. The internal format
--   of the buffer is not exposed to the application, and not accessible.
--   
--   Buffers containing audio data with more than one channel will be
--   played without 3D spatialization features, these formats are normally
--   used for background music. Applications should always check for an
--   error condition after attempting to specify buffer data in case an
--   implementation has to generate an <tt>ALOutOfMemory</tt> or a
--   conversion related <tt>ALInvalidValue</tt> error. The application is
--   free to reuse the memory specified by the data pointer once
--   <a>bufferData</a> is set. The implementation has to dereference, e.g.
--   copy, the data while accessing <a>bufferData</a> execution.
bufferData :: Buffer -> StateVar (BufferData a)
instance Eq (MemoryRegion a)
instance Ord (MemoryRegion a)
instance Show (MemoryRegion a)
instance Eq (BufferData a)
instance Ord (BufferData a)
instance Show (BufferData a)


-- | This module corresponds to section 6.4.2. (Capture) of the OpenAL
--   Specification and Reference (version 1.1).
module Sound.OpenAL.ALC.Capture
type NumSamples = ALCsizei
captureOpenDevice :: Maybe String -> Frequency -> Format -> NumSamples -> IO (Maybe Device)
captureStart :: Device -> IO ()
captureNumSamples :: Device -> GettableStateVar NumSamples
captureSamples :: Device -> Ptr a -> NumSamples -> IO ()
captureStop :: Device -> IO ()
captureCloseDevice :: Device -> IO Bool

-- | Contains the name of the default capture device.
captureDefaultDeviceSpecifier :: GettableStateVar String

-- | Contains the specifier string for the given capture device.
captureDeviceSpecifier :: Device -> GettableStateVar String

-- | Contains a list of specifiers for all available capture devices.
allCaptureDeviceSpecifiers :: GettableStateVar [String]


-- | This module corresponds to section 2.7 (AL Errors) of the OpenAL
--   Specification and Reference (version 1.1).
module Sound.OpenAL.AL.Errors

-- | AL errors consist of a general error category and a description of
--   what went wrong.
data ALError
ALError :: ALErrorCategory -> String -> ALError

-- | General AL error categories.
data ALErrorCategory
ALInvalidEnum :: ALErrorCategory
ALInvalidValue :: ALErrorCategory
ALInvalidOperation :: ALErrorCategory
ALInvalidName :: ALErrorCategory
ALOutOfMemory :: ALErrorCategory

-- | OpenAL detects only a subset of those conditions that could be
--   considered errors. This is because in many cases error checking would
--   adversely impact the performance of an error-free program. The state
--   variable <a>alErrors</a> is used to obtain error information. When an
--   error is detected by AL, a flag is set and the error code is recorded.
--   Further errors, if they occur, do not affect this recorded code. When
--   <a>alErrors</a> is read, the error is returned and the flag is
--   cleared, so that a further error will again record its code. If
--   reading <a>alErrors</a> returns <tt>[]</tt> then there has been no
--   detectable error since the last time <a>alErrors</a> (or since the AL
--   was initialized).
--   
--   When an error flag is set, results of AL operations are undefined only
--   if <a>ALOutOfMemory</a> has occurred. In other cases, the command
--   generating the error is ignored so that it has no effect on AL state
--   or output buffer contents. If the error generating command returns a
--   value, it returns zero. If the generating command modifies values
--   through a pointer argument, no change is made to these values. These
--   error semantics apply only to AL errors, not to system errors such as
--   memory access errors.
alErrors :: GettableStateVar [ALError]
instance Eq ALErrorCategory
instance Ord ALErrorCategory
instance Show ALErrorCategory
instance Eq ALError
instance Ord ALError
instance Show ALError


-- | This module corresponds to section 3.1.2 (String Queries) of the
--   OpenAL Specification and Reference (version 1.1).
module Sound.OpenAL.AL.StringQueries

-- | Contains the name of the vendor.
alVendor :: GettableStateVar String

-- | Contains information about the specific renderer.
alRenderer :: GettableStateVar String


-- | This module corresponds to section 3.4 (Attenuation By Distance) of
--   the OpenAL Specification and Reference (version 1.1).
module Sound.OpenAL.AL.Attenuation

-- | OpenAL currently supports six modes of operation with respect to
--   distance attenuation, including one that is similar to the IASIG I3DL2
--   model. The application chooses one of these models (or chooses to
--   disable distance-dependent attenuation) on a per-context basis.
--   
--   The distance used in the formulas for the "clamped" modes below is
--   clamped to be in the range between <tt>referenceDistance</tt> and
--   <tt>maxDistance</tt>:
--   
--   <i>clamped distance</i> = max(<tt>referenceDistance</tt>,
--   min(<i>distance</i>, <tt>maxDistance</tt>))
--   
--   The linear models are not physically realistic, but do allow full
--   attenuation of a source beyond a specified distance. The OpenAL
--   implementation is still free to apply any range clamping as necessary.
--   
--   With all the distance models, if the formula can not be evaluated then
--   the source will not be attenuated. For example, if a linear model is
--   being used with <tt>referenceDistance</tt> equal to
--   <tt>maxDistance</tt>, then the gain equation will have a
--   divide-by-zero error in it. In this case, there is no attenuation for
--   that source.
data DistanceModel

-- | Bypass all distance attenuation calculation for all sources. The
--   implementation is expected to optimize this situation.
NoAttenuation :: DistanceModel

-- | Inverse distance rolloff model, which is equivalent to the IASIG I3DL2
--   model with the exception that <tt>referenceDistance</tt> does not
--   imply any clamping.
--   
--   <i>gain</i> = <tt>referenceDistance</tt> / (<tt>referenceDistance</tt>
--   + <tt>rolloffFactor</tt> * (<i>distance</i> -
--   <tt>referenceDistance</tt>))
--   
--   The <tt>referenceDistance</tt> parameter used here is a per-source
--   attribute which is the distance at which the listener will experience
--   gain (unless the implementation had to clamp effective gain to the
--   available dynamic range). <tt>rolloffFactor</tt> is per-source
--   parameter the application can use to increase or decrease the range of
--   a source by decreasing or increasing the attenuation, respectively.
--   The default value is 1. The implementation is free to optimize for a
--   <tt>rolloffFactor</tt> value of 0, which indicates that the
--   application does not wish any distance attenuation on the respective
--   source.
InverseDistance :: DistanceModel

-- | Inverse Distance clamped model, which is essentially the inverse
--   distance rolloff model, extended to guarantee that for distances below
--   <tt>referenceDistance</tt>, gain is clamped. This mode is equivalent
--   to the IASIG I3DL2 distance model.
InverseDistanceClamped :: DistanceModel

-- | Linear distance rolloff model, modeling a linear dropoff in gain as
--   distance increases between the source and listener.
--   
--   <i>gain</i> = (1 - <tt>rolloffFactor</tt> * (<i>distance</i> -
--   <tt>referenceDistance</tt>) / (<tt>maxDistance</tt> -
--   <tt>referenceDistance</tt>))
LinearDistance :: DistanceModel

-- | Linear Distance clamped model, which is the linear model, extended to
--   guarantee that for distances below <tt>referenceDistance</tt>, gain is
--   clamped.
LinearDistanceClamped :: DistanceModel

-- | Exponential distance rolloff model, modeling an exponential dropoff in
--   gain as distance increases between the source and listener.
--   
--   <i>gain</i> = (<i>distance</i> / <tt>referenceDistance</tt>) ** (-
--   <tt>rolloffFactor</tt>)
ExponentDistance :: DistanceModel

-- | Exponential Distance clamped model, which is the exponential model,
--   extended to guarantee that for distances below
--   <tt>referenceDistance</tt>, gain is clamped.
ExponentDistanceClamped :: DistanceModel

-- | Contains the current per-context distance model.
distanceModel :: StateVar DistanceModel
instance Eq DistanceModel
instance Ord DistanceModel
instance Show DistanceModel


-- | This module corresponds to sections 4.1 (Basic Listener and Source
--   Attributes) and 4.2 (Listener Object) of the OpenAL Specification and
--   Reference (version 1.1).
--   
--   The listener object defines various properties that affect processing
--   of the sound for the actual output. The listener is unique for an
--   OpenAL Context, and has no name. By controlling the listener, the
--   application controls the way the user experiences the virtual world,
--   as the listener defines the sampling/pickup point and orientation, and
--   other parameters that affect the output stream.
--   
--   It is entirely up to the driver and hardware configuration, i.e. the
--   installation of OpenAL as part of the operating system and hardware
--   setup, whether the output stream is generated for headphones or 2
--   speakers, 4.1 speakers, or other arrangements, whether (and which)
--   HRTFs are applied, etc...
module Sound.OpenAL.AL.Listener

-- | <a>listenerPosition</a> contains the current location of the listener
--   in the world coordinate system. Any 3-tuple of valid float values is
--   allowed. Implementation behavior on encountering NaN and infinity is
--   not defined. The initial position is (<a>Vertex3</a> 0 0 0).
listenerPosition :: StateVar (Vertex3 ALfloat)

-- | <a>listenerVelocity</a> contains current velocity (speed and
--   direction) of the listener in the world coordinate system. Any 3-tuple
--   of valid float values is allowed, and the initial velocity is
--   (<a>Vector3</a> 0 0 0). <a>listenerVelocity</a> does not affect
--   <a>listenerPosition</a>. OpenAL does not calculate the velocity from
--   subsequent position updates, nor does it adjust the position over time
--   based on the specified velocity. Any such calculation is left to the
--   application. For the purposes of sound processing, position and
--   velocity are independent parameters affecting different aspects of the
--   sounds.
--   
--   <a>listenerVelocity</a> is taken into account by the driver to
--   synthesize the Doppler effect perceived by the listener for each
--   source, based on the velocity of both source and listener, and the
--   Doppler related parameters.
listenerVelocity :: StateVar (Vector3 ALfloat)

-- | A scalar amplitude multiplier.
type Gain = ALfloat

-- | <a>listenerGain</a> contains a scalar amplitude multiplier, which is
--   effectively applied to all sources in the current context. The initial
--   value 1 means that the sound is unattenuated. A <a>listenerGain</a>
--   value of 0.5 is equivalent to an attenuation of 6dB. The value zero
--   equals silence (no output). Driver implementations are free to
--   optimize this case and skip mixing and processing stages where
--   applicable. The implementation is in charge of ensuring artifact-free
--   (click-free) changes of gain values and is free to defer actual
--   modification of the sound samples, within the limits of acceptable
--   latencies.
--   
--   A <a>listenerGain</a> larger than 1 (amplification) is permitted.
--   However, the implementation is free to clamp the total gain (effective
--   gain per source times listener gain) to 1 to prevent overflow.
listenerGain :: StateVar Gain

-- | <a>orientation</a> contains an "at" vector and an "up" vector, where
--   the "at" vector represents the "forward" direction of the listener and
--   the orthogonal projection of the "up" vector into the subspace
--   perpendicular to the "at" vector represents the "up" direction for the
--   listener. OpenAL expects two vectors that are linearly independent.
--   These vectors are not expected to be normalized. If the two vectors
--   are linearly dependent, behavior is undefined. The initial orientation
--   is (<a>Vector3</a> 0 0 (-1), <a>Vector3</a> 0 1 0), i.e. looking down
--   the Z axis with the Y axis pointing upwards.
orientation :: StateVar (Vector3 ALfloat, Vector3 ALfloat)


-- | This module corresponds to section 3.1.2 (String Queries) and chapter
--   7 (Appendix: Extensions) of the OpenAL Specification and Reference
--   (version 1.1).
module Sound.OpenAL.AL.Extensions

-- | Contains the list of available extensions.
alExtensions :: GettableStateVar [String]

-- | To verify that a given extension is available for the current context,
--   use <a>alIsExtensionPresent</a>. For invalid and unsupported string
--   tokens it contains <a>False</a>. The extension name is not case
--   sensitive: The implementation will convert the name to all upper-case
--   internally (and will express extension names in upper-case).
alIsExtensionPresent :: String -> GettableStateVar Bool

-- | To retrieving function entry addresses, applications can use
--   <a>alProcAddress</a>. It contains <tt>nullFunPtr</tt> if no entry
--   point with the given name can be found. Implementations are free to
--   use <tt>nullFunPtr</tt> if an entry point is present, but not
--   applicable for the current context. However the specification does not
--   guarantee this behavior. Applications can use <a>alProcAddress</a> to
--   obtain core API entry points, not just extensions. This is the
--   recommended way to dynamically load and unload OpenAL DLLs as sound
--   drivers.
alProcAddress :: String -> GettableStateVar (FunPtr a)

-- | To obtain enumeration values for extensions, the application has to
--   use <a>alEnumValue</a> of an extension token. Enumeration values are
--   defined within the OpenAL name space and allocated according to
--   specification of the core API and the extensions, thus they are
--   context-independent.
--   
--   <a>alEnumValue</a> contains 0 if the enumeration can not be found. The
--   presence of an enum value does not guarantee the applicability of an
--   extension to the current context. A non-zero value indicates merely
--   that the implementation is aware of the existence of this extension.
--   Implementations should not attempt to use 0 to indicate that the
--   extensions is not supported for the current context.
alEnumValue :: String -> GettableStateVar ALenum

-- | Contains a version string in the format <tt>"<i>\&lt;spec major
--   number\&gt;</i>./&lt;spec minor number&gt;<i> </i>&lt;optional vendor
--   version information&gt;/"</tt>.
alVersion :: GettableStateVar String


-- | This module corresponds to section 3.5.2. (Velocity Dependent Doppler
--   Effect) of the OpenAL Specification and Reference (version 1.1).
module Sound.OpenAL.AL.Doppler

-- | <a>dopplerFactor</a> is a simple scaling of source and listener
--   velocities to exaggerate or deemphasize the Doppler (pitch) shift
--   resulting from the calculation. Setting <a>dopplerFactor</a> to a
--   negative value will result in an <tt>ALInvalidValue</tt> error, the
--   command is then ignored. The default value is 1. The implementation is
--   free to optimize the case of <a>dopplerFactor</a> containing zero, as
--   this effectively disables the effect.
dopplerFactor :: StateVar ALfloat

-- | <a>speedOfSound</a> allows the application to change the reference
--   (propagation) speed used in the Doppler calculation. The source and
--   listener velocities should be expressed in the same units as the speed
--   of sound. Setting <a>speedOfSound</a> to a negative or zero value will
--   result in an <tt>ALInvalidValue</tt> error, the command is ignored
--   then. The default value is 343.3 (appropriate for velocity units of
--   meters and air as the propagation medium).
speedOfSound :: StateVar ALfloat


-- | This module corresponds to sections 4.1 (Basic Listener and Source
--   Attributes) and 4.3 (Source Objects) of the OpenAL Specification and
--   Reference (version 1.1).
--   
--   Sources specify attributes like position, velocity, and a buffer with
--   sample data. By controlling a source's attributes the application can
--   modify and parameterize the static sample data provided by the buffer
--   referenced by the source. Sources define a localized sound, and
--   encapsulate a set of attributes applied to a sound at its origin, i.e.
--   in the very first stage of the processing on the way to the listener.
--   Source related effects have to be applied before listener related
--   effects unless the output is invariant to any collapse or reversal of
--   order. OpenAL also provides additional functions to manipulate and
--   query the execution state of sources: the current playing status of a
--   source, including access to the current sampling position within the
--   associated buffer.
module Sound.OpenAL.AL.Source

-- | The abstract buffer type.
data Source

-- | <a>sourcePosition</a> contains the current location of the source in
--   the world coordinate system. Any 3-tuple of valid float values is
--   allowed. Implementation behavior on encountering NaN and infinity is
--   not defined. The initial position is (<a>Vertex3</a> 0 0 0).
sourcePosition :: Source -> StateVar (Vertex3 ALfloat)

-- | <a>sourceVelocity</a> contains current velocity (speed and direction)
--   of the source in the world coordinate system. Any 3-tuple of valid
--   float values is allowed, and the initial velocity is (<a>Vector3</a> 0
--   0 0). <a>sourceVelocity</a> does not affect <a>sourcePosition</a>.
--   OpenAL does not calculate the velocity from subsequent position
--   updates, nor does it adjust the position over time based on the
--   specified velocity. Any such calculation is left to the application.
--   For the purposes of sound processing, position and velocity are
--   independent parameters affecting different aspects of the sounds.
--   
--   <a>sourceVelocity</a> is taken into account by the driver to
--   synthesize the Doppler effect perceived by the listener for each
--   source, based on the velocity of both source and listener, and the
--   Doppler related parameters.
sourceVelocity :: Source -> StateVar (Vector3 ALfloat)

-- | <a>sourceGain</a> contains a scalar amplitude multiplier for the given
--   source. The initial value 1 means that the sound is unattenuated. A
--   <a>sourceGain</a> value of 0.5 is equivalent to an attenuation of 6dB.
--   The value zero equals silence (no output). Driver implementations are
--   free to optimize this case and skip mixing and processing stages where
--   applicable. The implementation is in charge of ensuring artifact-free
--   (click-free) changes of gain values and is free to defer actual
--   modification of the sound samples, within the limits of acceptable
--   latencies.
--   
--   A <a>sourceGain</a> larger than 1 (amplification) is permitted.
--   However, the implementation is free to clamp the total gain (effective
--   gain per source times listener gain) to 1 to prevent overflow.
sourceGain :: Source -> StateVar Gain

-- | The entity to which the source attributes <a>sourcePosition</a>,
--   <a>sourceVelocity</a> and <a>direction</a> are to be interpreted.
data SourceRelative
World :: SourceRelative
Listener :: SourceRelative

-- | If <a>sourceRelative</a> contains <a>Listener</a>, it indicates
--   indicates that the values specified by <a>sourcePosition</a>,
--   <a>sourceVelocity</a> and <a>direction</a> are to be interpreted
--   relative to the listener position. The initial value is <a>World</a>,
--   indicating that those source attributes are to be interpreted relative
--   to the world, i.e. they are considered absolute.
sourceRelative :: Source -> StateVar SourceRelative

-- | When first created, a source will be in the <a>Undetermined</a> state.
--   If a buffer is then attached using <a>buffer</a>, then the source will
--   enter the <a>Static</a> state. If the first buffer attached to a
--   source is attached using <a>queueBuffers</a>, then the source will
--   enter the <a>Streaming</a> state. A source of either state will be
--   reset to state <a>Undetermined</a> by setting its <a>buffer</a> to
--   <a>Nothing</a>, and attaching any buffer to a streaming source will
--   change the state to <a>Static</a>. Attempting to queue a buffer on a
--   static source will result in an <tt>ALInvalidOperation</tt> error.
data SourceType
Undetermined :: SourceType
Static :: SourceType
Streaming :: SourceType

-- | <a>sourceType</a> indicates whether a source is ready to queue
--   buffers, ready to use a static buffer, or is in an undetermined state
--   where it can be used for either streaming or static playback.
sourceType :: Source -> GettableStateVar SourceType

-- | Specifies what should happen when the end of a buffer queue is
--   reached.
data LoopingMode
OneShot :: LoopingMode
Looping :: LoopingMode

-- | If <a>loopingMode</a> contains <a>Looping</a>, it indicates that the
--   source will not be in the <a>Stopped</a> state once it reaches the end
--   of last buffer in the buffer queue. Instead, the source will
--   immediately promote to <a>Initial</a> and <a>Playing</a>. The initial
--   value is <a>OneShot</a>. <a>loopingMode</a> can be changed on a source
--   in any execution state. In particular, it can be changed on a
--   <a>Playing</a> source.
loopingMode :: Source -> StateVar LoopingMode

-- | <a>buffer</a> contains the current buffer object. Setting
--   <a>buffer</a> to <a>Just</a> a buffer object makes it the head entry
--   in the source's queue. Setting <a>buffer</a>for a source in the
--   <a>Stopped</a> or <a>Initial</a> state empties the entire queue, then
--   appends the one buffer specified (or none at all if <a>Nothing</a> was
--   specified).
--   
--   For a source in the <a>Playing</a> or <a>Paused</a> state, setting
--   <a>buffer</a> will result in the <tt>ALInvalidOperation</tt> error
--   state being set. <a>buffer</a> can be applied only to sources in the
--   <a>Initial</a> and <a>Stopped</a> states. Specifying an invalid buffer
--   name (either because the buffer name doesn't exist or because that
--   buffer can't be attached to the specified source) will result in an
--   <tt>ALInvalidValue</tt> error while specifying an invalid source name
--   results in an <tt>ALInvalidName</tt> error. Setting <a>buffer</a> to
--   <a>Nothing</a> is a legal way to release the current buffer queue on a
--   source in the <a>Initial</a> or <a>Stopped</a> state, whether the
--   source has just one entry (current buffer) or more. Setting
--   <a>buffer</a> to <a>Nothing</a> still causes an
--   <tt>ALInvalidOperation</tt> for any source in the <a>Playing</a> or
--   <a>Paused</a> state, consequently it cannot be used to mute or stop a
--   source. The initial value is <a>Nothing</a>.
buffer :: Source -> StateVar (Maybe Buffer)

-- | <a>buffersQueued</a> contains the number of buffers in the queue of a
--   given source. This includes those not yet played, the one currently
--   playing, and the ones that have been played already. It will contain 0
--   if <a>buffer</a> has been set to <a>Nothing</a>.
buffersQueued :: Source -> GettableStateVar ALint

-- | <a>buffersProcessed</a> contains the number of buffers that have been
--   played by a given source. Indirectly, this gives the index of the
--   buffer currently playing. It can be used to determine how much slots
--   are needed for unqueuing them. On a source in the <a>Stopped</a>
--   state, all buffers are processed. On a source in the <a>Initial</a>
--   state, no buffers are processed, all buffers are pending. It will
--   contain 0 if <a>buffer</a> has been set to <a>Nothing</a>.
buffersProcessed :: Source -> GettableStateVar ALint

-- | <a>gainBounds</a> contains two scalar amplitude thresholds between 0
--   and 1 (included): The minimum guaranteed gain for this source and the
--   maximum gain permitted, with initial values 0 and 1, respectively At
--   the end of the processing of various attenuation factors such as
--   distance based attenuation and <a>sourceGain</a>, the effective gain
--   calculated is compared to these values:
--   
--   If the effective gain is lower than the minimum gain, the minimum gain
--   is applied. This happens before the <a>listenerGain</a> is applied. If
--   a zero minimum gain is set, then the effective gain will not be
--   corrected.
--   
--   If the effective gain is higher than the maximum gain, the maximum
--   gain is applied. This happens before the <a>listenerGain</a> is
--   applied. If the <a>listenerGain</a> times the maximum gain still
--   exceeds the maximum gain the implementation can handle, the
--   implementation is free to clamp. If a zero maximum gain is set, then
--   the source is effectively muted. The implementation is free to
--   optimize for this situation, but no optimization is required or
--   recommended as setting <a>sourceGain</a> to zero is the proper way to
--   mute a source.
gainBounds :: Source -> StateVar (Gain, Gain)

-- | <a>referenceDistance</a> is used for distance attenuation calculations
--   based on inverse distance with rolloff. Depending on the distance
--   model it will also act as a distance threshold below which gain is
--   clamped. See <a>Sound.OpenAL.AL.Attenuation</a> for details. The
--   initial value is 1.
referenceDistance :: Source -> StateVar ALfloat

-- | <a>rolloffFactor</a> is used for distance attenuation calculations
--   based on inverse distance with rolloff. For distances smaller than
--   <a>maxDistance</a> (and, depending on the distance model, larger than
--   <a>referenceDistance</a>), this will scale the distance attenuation
--   over the applicable range. See <a>Sound.OpenAL.AL.Attenuation</a> for
--   details how the attenuation is computed as a function of the distance.
--   The initial value is 1.
--   
--   In particular, <a>rolloffFactor</a> can be set to zero for those
--   sources that are supposed to be exempt from distance attenuation. The
--   implementation is encouraged to optimize this case, bypassing distance
--   attenuation calculation entirely on a persource basis.
rolloffFactor :: Source -> StateVar ALfloat

-- | <a>maxDistance</a> is used for distance attenuation calculations based
--   on inverse distance with rolloff, if the inverse clamped distance
--   model is used. In this case, distances greater than <a>maxDistance</a>
--   will be clamped to <a>maxDistance</a>. <a>maxDistance</a> based
--   clamping is applied before minimum gain clamping (see
--   <a>gainBounds</a>), so if the effective gain at <a>maxDistance</a> is
--   larger than the minimum gain, the minimum gain will have no effect. No
--   culling is supported. The initial value is the largest representable
--   <a>ALfloat</a>.
maxDistance :: Source -> StateVar ALfloat

-- | <a>pitch</a> contains the desired pitch shift, where 1 (the initial
--   value) equals identity. Each reduction by 50 percent equals a pitch
--   shift of -12 semitones (one octave reduction). Each doubling equals a
--   pitch shift of 12 semitones (one octave increase). Zero is not a legal
--   value. Implementations may clamp the actual output pitch range to any
--   values subject to the implementation's own limits.
pitch :: Source -> StateVar ALfloat

-- | If <a>direction</a> does not contain the zero vector (<a>Vector3</a> 0
--   0 0), the source is directional. The sound emission is presumed to be
--   symmetric around the direction vector (cylinder symmetry). Sources are
--   not oriented in full 3 degrees of freedom, only two angles are
--   effectively needed.
--   
--   The zero vector is the initial value, indicating that a source is not
--   directional. Specifying a non-zero vector will make the source
--   directional. Specifying a zero vector for a directional source will
--   effectively mark it as nondirectional.
direction :: Source -> StateVar (Vector3 ALfloat)

-- | <a>coneAngles</a> contains the inner and outer angles of the sound
--   cone, in degrees. The default of 360 for the inner cone angle means
--   that it covers the entire world, which is equivalent to an
--   omni-directional source. The default of 360 for the outer cone angle
--   means that it covers the entire world. If the inner angle is also 360,
--   then the zone for angle-dependent attenuation is zero.
coneAngles :: Source -> StateVar (ALfloat, ALfloat)

-- | <a>coneOuterGain</a> contains the factor with which <a>sourceGain</a>
--   is multiplied to determine the effective gain outside the cone defined
--   by the outer angle. The effective gain applied outside the outer cone
--   is <a>sourceGain</a> times <a>coneOuterGain</a>. Changing
--   <a>sourceGain</a> affects all directions, i.e. the source is
--   attenuated in all directions, for any position of the listener. The
--   application has to change <a>coneOuterGain</a> as well if a different
--   behavior is desired.
coneOuterGain :: Source -> StateVar Gain

-- | <a>secOffset</a> contains the playback position, expressed in seconds
--   (the value will loop back to zero for looping sources).
--   
--   When setting <a>secOffset</a> on a source which is already playing,
--   the playback will jump to the new offset unless the new offset is out
--   of range, in which case an <tt>ALInvalidValue</tt> error is set. If
--   the source is not playing, then the offset will be applied on the next
--   <a>play</a> call.
--   
--   The position is relative to the beginning of all the queued buffers
--   for the source, and any queued buffers traversed by a set call will be
--   marked as processed.
--   
--   This value is based on byte position, so a pitch-shifted source will
--   have an exaggerated playback speed. For example, you can be 0.5
--   seconds into a buffer having taken only 0.25 seconds to get there if
--   the pitch is set to 2.
secOffset :: Source -> StateVar ALfloat

-- | <a>sampleOffset</a> contains the playback position, expressed in
--   samples (the value will loop back to zero for looping sources). For a
--   compressed format, this value will represent an exact offset within
--   the uncompressed data.
--   
--   When setting <a>sampleOffset</a> on a source which is already playing,
--   the playback will jump to the new offset unless the new offset is out
--   of range, in which case an <tt>ALInvalidValue</tt> error is set. If
--   the source is not playing, then the offset will be applied on the next
--   <a>play</a> call. A <a>stop</a>, <a>rewind</a>, or a second
--   <a>play</a> call will reset the offset to the beginning of the buffer.
--   
--   The position is relative to the beginning of all the queued buffers
--   for the source, and any queued buffers traversed by a set call will be
--   marked as processed.
sampleOffset :: Source -> StateVar ALint

-- | <a>byteOffset</a> contains the playback position, expressed in bytes
--   (the value will loop back to zero for looping sources). For a
--   compressed format, this value may represent an approximate offset
--   within the compressed data buffer.
--   
--   When setting <a>byteOffset</a> on a source which is already playing,
--   the playback will jump to the new offset unless the new offset is out
--   of range, in which case an <tt>ALInvalidValue</tt> error is set. If
--   the source is not playing, then the offset will be applied on the next
--   <a>play</a> call. A <a>stop</a>, <a>rewind</a>, or a second
--   <a>play</a> call will reset the offset to the beginning of the buffer.
--   
--   The position is relative to the beginning of all the queued buffers
--   for the source, and any queued buffers traversed by a set call will be
--   marked as processed.
byteOffset :: Source -> StateVar ALint

-- | The application can queue up one or multiple buffer names using
--   <a>queueBuffers</a>. The buffers will be queued in the sequence in
--   which they appear in the list.
--   
--   This command is legal on a source in any playback state (to allow for
--   streaming, queuing has to be possible on a <a>Playing</a> source).
--   
--   All buffers in a queue must have the same format and attributes. An
--   attempt to mix formats or other buffer attributes will result in a
--   failure and an <tt>ALInvalidValue</tt> error will be thrown. If the
--   queue operation fails, the source queue will remain unchanged (even if
--   some of the buffers could have been queued).
queueBuffers :: Source -> [Buffer] -> IO ()

-- | Once a queue entry for a buffer has been appended to a queue and is
--   pending processing, it should not be changed. Removal of a given queue
--   entry is not possible unless either the source is stopped (in which
--   case then entire queue is considered processed), or if the queue entry
--   has already been processed (<a>Playing</a> or <a>Paused</a> source). A
--   playing source will enter the <a>Stopped</a> state if it completes
--   playback of the last buffer in its queue (the same behavior as when a
--   single buffer has been attached to a source and has finished
--   playback).
--   
--   The <a>unqueueBuffers</a> command removes a number of buffers entries
--   that have finished processing, in the order of appearance, from the
--   queue. The operation will fail with an <tt>ALInvalidValue</tt> error
--   if more buffers are requested than available, leaving the destination
--   arguments unchanged.
unqueueBuffers :: Source -> [Buffer] -> IO ()

-- | Each source can be in one of four possible execution states:
--   <a>Initial</a>, <a>Playing</a>, <a>Paused</a>, <a>Stopped</a>. Sources
--   that are either <a>Playing</a> or <a>Paused</a> are considered active.
--   Sources that are <a>Stopped</a> or <a>Initial</a> are considered
--   inactive. Only <a>Playing</a> sources are included in the processing.
--   The implementation is free to skip those processing stages for sources
--   that have no effect on the output (e.g. mixing for a source muted by
--   zero gain, but not sample offset increments). Depending on the current
--   state of a source certain (e.g. repeated) state transition commands
--   are legal NOPs: they will be ignored, no error is generated.
data SourceState
Initial :: SourceState
Playing :: SourceState
Paused :: SourceState
Stopped :: SourceState

-- | Contains the current execution state of the given source. The initial
--   state of any source is <a>Initial</a>.
--   
--   Note that the <a>Initial</a> state is not necessarily identical to the
--   initial state in which a source is created, because the other source
--   attributes are not automatically reset to their initial values.
--   <a>Initial</a> merely indicates that the source can be executed using
--   the <a>play</a> command. A <a>Stopped</a> or <a>Initial</a> source can
--   be reset into the default configuration by using a sequence of source
--   commands as necessary. As the application has to specify all relevant
--   state anyway to create a useful source configuration, no reset command
--   is provided.
sourceState :: Source -> GettableStateVar SourceState

-- | <a>play</a> applied to an <a>Initial</a> source will promote the
--   source to <a>Playing</a>, thus the data found in the buffer will be
--   fed into the processing, starting at the beginning. <a>play</a>
--   applied to a <a>Playing</a> source will restart the source from the
--   beginning. It will not affect the configuration, and will leave the
--   source in <a>Playing</a> state, but reset the sampling offset to the
--   beginning. <a>play</a> applied to a <a>Paused</a> source will resume
--   processing using the source state as preserved at the <a>pause</a>
--   operation. <a>play</a> applied to a <a>Stopped</a> source will
--   propagate it to <a>Initial</a> then to <a>Playing</a> immediately.
play :: [Source] -> IO ()

-- | <a>pause</a> applied to an <a>Initial</a> source is a legal NOP.
--   <a>pause</a> applied to a <a>Playing</a> source will change its state
--   to <a>Paused</a>. The source is exempt from processing, its current
--   state is preserved. <a>pause</a> applied to a <a>Paused</a> source is
--   a legal NOP. <a>pause</a> applied to a <a>Stopped</a> source is a
--   legal NOP.
pause :: [Source] -> IO ()

-- | <a>stop</a> applied to an <a>Initial</a> source is a legal NOP.
--   <a>stop</a> applied to a <a>Playing</a> source will change its state
--   to <a>Stopped</a>. The source is exempt from processing, its current
--   state is preserved. <a>stop</a> applied to a <a>Paused</a> source will
--   change its state to <a>Stopped</a>, with the same consequences as on a
--   <a>Playing</a> source. <a>stop</a> applied to a <a>Stopped</a> source
--   is a legal NOP.
stop :: [Source] -> IO ()

-- | <a>rewind</a> applied to an <a>Initial</a> source is a legal NOP.
--   <a>rewind</a> applied to a <a>Playing</a> source will change its state
--   to <a>Stopped</a> then <a>Initial</a>. The source is exempt from
--   processing: its current state is preserved, with the exception of the
--   sampling offset, which is reset to the beginning. <a>rewind</a>
--   applied to a <a>Paused</a> source will change its state to
--   <a>Initial</a>, with the same consequences as on a <a>Playing</a>
--   source. <a>rewind</a> applied to an <a>Stopped</a> source promotes the
--   source to <a>Initial</a>, resetting the sampling offset to the
--   beginning.
rewind :: [Source] -> IO ()
instance Eq Source
instance Ord Source
instance Show Source
instance Eq SourceRelative
instance Ord SourceRelative
instance Show SourceRelative
instance Eq SourceType
instance Ord SourceType
instance Show SourceType
instance Eq LoopingMode
instance Ord LoopingMode
instance Show LoopingMode
instance ObjectName Source
instance Storable Source


-- | This module corresponds to chapter 6 (AL Contexts and the ALC API) of
--   the OpenAL Specification and Reference (version 1.1).
--   
--   ALC is a portable API for managing OpenAL contexts, including resource
--   sharing, locking, and unlocking. Within the core AL API the existence
--   of a context is implied, but the context is not exposed. The context
--   encapsulates the state of a given instance of the AL state machine.
module Sound.OpenAL.ALC


-- | 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


-- | A convenience module, combining the Haskell bindings for AL and ALC.
module Sound.OpenAL
