CrystalSpace

Public API Reference

CS::SndSys::SndSysBasicStream Class Reference

Inheritance diagram for CS::SndSys::SndSysBasicStream:

Inheritance graph
[legend]

List of all members.

Public Types

enum  StreamNotificationType { STREAM_NOTIFY_PAUSED = 0, STREAM_NOTIFY_UNPAUSED, STREAM_NOTIFY_LOOP, STREAM_NOTIFY_FRAME }
 Types of notification events. More...

Public Member Functions

virtual void AdvancePosition (size_t frame_delta)=0
 NOT AN APPLICATION CALLABLE FUNCTION! This function advances the stream position based on the provided frame count value which is considered as an elapsed frame count.
virtual int Get3dMode ()
 Retrieve the 3D Mode the sound stream was created for.
virtual bool GetAutoUnregister ()
 If AutoUnregister is set, when the stream is paused it, and all sources attached to it are removed from the sound engine.
virtual bool GetAutoUnregisterRequested ()
 Used by the sound renderer to determine if this stream needs to be unregistered.
virtual void GetDataPointers (size_t *position_marker, size_t max_requested_length, void **buffer1, size_t *buffer1_bytes, void **buffer2, size_t *buffer2_bytes)
 Used to retrieve pointers to properly formatted sound data.
virtual const char * GetDescription ()=0
 Retrieve the textual description of this stream.
virtual size_t GetFrameCount ()=0
 Get length of this stream in rendered frames.
virtual int GetLoopState ()
 Retrieves the loop state of the stream.
virtual int GetPauseState ()
 Returns the PAUSE state of the stream:
  • CS_SNDSYS_STREAM_PAUSED - The stream is paused.

virtual int GetPlayRatePercent ()
 Retrieves the playback rate adjustment factor in percent.
virtual size_t GetPosition ()
 Returns the current position of this sound in rendered frames.
virtual const
csSndSysSoundFormat
GetRenderedFormat ()
 Get the format of the rendered sound data.
virtual void InitializeSourcePositionMarker (size_t *position_marker)
 Fill a size_t value that will be used to track a Source's position through calls to GetDataPointers().
virtual bool Pause ()
 Pauses the stream at the current position.
virtual void ProcessNotifications ()
 Called by the sound system to allow a stream time to process pending notifications.
virtual bool RegisterCallback (iSndSysStreamCallback *pCallback)
 Register a component to receive notification of stream events.
virtual bool RegisterFrameNotification (size_t frame_number)
 Register a particular frame number which will trigger a callback notification when.
virtual bool ResetPosition ()
 Resets the position of the stream to the beginning if possible.
virtual void SetAutoUnregister (bool autounreg)
 If AutoUnregister is set, when the stream is paused it, and all sources attached to it are removed from the sound engine.
virtual bool SetLoopState (int loopstate)
 Sets the loop state of the stream.
virtual void SetPlayRatePercent (int percent)
 Set the playback rate adjustment factor in percent.
virtual bool SetPosition (size_t newposition)
 Sets the position of the stream to a particular frame.
virtual bool Unpause ()
 Unpauses the stream and resumes providing data at the current position.
virtual bool UnregisterCallback (iSndSysStreamCallback *pCallback)
 Unregister a previously registered callback component.

Static Public Attributes

static const size_t InvalidPosition = (size_t)~0
 A constant value used to indicate an invalid position for the stream.

Protected Member Functions

size_t CopyBufferBytes (size_t max_dest_bytes)
 Copies audio data from the ogg decoding buffer into the cyclic sample buffer.
void QueueNotificationEvent (StreamNotificationType NotifyType, size_t FrameNum)
 Called to queue a notification event.

Protected Attributes

int m_3DMode
 The 3d mode that this stream was created for.
bool m_bAutoUnregisterReady
 Set to true if this stream is ready for unregistering.
bool m_bAutoUnregisterRequested
 Set to true if this stream and all tied sources should be removed from the sound system when it enters a paused state.
bool m_bLooping
 Is this stream set to loop (start over) when it reaches the end.
bool m_bPaused
 Is this stream paused?
bool m_bPlaybackReadComplete
 Have we finished reading data from the underlying data element?
csRefArray
< iSndSysStreamCallback
m_CallbackList
 The list of registered callback interfaces (with references held).
size_t m_MostAdvancedReadPointer
 Holds our integer representation of the position of the source which is.
int m_NewOutputFrequency
 When the output frequency is changed, the conversion output buffer will be resized.
size_t m_NewPosition
 If this value is !=positionInvalid then the next stream advancement will occur from the position requested.
Queue
< StreamNotificationEvent
m_NotificationQueue
 Threadsafe queue of pending notification events.
int m_OutputFrequency
 Stores the output frequency which is (render_frequency * 100) / m_PlaybackPercent.
SoundCyclicBufferm_pCyclicBuffer
 A pointer to our cyclic buffer object.
int m_PlaybackPercent
 Stores the playback rate in percent.
PCMSampleConverterm_pPCMConverter
 Pointer to the PCM sample converter object that will handle our conversions.
char * m_pPreparedDataBuffer
 The buffer into audio is decoded in preparation.
int m_PreparedDataBufferSize
 Size (in bytes) of the buffer pointed to by m_pPreparedDataBuffer.
size_t m_PreparedDataBufferStart
 The offset of the first byte of valid data remaining in the prepared.
size_t m_PreparedDataBufferUsage
 The number of valid bytes of data remaining in the prepared data buffer.
csSndSysSoundFormat m_RenderFormat
 The audio format in which sound data must be presented to the renderer.
int m_RenderFrameSize
 Stores the size in bytes of one frame of output data.

Classes

struct  StreamNotificationEvent
 Structure containing the data for each notification event. More...


Detailed Description

Definition at line 39 of file sndstream.h.


Member Enumeration Documentation

Types of notification events.

Enumerator:
STREAM_NOTIFY_PAUSED 
STREAM_NOTIFY_UNPAUSED 
STREAM_NOTIFY_LOOP 
STREAM_NOTIFY_FRAME 

Definition at line 54 of file sndstream.h.


Member Function Documentation

virtual void CS::SndSys::SndSysBasicStream::AdvancePosition ( size_t  frame_delta  )  [pure virtual]

NOT AN APPLICATION CALLABLE FUNCTION! This function advances the stream position based on the provided frame count value which is considered as an elapsed frame count.

A Sound Element will usually store the last advance frame internally. When this function is called it will compare the last frame with the frame presented and retrieve more data from the associated iSndSysData container as needed. It will then update its internal last advance frame value.

This function is not necessarily thread safe and must be called ONLY from the Sound System's main processing thread.

size_t CS::SndSys::SndSysBasicStream::CopyBufferBytes ( size_t  max_dest_bytes  )  [protected]

Copies audio data from the ogg decoding buffer into the cyclic sample buffer.

virtual int CS::SndSys::SndSysBasicStream::Get3dMode (  )  [virtual]

Retrieve the 3D Mode the sound stream was created for.

virtual bool CS::SndSys::SndSysBasicStream::GetAutoUnregister (  )  [virtual]

If AutoUnregister is set, when the stream is paused it, and all sources attached to it are removed from the sound engine.

virtual bool CS::SndSys::SndSysBasicStream::GetAutoUnregisterRequested (  )  [virtual]

Used by the sound renderer to determine if this stream needs to be unregistered.

virtual void CS::SndSys::SndSysBasicStream::GetDataPointers ( size_t *  position_marker,
size_t  max_requested_length,
void **  buffer1,
size_t *  buffer1_bytes,
void **  buffer2,
size_t *  buffer2_bytes 
) [virtual]

Used to retrieve pointers to properly formatted sound data.

Since a Stream may be attached to multiple Sources, it will be most optimal to perform any decoded-data buffering at the stream level. The parameters passed to GetDataPointers() should allow for proper interface to a cyclic buffering method to store this decoded-data.

Since the data in the Stream buffer(s) and data related to how the buffers are accessed may change when AdvancePosition() is called, this function is not safe to call while AdvancePosition() is in operation. For this reason it is only safe to be called from the same thread that calls AdvancePosition() - specifically the Sound System main processing thread.

Parameters:
position_marker Should point to a size_t initially filled by the Sound System internally when a Source is created - through a call to InitializeSourcePositionMarker().
max_requested_length Should contain the maximum number of bytes the calling source is interested in receiving. On return, *buffer1_bytes + *buffer1_bytes must not exceed this value.
buffer1 Should point to a (void *) that will be filled with a pointer to the first chunk of data on return or NULL (0) if no data is available
buffer1_bytes Should point to a long that will be filled with the length, in bytes, of valid data in the buffer pointed to by *buffer1 on return.
buffer2 Should point to a (void *) that will be filled with a pointer to the second chunk of data on return, or NULL (0) if no second chunk is needed.
buffer2_bytes Should point to a long that will be filled with the length, in bytes, of valid data in the buffer pointed to by *buffer1 on return.
Remarks:
Not intended to be called by an application.

virtual const char* CS::SndSys::SndSysBasicStream::GetDescription (  )  [pure virtual]

Retrieve the textual description of this stream.

virtual size_t CS::SndSys::SndSysBasicStream::GetFrameCount (  )  [pure virtual]

Get length of this stream in rendered frames.

May return CS_SNDSYS_STREAM_UNKNOWN_LENGTH if the stream is of unknown length. For example, sound data being streamed from a remote host may not have a pre-determinable length.

virtual int CS::SndSys::SndSysBasicStream::GetLoopState (  )  [virtual]

Retrieves the loop state of the stream.

Current possible returns are CS_SNDSYS_STREAM_DONTLOOP and CS_SNDSYS_STREAM_LOOP.

virtual int CS::SndSys::SndSysBasicStream::GetPauseState (  )  [virtual]

Returns the PAUSE state of the stream:

  • CS_SNDSYS_STREAM_PAUSED - The stream is paused.

  • CS_SNDSYS_STREAM_UNPAUSED - The stream is not paused. AdvancePosition is moving the stream position.

virtual int CS::SndSys::SndSysBasicStream::GetPlayRatePercent (  )  [virtual]

Retrieves the playback rate adjustment factor in percent.

100 = 100% (normal speed)

virtual size_t CS::SndSys::SndSysBasicStream::GetPosition (  )  [virtual]

Returns the current position of this sound in rendered frames.

This should return a valid value even if GetFrameCount() returns CS_SNDSYS_STREAM_UNKNOWN_LENGTH since an object implementing this interface should know its position relative to the beginning of the data. In the case where the beginning may be ambiguous it should be considered to be at the point where the stream first started. In other words, where there is doubt, the position should start at 0 and advance as the position advances.

virtual const csSndSysSoundFormat* CS::SndSys::SndSysBasicStream::GetRenderedFormat (  )  [virtual]

Get the format of the rendered sound data.

This is for informational purposes only.

virtual void CS::SndSys::SndSysBasicStream::InitializeSourcePositionMarker ( size_t *  position_marker  )  [virtual]

Fill a size_t value that will be used to track a Source's position through calls to GetDataPointers().

Remarks:
Not intended to be called by an application.

virtual bool CS::SndSys::SndSysBasicStream::Pause (  )  [virtual]

Pauses the stream at the current position.

Data will not be provided through the GetData() call beyond the point of pausing. AdvancePosition() will NOT adjust the position of the stream.

If either of the above conditions cannot be met, this call fails and returns FALSE. The sound element should continue operation as though this call were not made. For example, a stream coming from a remote host may not be able to be stopped or advance-buffered properly, in this case pausing the stream is not possible, and this function should return FALSE.

virtual void CS::SndSys::SndSysBasicStream::ProcessNotifications (  )  [virtual]

Called by the sound system to allow a stream time to process pending notifications.

Remarks:
Not intended to be called by an application. This is called from the main application thread.

void CS::SndSys::SndSysBasicStream::QueueNotificationEvent ( StreamNotificationType  NotifyType,
size_t  FrameNum 
) [protected]

Called to queue a notification event.

virtual bool CS::SndSys::SndSysBasicStream::RegisterCallback ( iSndSysStreamCallback pCallback  )  [virtual]

Register a component to receive notification of stream events.

virtual bool CS::SndSys::SndSysBasicStream::RegisterFrameNotification ( size_t  frame_number  )  [virtual]

Register a particular frame number which will trigger a callback notification when.

virtual bool CS::SndSys::SndSysBasicStream::ResetPosition (  )  [virtual]

Resets the position of the stream to the beginning if possible.

FALSE may be returned if a reset operation is not permitted or not possible.

virtual void CS::SndSys::SndSysBasicStream::SetAutoUnregister ( bool  autounreg  )  [virtual]

If AutoUnregister is set, when the stream is paused it, and all sources attached to it are removed from the sound engine.

virtual bool CS::SndSys::SndSysBasicStream::SetLoopState ( int  loopstate  )  [virtual]

Sets the loop state of the stream.

Current acceptable values are CS_SNDSYS_STREAM_DONTLOOP and CS_SNDSYS_STREAM_LOOP May return FALSE if looping is not supported

virtual void CS::SndSys::SndSysBasicStream::SetPlayRatePercent ( int  percent  )  [virtual]

Set the playback rate adjustment factor in percent.

100 = 100% (normal speed)

virtual bool CS::SndSys::SndSysBasicStream::SetPosition ( size_t  newposition  )  [virtual]

Sets the position of the stream to a particular frame.

FALSE may be returned if a set position operation is not permitted or not possible.

virtual bool CS::SndSys::SndSysBasicStream::Unpause (  )  [virtual]

Unpauses the stream and resumes providing data at the current position.

If the stream is not currently paused this function returns FALSE.

virtual bool CS::SndSys::SndSysBasicStream::UnregisterCallback ( iSndSysStreamCallback pCallback  )  [virtual]

Unregister a previously registered callback component.


Member Data Documentation

const size_t CS::SndSys::SndSysBasicStream::InvalidPosition = (size_t)~0 [static]

A constant value used to indicate an invalid position for the stream.

Definition at line 47 of file sndstream.h.

The 3d mode that this stream was created for.

One of SOUND3D_DISABLE, SOUND3D_RELATIVE, or SOUND3D_ABSOLUTE

Definition at line 374 of file sndstream.h.

Set to true if this stream is ready for unregistering.

Definition at line 383 of file sndstream.h.

Set to true if this stream and all tied sources should be removed from the sound system when it enters a paused state.

Definition at line 380 of file sndstream.h.

Is this stream set to loop (start over) when it reaches the end.

Definition at line 313 of file sndstream.h.

Is this stream paused?

Definition at line 309 of file sndstream.h.

Have we finished reading data from the underlying data element?

Definition at line 320 of file sndstream.h.

The list of registered callback interfaces (with references held).

Definition at line 386 of file sndstream.h.

Holds our integer representation of the position of the source which is.

Definition at line 324 of file sndstream.h.

When the output frequency is changed, the conversion output buffer will be resized.

Definition at line 368 of file sndstream.h.

If this value is !=positionInvalid then the next stream advancement will occur from the position requested.

Used by ResetPosition()

Definition at line 330 of file sndstream.h.

Threadsafe queue of pending notification events.

Definition at line 389 of file sndstream.h.

Stores the output frequency which is (render_frequency * 100) / m_PlaybackPercent.

Definition at line 362 of file sndstream.h.

A pointer to our cyclic buffer object.

Definition at line 306 of file sndstream.h.

Stores the playback rate in percent.

Definition at line 356 of file sndstream.h.

Pointer to the PCM sample converter object that will handle our conversions.

Definition at line 336 of file sndstream.h.

The buffer into audio is decoded in preparation.

Definition at line 340 of file sndstream.h.

Size (in bytes) of the buffer pointed to by m_pPreparedDataBuffer.

Definition at line 343 of file sndstream.h.

The offset of the first byte of valid data remaining in the prepared.

Definition at line 350 of file sndstream.h.

The number of valid bytes of data remaining in the prepared data buffer.

Definition at line 346 of file sndstream.h.

The audio format in which sound data must be presented to the renderer.

Definition at line 299 of file sndstream.h.

Stores the size in bytes of one frame of output data.

Definition at line 353 of file sndstream.h.


The documentation for this class was generated from the following file:
Generated for Crystal Space 1.2.1 by doxygen 1.5.3