| OpenAL-1.3.1.1: A binding to the OpenAL cross-platform 3D audio API | Source code | Contents | Index

Sound.OpenAL.ALC.Context

Portability | portable
Stability | provisional
Maintainer | sven.panne@aedion.de

Description

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.

Synopsis

type Frequency = Float

data ContextAttribute

= Frequency Frequency
| Refresh Frequency
| Sync Bool
| MonoSources Int
| StereoSources Int

data Context
createContext :: Device -> [ContextAttribute] -> IO (Maybe Context)
currentContext :: StateVar (Maybe Context)
processContext :: Context -> IO ()
suspendContext :: Context -> IO ()
destroyContext :: Context -> IO ()
contextsDevice :: Context -> GettableStateVar (Maybe Device)
allAttributes :: Device -> GettableStateVar [ContextAttribute]

Documentation

type Frequency = Float | Source

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.

data ContextAttribute | Source

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

Frequency Frequency | Frequency for mixing output buffer, in units of Hz
Refresh Frequency | Refresh intervals, in units of Hz
Sync Bool | Flag, indicating a synchronous context
MonoSources Int | A hint indicating how many sources should be capable of supporting mono data
StereoSources Int | A hint indicating how many sources should be capable of supporting stereo data

Instances

Eq ContextAttribute
Ord ContextAttribute
Show ContextAttribute

data Context | Source

The abstract context type.
Instances

Eq Context
Ord Context
Show Context

createContext :: Device -> [ContextAttribute] -> IO (Maybe Context) | Source

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

currentContext :: StateVar (Maybe Context) | Source

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.

processContext :: Context -> IO () | Source

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.

suspendContext :: Context -> IO () | Source

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.

destroyContext :: Context -> IO () | Source

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.

contextsDevice :: Context -> GettableStateVar (Maybe Device) | Source

Contains `Just` the device of the given context or `Nothing` if the context is invalid.

allAttributes :: Device -> GettableStateVar [ContextAttribute] | Source

Contains the attribute list for the current context of the specified device.
Produced by Haddock version 0.9