CSSI Class Reference
Sample Stream In base class. More...
Public Member Functions | |
API Functions | |
These functions are for use by the user to control and query a sample stream input object. The individual stream constructors set the parameters unique to each stream type. Some of these functions are also used internally by the slabwire framework. | |
| void | SSInPause () |
| pauses a sample stream | |
| bool | SSInPaused () |
| returns true if stream paused | |
| void | SSInPlay () |
| unpauses a paused stream | |
| virtual SSIError | SSInRewind () |
| rewinds stream (not supported by all streams) | |
| virtual bool | SSInContinuous () |
| returns true if the stream is continuous | |
| virtual StreamType | SSInStreamType ()=0 |
| returns the CSSI subclass's stream type | |
| unsigned long | SSInOverflow () |
| returns the number of overflows since SSInBegin() | |
| unsigned long | SSInUnderflow () |
| returns the number of underflows since SSInBegin() | |
| WAVEFORMATEX * | SSInFormat () |
| returns the stream format struct | |
| unsigned short | SSInFormatType () |
| returns the stream format struct format type | |
| virtual int | SSInChannels () |
| returns the stream format struct number of channels | |
| int | SSInSampleBits () |
| returns the stream format struct number of bits per sample | |
| int | SSInBlockSize () |
| returns the stream format struct block size | |
| long | SSInSampleRate () |
| returns the stream format struct sample rate | |
Buffer Access Functions | |
| virtual SSIError | SSInBegin () |
| begins sample stream input | |
| virtual SSIError | SSInEnd () |
| ends sample stream input | |
| virtual SSIError | SSInRead () |
| requests a buffer of input | |
| virtual char * | SSInPtr () |
| returns a pointer to the current input sample buffer | |
| virtual long | SSInBytes () |
| returns the size of the SSInPtr() buffer in bytes | |
| virtual bool | SSInActive () |
| returns true if stream is active | |
| virtual bool | SSInDone () |
| returns true if stream done (empty) | |
| virtual bool | SSInData () |
| returns true if input sample data available | |
| SSIError | SSInSetRecorder (CSITrack *pSIT) |
| attach CSITrack Track Recorder object for recording input | |
Sample Access Functions | |
| void | SampleReset () |
| resets the Sample interface | |
| long | SampleRemain () |
| returns the number of samples remaining in the input buffer | |
| float | SampleFloat () |
| returns one sample of input, converted to float if necessary | |
| short | SamplePCM8 () |
| returns one 8-bit PCM sample of input in 16-bit PCM format | |
| short | SamplePCM16 () |
| returns one 16-bit PCM sample of input | |
Delay Line Functions | |
| SSIError | DelayInit (int nDelayMS, int nPFrameLen, long lPFS, int nOver, int nResampler=2) |
| attaches a delay line to the SSI | |
| void | DelayAlias (bool bAlias) |
| allows resample aliasing | |
| virtual int | DelayLength () |
| returns delay line length in samples | |
| int | DelayFrame () |
| returns frame length in samples | |
| virtual void | DelayChannel (int nCh) |
| sets the current channel of the delay line | |
| virtual SSIError | DelayAdvance () |
| advances the delay line one frame | |
| virtual float | operator[] (int n) |
| delay line sample access, integer index | |
| virtual float | operator[] (float f) |
| delay line sample access, float index | |
Public Attributes | |
| CDelayLine | m_cFrameIn |
| Delay input frame and FIR memory. | |
| CDelayLine | m_cDelayLine |
| Delay delay line. | |
| HANDLE | m_hEventUnsuspend |
| continuous stream unsuspend (public for callback access) | |
Protected Types | |
| enum | SSIState { SSI_NOTACTIVE, SSI_DATA, SSI_DONE, SSI_SUSPENDED } |
| SSI states. More... | |
Protected Attributes | |
| SSIState | m_SSIState |
| object state | |
| WAVEFORMATEX * | m_pFormat |
| stream format | |
| int | m_nIndexSample |
| input buffer sample index | |
| bool | m_bPlay |
| play/pause flag | |
| bool | m_bBegin |
| stream begin has occurred | |
| CRITICAL_SECTION | m_cs |
| sync user and DSP threads | |
| unsigned long | m_lOverflow |
| overflow counter | |
| unsigned long | m_lUnderflow |
| underflow counter | |
| CSITrack * | m_pSIT |
| track recorder | |
| int | m_nFrameLen |
| Delay processing frame length. | |
| CResampler * | m_pResampler |
| Delay resampler. | |
| int | m_nInUsed |
| # input samples used by resampler | |
Error Handling and Reporting functions | |
| virtual SSIError | ErrorHandle (SSIError error) |
| internal SSI error handling function | |
| virtual bool | ErrorState () |
| returns true if the object is in an error state | |
| char * | ErrorString () |
| returns a string describing the current error state | |
| SSIError | Error () |
| returns the curret error state | |
Detailed Description
CSSI is the base class for all Sample Stream In (SSI) classes. It supports three types of sample access:- buffer - SSInPtr(), SSInBytes()
- sample at a time - "Sample"-prefixed functions
- delay line - "Delay"-prefixed functions, operator[]
When using the sample access functions without a delay line, the input buffer is advanced manually, i.e., code must be written that checks for the consumption of the current input buffer and reads the next buffer once the current buffer is consumed.
DelayInit() enables the following capabilities:
- manages a frame length buffer of current float samples with at least one frame of past samples
- optional delay line extension beyond one frame
- input-to-processing sample rate conversion, if required
- "Sample" function frame buffer advancement
- bracket operator ([]) delay line sample access
- linearly-interpolated fractionally-indexed sample access
- optional upsampling of delay line (reduces linear interp lowpass effect)
Delay line functions:
- DelayInit() - inits delay line
- DelayAlias() - allows resample aliasing
- DelayLength() - returns delay line length in samples
- DelayFrame() - returns frame length in samples
- DelayChannel() - sets current channel
- DelayAdvance() - advances delay line one frame
- operator [ int ] - delay line sample access
- operator [ float ] - interpolated delay line sample access
Delay line definitions:
- IFS = input sample rate (e.g., wave file at 11025, 22050, or 44100)
- PFS = processing sample rate (e.g., 44100)
- DFS = delay line sample rate (e.g., 88200)
- oversampling factor = processing rate (PFS) to delay line rate (DFS) factor (e.g., 2x for 44100 to 88200)
- Note:
- Aliasing can occur when using an oversampled delay line if the rates are such that the samples in the delay line are not bandlimited to half the processing rate. This is due to the fact that only one resampling operation occurs - input rate to delay line rate. For example, an input rate of 44100 Hz downsampled to a delay line rate of 22050 Hz with a processing rate of 11025 Hz will cause aliasing of the frequency content between 11025 Hz and 5512 Hz.
Library: none
Member Enumeration Documentation
enum CSSI::SSIState [protected] |
- Enumerator:
-
SSI_NOTACTIVE active = between SSInBegin() and SSInEnd() SSI_DATA data available SSI_DONE stream empty SSI_SUSPENDED stream suspended, waiting for new data
Member Function Documentation
ErrorHandle() is the internal SSI error handling function called when an error occurs. In general, subclasses do not need to override this function. If an error occurs, SSIs typically stay in an error state until they are deleted. The primary reason to override this function is if the error would cause annoying audible artifacts. In this case, it might be desirable to override ErrorHandle() and handle the error condition immediately rather than waiting for the desctructor to be called.
The default behavior of ErrorHandle() is to set the error state and to log the error in the global log statck (CLogStack) and the global log file (CLogFile).
Reimplemented in CSIDevice.
| char* CSSI::ErrorString | ( | ) | [inline] |
ErrorString() returns a string describing the current error state.
| SSIError CSSI::Error | ( | ) | [inline] |
Error() returns the current error state.
- See also:
- ErrorString(), CLogStack, CLogFile
Referenced by SSInRewind().
| void CSSI::SSInPause | ( | ) | [inline] |
SSInPause() pauses a sample stream. A paused stream streams zeroes instead of data. If a stream is "continuous" (e.g., sound devices), incoming samples will be discarded. Pause functionality is implemented in the Sample interface.
References m_bPlay.
| virtual bool CSSI::SSInContinuous | ( | ) | [inline, virtual] |
SSInContinuous() returns true if the stream is continuous. A continuous stream is a stream such as a device that must be pumped continuously (i.e., buffers must by cycled). When a continuous stream is paused, samples are discarded.
By default, this function returns false. Subclasses should override this function and return true if the stream is continuous.
Reimplemented in CSIAsio, CSIDevice, CSIDISRadio, CSISubmix, CSIVoipID, and CSIVoipPort.
| unsigned long CSSI::SSInOverflow | ( | ) | [inline] |
SSInOverflow() returns the number of overflows since SSInBegin(). Overflows are only possible for continuous streams and should be avoided because they can result in audible artifacts. An overflow can occur if the DSP consumes samples at a rate lower than the samples are provided by a continuous input (e.g., sound device). The most common cause of overflow is DSP computational load.
References m_lOverflow.
| unsigned long CSSI::SSInUnderflow | ( | ) | [inline] |
SSInUnderflow() returns the number of underflows since SSInBegin(). Underflows are only possible for continuous streams and should be avoided because they can result in audible artifacts. An underflow can occur if the stream source (e.g., remote DIS radio transmitter) cannot supply samples fast enough to keep up with real time. The most common cause of underflow is delayed or missing network packets.
References m_lUnderflow.
| virtual SSIError CSSI::SSInBegin | ( | ) | [virtual] |
SSInBegin() begins sample stream input. Subclasses should call the base class function to init the Sample interface and reset the overflow counter.
Reimplemented in CSIAsio, CSIDevice, CSIDISRadio1, CSIDISRadio2, CSIFile, CSIGen, CSIList, CSIMemory, CSISubmix, CSITrack, CSIUrl, CSIUser, CSIVoipID, and CSIVoipPort.
| virtual SSIError CSSI::SSInEnd | ( | ) | [virtual] |
SSInEnd() ends sample stream input.
Reimplemented in CSIAsio, CSIDevice, CSIDISRadio1, CSIDISRadio2, CSIFile, CSIGen, CSIList, CSIMemory, CSITrack, CSIUrl, CSIUser, CSIVoipID, and CSIVoipPort.
| virtual SSIError CSSI::SSInRead | ( | ) | [virtual] |
SSInRead() requests a buffer of input. For continuous streams, this function can suspend, waiting for input samples. Subclasses should call the base class function to reset the Sample interface for the new buffer. After SSInRead() returns, SSInPtr() will point to the new sample data and SSInBytes() will indicate the number of bytes read.
Reimplemented in CSIAsio, CSIDevice, CSIDISRadio1, CSIDISRadio2, CSIFile, CSIGen, CSIMemory, CSITrack, CSIUrl, CSIUser, CSIVoipID, and CSIVoipPort.
| virtual char* CSSI::SSInPtr | ( | ) | [inline, virtual] |
SSInPtr() returns a pointer to the current input sample buffer. The buffer samples are channel-interleaved and in their native format (e.g., 8 or 16-bit int, float). The Sample interface provides a slightly higher-level of buffer access, retrieving samples one at a time in float format. Some SSIs might choose to only support one type of sample access.
Reimplemented in CSIAsio, CSIDevice, CSIDISRadio1, CSIDISRadio2, CSIFile, CSIGen, CSIMemory, CSITrack, CSIUrl, CSIUser, CSIVoipID, and CSIVoipPort.
| virtual long CSSI::SSInBytes | ( | ) | [inline, virtual] |
SSInBytes() returns the size of the SSInPtr() buffer in bytes.
Reimplemented in CSIAsio, CSIDevice, CSIDISRadio1, CSIDISRadio2, CSIFile, CSIGen, CSIMemory, CSITrack, CSIUrl, CSIUser, CSIVoipID, and CSIVoipPort.
| virtual bool CSSI::SSInActive | ( | ) | [inline, virtual] |
SSInActive() returns true if the stream is active (between SSInBegin() and SSInEnd()). An active stream can be in one of three states: (1) data available, (2) done (stream empty), or (3) suspended (waiting for data). This function is used internally by some CSSI subclasses.
References m_SSIState, and SSI_NOTACTIVE.
| virtual bool CSSI::SSInDone | ( | ) | [inline, virtual] |
SSInDone() returns true if the stream is done (empty). One-shot (non-looping) wave file input is an example of a stream that can enter a done state. This function is used by CDSP to manage stream I/O.
Reimplemented in CSIList.
References m_SSIState, and SSI_DONE.
| virtual bool CSSI::SSInData | ( | ) | [inline, virtual] |
SSInData() returns true if input sample data is available. This function is used by CDSP to manage stream I/O.
Reimplemented in CSIList.
References m_SSIState, and SSI_DATA.
SSInSetRecorder() is used to attach a CSITrack Track Recorder object for recording SSI input. When recording, CSITrack writes the SSI input to a file. The CSITrack object can also be used simultaneously as a standard SSI input object.
| void CSSI::SampleReset | ( | ) | [inline] |
SampleReset() resets the Sample interface. The Sample interface provides a slightly higher-level of input buffer access, retrieving samples one at a time in float format. Sample also supports play/pause functionality.
References m_nIndexSample.
| long CSSI::SampleRemain | ( | ) |
SampleRemain() returns the number of samples remaining in the input buffer. For multi-channel input, this number corresponds to the number of samples in one channel. The number of remaining samples is reduced by the number of samples read via the Sample interface since the last SSInRead().
If the stream is paused and is not continuous, a constant value of 32768 is returned. In a paused state, a non-continuous stream streams an unlimited amount of zero-valued samples.
| float CSSI::SampleFloat | ( | ) |
SampleFloat() returns one sample of input. The sample is converted to float format, if necessary. If the stream is paused, a zero-valued sample is returned. If the paused stream is continuous, a sample of continuous data is discarded.
| short CSSI::SamplePCM8 | ( | ) |
SamplePCM8() returns one 8-bit PCM sample of input in 16-bit format. This function is primarily for use by SampleFloat(). If used directly, the input sample buffer must be in 8-bit PCM format. See SampleFloat() regarding pause behavior.
| short CSSI::SamplePCM16 | ( | ) |
SamplePCM16() returns one 16-bit PCM sample of input. This function is primarily for use by SampleFloat(). If used directly, the input sample buffer must be in 16-bit PCM format. See SampleFloat() regarding pause behavior.
| SSIError CSSI::DelayInit | ( | int | nDelayMS, | |
| int | nPFrameLen, | |||
| long | lPFS, | |||
| int | nOver, | |||
| int | nResampler = 2 | |||
| ) |
DelayInit() attaches a delay line to the SSI. This enables the additional functionality described in the class description. If nResampler is 1, resample factors of 1,2,4,8x are allowed. If nResampler is 2, arbitrary resample factors are allowed.
| void CSSI::DelayAlias | ( | bool | bAlias | ) | [inline] |
DelayAlias() allows resample aliasing. If bAlias is true, aliasing is allowed, if false, an anti-alias filter is applied. This function is only valid after DelayInit() and only supported by the arbitrary resample factor algorithm.
References m_pResampler.
| virtual int CSSI::DelayLength | ( | ) | [inline, virtual] |
DelayLength() returns delay line length in samples.
References m_cDelayLine.
| int CSSI::DelayFrame | ( | ) | [inline] |
DelayFrame() returns frame length in samples.
References m_nFrameLen.
| virtual void CSSI::DelayChannel | ( | int | nCh | ) | [inline, virtual] |
DelayChannel() sets the current channel of the delay line.
Reimplemented in CSIList, and CSISubmix.
References m_cDelayLine.
Referenced by CSIList::DelayChannel().
| virtual SSIError CSSI::DelayAdvance | ( | ) | [virtual] |
DelayAdvance() advances the delay line one frame. A new input buffer is read if necessary. The samples are converted from the input sample rate to the delay line rate as needed.
Reimplemented in CSIDISFreq, CSIList, and CSISubmix.
| virtual float CSSI::operator[] | ( | int | n | ) | [inline, virtual] |
operator[] (int) extracts a sample from the delay line at the processing sample rate (PFS). The subscript is less than zero for delay or zero to frame length minus one for the current frame. This operator is faster than the float-indexed version.
- See also:
- operator[] (float)
Reimplemented in CSIList.
References m_cDelayLine.
| virtual float CSSI::operator[] | ( | float | f | ) | [inline, virtual] |
operator[] (float) extracts a sample from the delay line at the processing sample rate (PFS). The subscript is less than zero for delay or zero to frame length minus one for the current frame. Fractional indices are linearly interpolated. Delay line oversampling can reduce the lowpass effect.
- See also:
- operator[] (int)
Reimplemented in CSIList.
References m_cDelayLine.