CrystalSpace

Public API Reference

iSndSysStream Struct Reference
[Sound system]

The primary interface for a sound stream used by the audio system. More...

#include <isndsys/ss_stream.h>

Inheritance diagram for iSndSysStream:

List of all members.

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 bool AlwaysStream () const =0
 Whether this stream always needs to be treated as a stream regardless of size.
virtual int Get3dMode ()=0
 Retrieve the 3D Mode the sound stream was created for.
virtual bool GetAutoUnregister ()=0
 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 ()=0
 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_frames, void **buffer1, size_t *buffer1_frames, void **buffer2, size_t *buffer2_frames)=0
 Used to retrieve pointers to properly formatted sound data.
virtual const char * GetDescription ()=0
 Retrieve a description of this stream.
virtual size_t GetFrameCount ()=0
 Get length of this stream in rendered frames.
virtual size_t GetLoopEnd ()=0
 Gets when the audio should rewind to loop.
virtual size_t GetLoopStart ()=0
 Gets where the audio should rewind to loop.
virtual int GetLoopState ()=0
 Retrieves the loop state of the stream.
virtual int GetPauseState ()=0
 Returns the PAUSE state of the stream:

  • CS_SNDSYS_STREAM_PAUSED - The stream is paused.

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

Detailed Description

The primary interface for a sound stream used by the audio system.

Definition at line 62 of file ss_stream.h.


Member Function Documentation

virtual void iSndSysStream::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.

virtual bool iSndSysStream::AlwaysStream (  )  const [pure virtual]

Whether this stream always needs to be treated as a stream regardless of size.

virtual int iSndSysStream::Get3dMode (  )  [pure virtual]

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

virtual bool iSndSysStream::GetAutoUnregister (  )  [pure 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 iSndSysStream::GetAutoUnregisterRequested (  )  [pure virtual]

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

virtual void iSndSysStream::GetDataPointers ( size_t *  position_marker,
size_t  max_requested_frames,
void **  buffer1,
size_t *  buffer1_frames,
void **  buffer2,
size_t *  buffer2_frames 
) [pure 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_frames Should contain the maximum number of frames the calling source is interested in receiving. On return, *buffer1_length + *buffer2_length 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_frames should point to a long that will be filled with the length, in frames, 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_frames should point to a long that will be filled with the length, in frames, of valid data in the buffer pointed to by *buffer1 on return.
Remarks:
Not intended to be called by an application.
virtual const char* iSndSysStream::GetDescription (  )  [pure virtual]

Retrieve a description of this stream.

virtual size_t iSndSysStream::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 size_t iSndSysStream::GetLoopEnd (  )  [pure virtual]

Gets when the audio should rewind to loop.

Returns:
The position where to rewind to loop start when looping in frames.
virtual size_t iSndSysStream::GetLoopStart (  )  [pure virtual]

Gets where the audio should rewind to loop.

Returns:
The position where to restart playing when looping in frames.
virtual int iSndSysStream::GetLoopState (  )  [pure virtual]

Retrieves the loop state of the stream.

Current possible returns are CS_SNDSYS_STREAM_DONTLOOP and CS_SNDSYS_STREAM_LOOP.

virtual int iSndSysStream::GetPauseState (  )  [pure 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.
  • CS_SNDSYS_STREAM_COMPLETED - The stream's data has been processed but not rendered yet. In order to keep the state consistent, the Sound System's main processing thread should call Pause() once the data has been entirely rendered.
virtual int iSndSysStream::GetPlayRatePercent (  )  [pure virtual]

Retrieves the playback rate adjustment factor in percent.

100 = 100% (normal speed)

virtual size_t iSndSysStream::GetPosition (  )  [pure 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* iSndSysStream::GetRenderedFormat (  )  [pure virtual]

Get the format of the rendered sound data.

This is for informational purposes only.

virtual void iSndSysStream::InitializeSourcePositionMarker ( size_t *  position_marker  )  [pure 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 iSndSysStream::Pause (  )  [pure 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 bool iSndSysStream::PendingSeek (  )  [pure virtual]

Check if the stream is pending position replacement.

Usually in this case it might be a good idea to flush buffers and rebuffer.

Returns:
TRUE if the position is being changed
virtual void iSndSysStream::ProcessNotifications (  )  [pure 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.
virtual bool iSndSysStream::RegisterCallback ( iSndSysStreamCallback pCallback  )  [pure virtual]

Register a component to receive notification of stream events.

virtual bool iSndSysStream::RegisterFrameNotification ( size_t  frame_number  )  [pure virtual]

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

virtual bool iSndSysStream::ResetPosition (  )  [pure 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 iSndSysStream::SetAutoUnregister ( bool  autounreg  )  [pure 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 iSndSysStream::SetLoopBoundaries ( size_t  startPosition,
size_t  endPosition 
) [pure virtual]

Sets the loop start and end bounduaries.

The start position defines the position in frames where the loop will restart when the stream reaches the end of the stream, in case endPosition is 0 or the frame defined in endPosition.

Note:
The endPosition is exclusive while the start position is inclusive, so for example to get a loop from frame 0 to frame 0 you should do startPosition 0 and endPosition 1
Parameters:
startPosition The position in frames where to restart playing when looping.
endPosition The position in frames where to rewind to loop start when looping.
Returns:
false if the parameters are out of bound or the audio format plugin doesn't support this.
virtual bool iSndSysStream::SetLoopState ( int  loopstate  )  [pure 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 iSndSysStream::SetPlayRatePercent ( int  percent  )  [pure virtual]

Set the playback rate adjustment factor in percent.

100 = 100% (normal speed)

virtual bool iSndSysStream::SetPosition ( size_t  newposition  )  [pure 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 iSndSysStream::Unpause (  )  [pure 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 iSndSysStream::UnregisterCallback ( iSndSysStreamCallback pCallback  )  [pure virtual]

Unregister a previously registered callback component.


The documentation for this struct was generated from the following file:

Generated for Crystal Space 2.0 by doxygen 1.6.1