SFXBuffer

Engine/source/sfx/sfxBuffer.h

Inheritance diagram for SFXBuffer ↕

The buffer interface hides the details of how the device holds sound data for playback.

More...

Classes:

class

SFXBuffer::AsyncState

Encapsulates the async I/O state of the sound buffer.

Public Types

enum

Status {
  STATUS_Null 
  STATUS_Loading 
  STATUS_Ready 
  STATUS_Blocked 
  STATUS_AtEnd 
}

Status indicators for sound buffers.

void

Parent

Protected Types

ThreadSafeRef< AsyncState >

AsyncStatePtr

SFXInternal::SFXAsyncQueue *

SFXAsyncQueuePtr

ThreadSafeRef< SFXInternal::SFXAsyncStream >

SFXAsyncStreamPtr

Public Friends

void

SFXInternal::PurgeDeadBuffers

class

SFXVoice

Public Static Attributes

Signal< void(SFXBuffer *) >

smBufferDestroyedSignal

This signal is triggered from SFXBuffer's destructor so the sound system can keep track of buffers being released on the device.

Protected Attributes

AsyncStatePtr

mAsyncState

Pointer to structure keeping the asynchronous I/O state of the buffer.

U32

mDuration

Total playback time of the associated sound stream in milliseconds.

SFXFormat

mFormat

The sound sample format used by the buffer.

bool

mIsDead

If true, the buffer is dead and will be deleted.

bool

mIsLooping

For streaming buffers, tells whether the source stream loops.

bool

mIsStreaming

If true, this is a continuously streaming buffer.

bool

mIsUnique

If true, this buffer can only have a single SFXVoice attached.

Status

mStatus

The buffer readiness status.

StrongWeakRefPtr< SFXVoice >

mUniqueVoice

If this is a unique buffer (i.e.

Public Attributes

Signal< void(SFXBuffer *buffer, Status newStatus) >

mOnStatusChange

Signal that is triggered when the buffer status changes.

Protected Functions

SFXBuffer(const ThreadSafeRef< SFXStream > & stream, SFXDescription * description, bool createAsyncState)

Create a new buffer from stream using the parameters in description.

SFXBuffer(SFXDescription * description)

Create a buffer with just a description.

~SFXBuffer()

void

_flush()

Flush all queue state for this buffer on the device.

void

_setStatus(Status status)

Set the buffer status and trigger mOnStatusChange if the status changes.

Public Functions

void

destroySelf()

object destroy self call (from StrongRefPtr). Override if this class has specially allocated memory.

U32

getDuration()

const SFXFormat &

getFormat()

U32

getMemoryUsed()

U32

getNumSamples()

Status

getStatus()

bool

isAtEnd()

bool

isBlocked()

bool

isDead()

bool

isLoading()

bool

isReady()

bool

isStreaming()

bool

isUnique()

void

load()

Start the async request chain for the buffer.

bool

update()

Update the object state.

Detailed Description

The buffer interface hides the details of how the device holds sound data for playback.

A sound buffer may either be loaded once completely and then played as needed or it may be progressively streamed from an SFXStream. In the latter case, there can only be a single voice tied to the buffer.

note:
SFXDevice is the last instance when it comes to ownership of SFXBuffers. If the SFXDevice goes away, it will take all SFXBuffers with it, regardless of whether there are still strong refs to it. Use StrongWeakRefPtrs to keep pointers to SFXBuffers!

see:

SFXStream

Public Types

Status

Enumerator

STATUS_Null: Initial state.
STATUS_Loading: Buffer has requested data and is waiting for queue to fill up.
STATUS_Ready: Playback queue is fed and ready (non-stream buffers will stop at this state).
STATUS_Blocked: Queue is starved and playback thus held until further data is available (streaming buffers only).
STATUS_AtEnd: Buffer has read all its streaming data (streaming buffers only).

Status indicators for sound buffers.

typedef void Parent

Protected Types

typedef ThreadSafeRef< AsyncState > AsyncStatePtr

typedef SFXInternal::SFXAsyncQueue * SFXAsyncQueuePtr

typedef ThreadSafeRef< SFXInternal::SFXAsyncStream > SFXAsyncStreamPtr

Public Friends

Public Static Attributes

Signal< void(SFXBuffer *) > smBufferDestroyedSignal

This signal is triggered from SFXBuffer's destructor so the sound system can keep track of buffers being released on the device.

Protected Attributes

AsyncStatePtr mAsyncState

Pointer to structure keeping the asynchronous I/O state of the buffer.

For non-streaming buffers, this is released as soon as all data is loaded.

To allow seeking in streaming buffers even after playback has ended, we do not release the async state of these buffers until the buffer is actually released itself. This allows to always access the associated input stream.

note:
For devices that handle loading/streaming on their own, this will not be set.

U32 mDuration

Total playback time of the associated sound stream in milliseconds.

note:
For streaming buffers, this will not correspond to the actual playtime of the device buffer.

SFXFormat mFormat

The sound sample format used by the buffer.

bool mIsDead

If true, the buffer is dead and will be deleted.

Can't be in status for synchronization reasons.

bool mIsLooping

For streaming buffers, tells whether the source stream loops.

bool mIsStreaming

If true, this is a continuously streaming buffer.

bool mIsUnique

If true, this buffer can only have a single SFXVoice attached.

Status mStatus

The buffer readiness status.

StrongWeakRefPtr< SFXVoice > mUniqueVoice

If this is a unique buffer (i.e.

a streaming buffer), then this holds the reference to the unique voice.

Public Attributes

Signal< void(SFXBuffer *buffer, Status newStatus) > mOnStatusChange

Signal that is triggered when the buffer status changes.

note:
This signal is triggered on the same thread that the buffer update code runs on.

Protected Functions

SFXBuffer(const ThreadSafeRef< SFXStream > & stream, SFXDescription * description, bool createAsyncState)

Create a new buffer from stream using the parameters in description.

Parameters:

stream	Sound stream from which to read sound data into the buffer.
description	Sound setup description.
createAsyncState	If true, the asynchronous loading state for the buffer will be set up in the constructor. This is mainly useful for the null device which creates dummy buffers that do not need the async state to be in place. All other buffers do.

SFXBuffer(SFXDescription * description)

Create a buffer with just a description.

This is used by devices who fully take over loading and streaming.

~SFXBuffer()

_flush()

Flush all queue state for this buffer on the device.

note:
Called on the SFX update thread.

Reimplemented by: SFXDSBuffer, SFXFMODBuffer, SFXNullBuffer, SFXALBuffer, SFXInternal::SFXWrapAroundBuffer, SFXXAudioBuffer

_setStatus(Status status)

Set the buffer status and trigger mOnStatusChange if the status changes.

note:
Called on both the SFX update thread and the main thread.

Public Functions

destroySelf()

Reimplemented from: StrongRefBase

getDuration()

return:

The total playback time of the buffer in milliseconds.

getFormat()

return:

The sound sample format used by the buffer.

getMemoryUsed()

return:

The number of bytes consumed by this sound buffer.

Reimplemented by: SFXFMODBuffer, SFXInternal::SFXWrapAroundBuffer

getNumSamples()

return:

The total number of samples in the buffer.

getStatus()

return:

The current buffer loading/queue status.

isAtEnd()

return:

True if the buffer has exhausted its source stream

isBlocked()

return:

True if the buffer's packet queue has been starved and is waiting for data.

isDead()

return:

True if the buffer is pending deletion.

isLoading()

return:

True if the buffer's packet queue is still loading.

isReady()

return:

True if the buffer's packet queue is loaded and ready for playback.

isStreaming()

return:

True if the buffer does continuous sound streaming.

isUnique()

return:

True if the buffer can only have a single SFXVoice attached to it.

load()

Start the async request chain for the buffer.

update()

Reimplemented from: IPolled