Sound.OpenAL.AL.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:

unused

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.

processed

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.

pending

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.

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.

Documentation

data Buffer

The abstract buffer type.

Instances

Eq Buffer

Defined in Sound.OpenAL.AL.BufferInternal

Methods

(==) :: Buffer -> Buffer -> Bool

(/=) :: Buffer -> Buffer -> Bool

Ord Buffer

Defined in Sound.OpenAL.AL.BufferInternal

Methods

compare :: Buffer -> Buffer -> Ordering

(<) :: Buffer -> Buffer -> Bool

(<=) :: Buffer -> Buffer -> Bool

(>) :: Buffer -> Buffer -> Bool

(>=) :: Buffer -> Buffer -> Bool

max :: Buffer -> Buffer -> Buffer

min :: Buffer -> Buffer -> Buffer

Show Buffer

Defined in Sound.OpenAL.AL.BufferInternal

Methods

showsPrec :: Int -> Buffer -> ShowS

show :: Buffer -> String

showList :: [Buffer] -> ShowS

ObjectName Buffer

Defined in Sound.OpenAL.AL.BufferInternal

Methods

isObjectName :: MonadIO m => Buffer -> m Bool

deleteObjectName :: MonadIO m => Buffer -> m ()

deleteObjectNames :: MonadIO m => [Buffer] -> m ()

GeneratableObjectName Buffer

Defined in Sound.OpenAL.AL.BufferInternal

Methods

genObjectName :: MonadIO m => m Buffer

genObjectNames :: MonadIO m => Int -> m [Buffer]

Storable Buffer

Defined in Sound.OpenAL.AL.BufferInternal

Methods

sizeOf :: Buffer -> Int

alignment :: Buffer -> Int

peekElemOff :: Ptr Buffer -> Int -> IO Buffer

pokeElemOff :: Ptr Buffer -> Int -> Buffer -> IO ()

peekByteOff :: Ptr b -> Int -> IO Buffer

pokeByteOff :: Ptr b -> Int -> Buffer -> IO ()

peek :: Ptr Buffer -> IO Buffer

poke :: Ptr Buffer -> Buffer -> IO ()

data MemoryRegion a

Constructors

MemoryRegion (Ptr a) ALsizei

Instances

Eq (MemoryRegion a)

Defined in Sound.OpenAL.AL.Buffer

Methods

(==) :: MemoryRegion a -> MemoryRegion a -> Bool

(/=) :: MemoryRegion a -> MemoryRegion a -> Bool

Ord (MemoryRegion a)

Defined in Sound.OpenAL.AL.Buffer

Methods

compare :: MemoryRegion a -> MemoryRegion a -> Ordering

(<) :: MemoryRegion a -> MemoryRegion a -> Bool

(<=) :: MemoryRegion a -> MemoryRegion a -> Bool

(>) :: MemoryRegion a -> MemoryRegion a -> Bool

(>=) :: MemoryRegion a -> MemoryRegion a -> Bool

max :: MemoryRegion a -> MemoryRegion a -> MemoryRegion a

min :: MemoryRegion a -> MemoryRegion a -> MemoryRegion a

Show (MemoryRegion a)

Defined in Sound.OpenAL.AL.Buffer

Methods

showsPrec :: Int -> MemoryRegion a -> ShowS

show :: MemoryRegion a -> String

showList :: [MemoryRegion a] -> ShowS

data Format

Valid sound formats. An implementation may expose other formats, see Sound.OpenAL.ALC.Extensions for information on determining if additional formats are supported.

Constructors

Mono8

Mono16

Stereo8

Stereo16

Instances

Eq Format

Defined in Sound.OpenAL.AL.Format

Methods

(==) :: Format -> Format -> Bool

(/=) :: Format -> Format -> Bool

Ord Format

Defined in Sound.OpenAL.AL.Format

Methods

compare :: Format -> Format -> Ordering

(<) :: Format -> Format -> Bool

(<=) :: Format -> Format -> Bool

(>) :: Format -> Format -> Bool

(>=) :: Format -> Format -> Bool

max :: Format -> Format -> Format

min :: Format -> Format -> Format

Show Format

Defined in Sound.OpenAL.AL.Format

Methods

showsPrec :: Int -> Format -> ShowS

show :: Format -> String

showList :: [Format] -> ShowS

data BufferData a

Constructors

BufferData (MemoryRegion a) Format Frequency

Instances

Eq (BufferData a)

Defined in Sound.OpenAL.AL.Buffer

Methods

(==) :: BufferData a -> BufferData a -> Bool

(/=) :: BufferData a -> BufferData a -> Bool

Ord (BufferData a)

Defined in Sound.OpenAL.AL.Buffer

Methods

compare :: BufferData a -> BufferData a -> Ordering

(<) :: BufferData a -> BufferData a -> Bool

(<=) :: BufferData a -> BufferData a -> Bool

(>) :: BufferData a -> BufferData a -> Bool

(>=) :: BufferData a -> BufferData a -> Bool

max :: BufferData a -> BufferData a -> BufferData a

min :: BufferData a -> BufferData a -> BufferData a

Show (BufferData a)

Defined in Sound.OpenAL.AL.Buffer

Methods

showsPrec :: Int -> BufferData a -> ShowS

show :: BufferData a -> String

showList :: [BufferData a] -> ShowS

bufferData :: Buffer -> StateVar (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.