-- 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: -- http://www.openal.org/. @package OpenAL @version 1.3 -- | 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 ALCboolean, ALCchar, -- 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 -- | openDevice allows the application (i.e. the client program) to -- connect to a device (i.e. the server). If the function returns -- Nothing, then no sound driver/device has been found. The -- argument to openDevice specifies a certain device or device -- configuration. If it is Nothing, the implementation will -- provide an implementation specific default, see -- defaultDeviceSpecifier. Otherwise it is Just an -- implementation-dependent string. You can use -- allDeviceSpecifiers to get a list of the known OpenAL devices. -- -- Notes for Windows: There are 3 possible device strings, each -- having a deprecated equivalent for legacy applications only: -- -- -- -- Notes for Linux\*nix:/ If an .openalrc file is present -- in the user's home directory, it is loaded first, otherwise -- /etc/openalrc is tried. The bindings (if any) of -- devices, direction, sampling-rate, and -- speaker-num (see below) after loading one of these files take -- precedence over any bindings done via the argument to -- openDevice. -- -- The syntax of these files is lisp-based and a sequence of expressions, -- where an expression is one the following: -- -- -- -- Some symbols have a special meaning for OpenAL: -- -- -- -- The string given to openDevice has to be of the form -- '((symbol expression) ...), which means -- basically a sequence of define expressions. Example: -- -- 
--   "'((sampling-rate 8000) (native-backend-debug #f))"
--
-- -- Note: 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) -- | closeDevice allows the application (i.e. the client program) to -- disconnect from a device (i.e. the server). It returns True for -- success and False for failure. Once closed, the Device -- is invalid. -- -- Note: Older OpenAL implementations will always report a -- success! closeDevice :: Device -> IO Bool -- | Contains Just the specifier string for the default device or -- Nothing 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, Nothing will be returned, otherwise Just the new -- context. Note that createContext does not set the -- current context, this must be done separately via -- currentContext. createContext :: Device -> [ContextAttribute] -> IO (Maybe Context) -- | Contains Just the current context with respect to OpenAL -- operation, or Nothing 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 processContext. Repeated calls to -- processContext are legal, and do not affect a context that is -- already marked as processing. The default state of a context created -- by createContext 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 -- suspendContext. Repeated calls to suspendContext 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 currentContext to -- Nothing. Applications should not attempt to destroy a current -- context, doing so will not work and will result in an -- ALCInvalidOperation error. destroyContext :: Context -> IO () -- | Contains Just the device of the given context or Nothing -- 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 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 alcErrors 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 alcErrors 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 alcErrors returns [] then -- there has been no detectable error since the last time -- alcErrors (or since the ALC was initialized). -- -- When an error flag is set, results of ALC operations are undefined -- only if ALCOutOfMemory 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 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 -- alcIsExtensionPresent. For invalid and unsupported string -- tokens it contains False. Using Nothing 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 alcIsExtensionPresent. Extension entry points can be -- retrieved using alcProcAddress. Entry points can be device -- specific, but are not context specific. Using Nothing 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 -- Nothing 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 "major.minor" specification revision for -- this implementation. alcVersion :: GettableStateVar String -- | 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 Format. module Sound.OpenAL.AL.Format -- | Valid sound formats. An implementation may expose other formats, see -- Sound.OpenAL.ALC.Extensions 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 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 alErrors 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 -- alErrors is read, the error is returned and the flag is -- cleared, so that a further error will again record its code. If -- reading alErrors returns [] then there has been no -- detectable error since the last time alErrors (or since the AL -- was initialized). -- -- When an error flag is set, results of AL operations are undefined only -- if ALOutOfMemory 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 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 -- | listenerPosition 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 (Vertex3 0 0 0). listenerPosition :: StateVar (Vertex3 ALfloat) -- | listenerVelocity 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 -- (Vector3 0 0 0). listenerVelocity does not affect -- listenerPosition. 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. -- -- listenerVelocity 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 -- | listenerGain 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 listenerGain -- 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 listenerGain 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 -- | orientation 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 (Vector3 0 0 (-1), Vector3 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) 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 referenceDistance and maxDistance: -- -- clamped distance = max(referenceDistance, min(distance, -- maxDistance)) -- -- 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 referenceDistance equal to maxDistance, 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 referenceDistance does not imply any -- clamping. -- -- gain = referenceDistance / (referenceDistance + rolloffFactor * -- (distance - referenceDistance)) -- -- The referenceDistance 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). rolloffFactor 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 rolloffFactor -- 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 -- referenceDistance, 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. -- -- gain = (1 - rolloffFactor * (distance - -- referenceDistance) / (maxDistance - referenceDistance)) LinearDistance :: DistanceModel -- | Linear Distance clamped model, which is the linear model, extended to -- guarantee that for distances below referenceDistance, gain is clamped. LinearDistanceClamped :: DistanceModel -- | Exponential distance rolloff model, modeling an exponential dropoff in -- gain as distance increases between the source and listener. -- -- gain = (distance / referenceDistance) ** (- -- rolloffFactor) ExponentDistance :: DistanceModel -- | Exponential Distance clamped model, which is the exponential model, -- extended to guarantee that for distances below referenceDistance, 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 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. data Buffer marshalBuffer :: Maybe Buffer -> ALuint unmarshalBuffer :: ALuint -> Maybe Buffer instance Eq Buffer instance Ord Buffer instance Show Buffer instance ObjectName Buffer instance Storable Buffer -- | 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 Sound.OpenAL.AL.Source) and listener (see -- Sound.OpenAL.AL.Listener) 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: -- -- -- -- 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 unused to processed -- or higher. Sources that are in the Stopped or Initial states still -- have queue entries that cause buffers to be processed. -- -- A single queue entry with a single source for which the buffer is not -- yet processed propagates the buffer's queuing state to -- pending. -- -- Buffers that are processed for a given source can be unqueued -- from that source's queue. Buffers that have been unqueued from all -- sources are unused. Buffers that are unused can be -- deleted, or changed by writing bufferData. 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 -- Sound.OpenAL.ALC.Extensions 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 bufferData. -- -- 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 ALOutOfMemory or a conversion -- related ALInvalidValue error. The application is free to reuse the -- memory specified by the data pointer once bufferData is set. -- The implementation has to dereference, e.g. copy, the data while -- accessing bufferData execution. bufferData :: Buffer -> StateVar (BufferData a) instance Eq (BufferData a) instance Ord (BufferData a) instance Show (BufferData a) instance Eq (MemoryRegion a) instance Ord (MemoryRegion a) instance Show (MemoryRegion 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 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 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 alIsExtensionPresent. For invalid and unsupported string -- tokens it contains False. 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 -- alProcAddress. It contains nullFunPtr if no entry point with -- the given name can be found. Implementations are free to use -- nullFunPtr if an entry point is present, but not applicable for the -- current context. However the specification does not guarantee this -- behavior. Applications can use alProcAddress 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 alEnumValue 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. -- -- alEnumValue 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 "\<spec major -- number\>./<spec minor number> <optional vendor -- version information>/". 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 -- | dopplerFactor is a simple scaling of source and listener -- velocities to exaggerate or deemphasize the Doppler (pitch) shift -- resulting from the calculation. Setting dopplerFactor to a -- negative value will result in an ALInvalidValue error, the command is -- then ignored. The default value is 1. The implementation is free to -- optimize the case of dopplerFactor containing zero, as this -- effectively disables the effect. dopplerFactor :: StateVar ALfloat -- | speedOfSound 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 speedOfSound to a negative or zero value will -- result in an ALInvalidValue 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 -- | sourcePosition 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 (Vertex3 0 0 0). sourcePosition :: Source -> StateVar (Vertex3 ALfloat) -- | sourceVelocity 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 (Vector3 0 -- 0 0). sourceVelocity does not affect sourcePosition. -- 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. -- -- sourceVelocity 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) -- | sourceGain contains a scalar amplitude multiplier for the given -- source. The initial value 1 means that the sound is unattenuated. A -- sourceGain 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 sourceGain 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 sourcePosition, -- sourceVelocity and direction are to be interpreted. data SourceRelative World :: SourceRelative Listener :: SourceRelative -- | If sourceRelative contains Listener, it indicates -- indicates that the values specified by sourcePosition, -- sourceVelocity and direction are to be interpreted -- relative to the listener position. The initial value is World, -- 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 Undetermined state. -- If a buffer is then attached using buffer, then the source will -- enter the Static state. If the first buffer attached to a -- source is attached using queueBuffers, then the source will -- enter the Streaming state. A source of either state will be -- reset to state Undetermined by setting its buffer to -- Nothing, and attaching any buffer to a streaming source will -- change the state to Static. Attempting to queue a buffer on a -- static source will result in an ALInvalidOperation error. data SourceType Undetermined :: SourceType Static :: SourceType Streaming :: SourceType -- | sourceType 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 loopingMode contains Looping, it indicates that the -- source will not be in the Stopped state once it reaches the end -- of last buffer in the buffer queue. Instead, the source will -- immediately promote to Initial and Playing. The initial -- value is OneShot. loopingMode can be changed on a source -- in any execution state. In particular, it can be changed on a -- Playing source. loopingMode :: Source -> StateVar LoopingMode -- | buffer contains the current buffer object. Setting -- buffer to Just a buffer object makes it the head entry -- in the source's queue. Setting bufferfor a source in the -- Stopped or Initial state empties the entire queue, then -- appends the one buffer specified (or none at all if Nothing was -- specified). -- -- For a source in the Playing or Paused state, setting -- buffer will result in the ALInvalidOperation error state being -- set. buffer can be applied only to sources in the -- Initial and Stopped 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 -- ALInvalidValue error while specifying an invalid source name results -- in an ALInvalidName error. Setting buffer to Nothing is -- a legal way to release the current buffer queue on a source in the -- Initial or Stopped state, whether the source has just -- one entry (current buffer) or more. Setting buffer to -- Nothing still causes an ALInvalidOperation for any source in -- the Playing or Paused state, consequently it cannot be -- used to mute or stop a source. The initial value is Nothing. buffer :: Source -> StateVar (Maybe Buffer) -- | buffersQueued 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 buffer has been set to Nothing. buffersQueued :: Source -> GettableStateVar ALint -- | buffersProcessed 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 Stopped -- state, all buffers are processed. On a source in the Initial -- state, no buffers are processed, all buffers are pending. It will -- contain 0 if buffer has been set to Nothing. buffersProcessed :: Source -> GettableStateVar ALint -- | gainBounds 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 sourceGain, 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 listenerGain 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 listenerGain is applied. If -- the listenerGain 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 sourceGain -- to zero is the proper way to mute a source. gainBounds :: Source -> StateVar (Gain, Gain) -- | referenceDistance 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 Sound.OpenAL.AL.Attenuation for details. The -- initial value is 1. referenceDistance :: Source -> StateVar ALfloat -- | rolloffFactor is used for distance attenuation calculations -- based on inverse distance with rolloff. For distances smaller than -- maxDistance (and, depending on the distance model, larger than -- referenceDistance), this will scale the distance attenuation -- over the applicable range. See Sound.OpenAL.AL.Attenuation for -- details how the attenuation is computed as a function of the distance. -- The initial value is 1. -- -- In particular, rolloffFactor 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 -- | maxDistance 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 maxDistance -- will be clamped to maxDistance. maxDistance based -- clamping is applied before minimum gain clamping (see -- gainBounds), so if the effective gain at maxDistance is -- larger than the minimum gain, the minimum gain will have no effect. No -- culling is supported. The initial value is the largest representable -- ALfloat. maxDistance :: Source -> StateVar ALfloat -- | pitch 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 direction does not contain the zero vector (Vector3 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) -- | coneAngles 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) -- | coneOuterGain contains the factor with which sourceGain -- is multiplied to determine the effective gain outside the cone defined -- by the outer angle. The effective gain applied outside the outer cone -- is sourceGain times coneOuterGain. Changing -- sourceGain affects all directions, i.e. the source is -- attenuated in all directions, for any position of the listener. The -- application has to change coneOuterGain as well if a different -- behavior is desired. coneOuterGain :: Source -> StateVar Gain -- | secOffset contains the playback position, expressed in seconds -- (the value will loop back to zero for looping sources). -- -- When setting secOffset 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 ALInvalidValue error is set. If the source -- is not playing, then the offset will be applied on the next -- play 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 -- | sampleOffset 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 sampleOffset 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 ALInvalidValue error is set. If the source -- is not playing, then the offset will be applied on the next -- play call. A stop, rewind, or a second -- play 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 -- | byteOffset 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 byteOffset 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 ALInvalidValue error is set. If the source -- is not playing, then the offset will be applied on the next -- play call. A stop, rewind, or a second -- play 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 -- queueBuffers. 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 Playing 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 ALInvalidValue 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 (Playing or Paused source). A -- playing source will enter the Stopped 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 unqueueBuffers 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 ALInvalidValue 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: -- Initial, Playing, Paused, Stopped. Sources -- that are either Playing or Paused are considered active. -- Sources that are Stopped or Initial are considered -- inactive. Only Playing 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 Initial. -- -- Note that the Initial 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. -- Initial merely indicates that the source can be executed using -- the play command. A Stopped or Initial 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 -- | play applied to an Initial source will promote the -- source to Playing, thus the data found in the buffer will be -- fed into the processing, starting at the beginning. play -- applied to a Playing source will restart the source from the -- beginning. It will not affect the configuration, and will leave the -- source in Playing state, but reset the sampling offset to the -- beginning. play applied to a Paused source will resume -- processing using the source state as preserved at the pause -- operation. play applied to a Stopped source will -- propagate it to Initial then to Playing immediately. play :: [Source] -> IO () -- | pause applied to an Initial source is a legal NOP. -- pause applied to a Playing source will change its state -- to Paused. The source is exempt from processing, its current -- state is preserved. pause applied to a Paused source is -- a legal NOP. pause applied to a Stopped source is a -- legal NOP. pause :: [Source] -> IO () -- | stop applied to an Initial source is a legal NOP. -- stop applied to a Playing source will change its state -- to Stopped. The source is exempt from processing, its current -- state is preserved. stop applied to a Paused source will -- change its state to Stopped, with the same consequences as on a -- Playing source. stop applied to a Stopped source -- is a legal NOP. stop :: [Source] -> IO () -- | rewind applied to an Initial source is a legal NOP. -- rewind applied to a Playing source will change its state -- to Stopped then Initial. The source is exempt from -- processing: its current state is preserved, with the exception of the -- sampling offset, which is reset to the beginning. rewind -- applied to a Paused source will change its state to -- Initial, with the same consequences as on a Playing -- source. rewind applied to an Stopped source promotes the -- source to Initial, resetting the sampling offset to the -- beginning. rewind :: [Source] -> IO () instance Eq LoopingMode instance Ord LoopingMode instance Show LoopingMode instance Eq SourceType instance Ord SourceType instance Show SourceType instance Eq SourceRelative instance Ord SourceRelative instance Show SourceRelative instance Eq Source instance Ord Source instance Show Source instance ObjectName Source instance Storable Source -- | 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