Output Stream
[Streams]

The following section describes the states a stream uses. More...

Functions

HPI_ERR HPI_OutStreamOpen (HPI_HSUBSYS *phSubSys, HW16 wAdapterIndex, HW16 wOutStreamIndex, HPI_HOSTREAM *phOutStream)
 Open and initializes an output stream.
HPI_ERR HPI_OutStreamClose (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream)
 Closes an output stream and deallocates host buffers if they are being used.
HPI_ERR HPI_OutStreamGetInfo (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW16 *pwState, HW32 *pdwBufferSize, HW32 *pdwDataToPlay)
HPI_ERR HPI_OutStreamGetInfoEx (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW16 *pwState, HW32 *pdwBufferSize, HW32 *pdwDataToPlay, HW32 *pdwSamplesPlayed, HW32 *pdwAuxiliaryDataToPlay)
 Get information about attributes and state of output stream.
HPI_ERR HPI_OutStreamWriteBuf (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW8 *pbData, HW32 dwBytesToWrite, HPI_FORMAT *pFormat)
 Writes a block of audio data to the specified output stream.
HPI_ERR HPI_OutStreamWrite (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HPI_DATA *pData)
 Writes a block of audio data to the specified output stream.
HPI_ERR HPI_OutStreamStart (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream)
 Starts an output stream playing audio data.
HPI_ERR HPI_OutStreamStop (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream)
 Stops an output stream playing audio data.
HPI_ERR HPI_OutStreamReset (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream)
 Clears the audio data buffer of an output stream.
HPI_ERR HPI_OutStreamQueryFormat (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HPI_FORMAT *pFormat)
 Queries an OutStream to see whether it supports a certain audio format, described in pFormat.
HPI_ERR HPI_OutStreamSetVelocity (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, short nVelocity)
 Sets the playback velocity for scrubbing.
HPI_ERR HPI_OutStreamAncillaryReset (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW16 wMode)
 Resets MPEG ancillary data extraction.
HPI_ERR HPI_OutStreamAncillaryGetInfo (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW32 *pdwFramesAvailable)
 Returns information about the Ancillary stream.
HPI_ERR HPI_OutStreamAncillaryRead (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HPI_ANC_FRAME *pAncFrameBuffer, HW32 dwAncFrameBufferSizeInBytes, HW32 dwNumberOfAncillaryFramesToRead)
 Reads frames of ancillary data from a stream's ancillary data buffer to pdwBuffer.
HPI_ERR HPI_OutStreamSetTimeScale (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW32 dwTimeScale)
 Sets the playback timescale with pitch and content preservation.
HPI_ERR HPI_OutStreamHostBufferAllocate (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW32 dwSizeInBytes)
 Allocates a buffer inside the driver for bus mastering transfers.
HPI_ERR HPI_OutStreamHostBufferFree (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream)
 Free any buffers allocated by HPI_OutStreamHostBufferAllocate().
HPI_ERR HPI_OutStreamGroupAdd (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HPI_HSTREAM hStream)
 This function adds a stream to a group of streams.
HPI_ERR HPI_OutStreamGroupGetMap (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream, HW32 *pdwOutStreamMap, HW32 *pdwInStreamMap)
 This function returns information about the streams that form a group.
HPI_ERR HPI_OutStreamGroupReset (HPI_HSUBSYS *phSubSys, HPI_HOSTREAM hOutStream)
 Resets stream grouping information for a given out stream.

Detailed Description

The following section describes the states a stream uses.

outstream_states.png

The state HPI_STATE_DRAINED indicates that the stream has run out of decoded data.

This can happen for two reasons:
Intentionally, when the end of the currently playing audio is reached.
A transient error condition when the adapter DSP was unable to decode audio fast enough.

The dwDataToPlay count returned from HPI_OutStreamGetInfoEx() measures the amount of encoded data (MPEG, PCM, etc.) in the stream's buffer. When there is less than a whole frame of encoded data left, it cannot be decoded for mixing and output. It is possible that HPI_OutStreamGetInfoEx() indicates that there is still a small amount of data to play, but the stream enters the DRAINED state, and the amount of data to play never gets to zero.

The size of a frame varies depending on the audio format. Compressed formats such as MPEG require whole frames of data in order to decode audio. The size of the input frame depends on the samplerate and bitrate (e.g. MPEG frame_bytes = bitrate/8 * 1152/samplerate).

AudioScience's implementation of PCM decoding also requires a minimum amount of input data. ASI4xxx adapters require 4608 bytes, whereas ASI6xxx adapters require 1536 bytes for stereo, half this for mono.

Conservative conditions to detect end of play:

Input data requirements for different algorithms.

BytesPCM-16MP1MP2 MP3AC-2

AX4608<3456<3456-380
AX44608<3456<34563456-
AX61536<=700<=7001100380

Function Documentation

HPI_ERR HPI_OutStreamOpen (  HPI_HSUBSYS *  phSubSys,
HW16  wAdapterIndex,
HW16  wOutStreamIndex,
HPI_HOSTREAM *  phOutStream
) 
 

Open and initializes an output stream.

The handle is used for all future calls to that OutStream. An output stream may only be open by only one application at a time.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
wAdapterIndex  Index of adapter to be opened. Ranges from 0 to 15 and corresponds to the Adapter Index set on the adapter hardware.
wOutStreamIndex  Index of the OutStream to be opened. Ranges from 0 to wNumOutStreams-1 (returned by HPI_AdapterGetInfo()).
phOutStream  Returned Handle to the OutStream.

HPI_ERR HPI_OutStreamClose (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream
) 
 

Closes an output stream and deallocates host buffers if they are being used.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle of the OutStream to close.

HPI_ERR HPI_OutStreamGetInfo (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW16 *  pwState,
HW32 *  pdwBufferSize,
HW32 *  pdwDataToPlay
) 
 

Deprecated:
This function has been superseded by HPI_OutStreamGetInfoEx()

HPI_ERR HPI_OutStreamGetInfoEx (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW16 *  pwState,
HW32 *  pdwBufferSize,
HW32 *  pdwDataToPlay,
HW32 *  pdwSamplesPlayed,
HW32 *  pdwAuxiliaryDataToPlay
) 
 

Get information about attributes and state of output stream.

This is similar to HPI_OutStreamGetInfo() but returns extended information including the size of the streams buffer in pdwBufferSize. It also returns whether the stream is currently playing (the state) and the amount of audio data left to play.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to opened OutStream.
pwState  State of stream = HPI_STATE_STOPPED,HPI_STATE_PLAYING or HPI_STATE_DRAINED.
pdwBufferSize  Size (in bytes) of stream data buffer.
pdwDataToPlay  Bytes left in the buffer to play.
pdwSamplesPlayed  The SamplesPlayed parameter returns the number of samples played since the last HPI_OutStreamReset command was issued. It reflects the number of stereo samples for a stereo stream and the number of mono samples for a mono stream. This means that if a 44.1kHz stereo and mono stream were both playing they would both return SamplesPlayed=44100 after 1 second.
pdwAuxiliaryDataToPlay  AuxiliaryDataToPlay is only relevant when BBM is active (see HPI_OutStreamHostBufferAllocate). In this case DataToPlay refers to the host side buffer state while AuxiliaryDataToPlay refers to the data remaining in the card's own buffers.

HPI_ERR HPI_OutStreamWriteBuf (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW8 *  pbData,
HW32  dwBytesToWrite,
HPI_FORMAT *  pFormat
) 
 

Writes a block of audio data to the specified output stream.

dwBytesToWrite bytes are copied from *pbData array to the output stream hardware. On return the memory used to hold that data may be reused.

A different format will only be accepted in the first write after the stream is opened or reset.

The size of the data block that may be written is limited to half the size of the streams internal data buffer (specified by dwBufferSize returned by HPI_OutStreamGetInfo()).

outstream_buf.png 
wHE = HPI_FormatCreate(
                        &hpiFormat,
                        2,                 // stereo channel
                        HPI_FORMAT_MPEG_L2,// MPEG Layer II
                        44100L,            //sample rate
                        128000L,           //128k bits/sec
                        0                  // no attributes
                        );

wHE = HPI_OutStreamWriteBuf( phSubSys, hOutStream, &aData, dwBytes, &hpiFormat);
Returns:
0 on success, or one of the HPI Error codes.
Return values:
0 The data was written to the stream
HPI_INVALID_DATASIZE tried to write more data than buffer space available - no data was written
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to opened OutStream.
pbData  Pointer to buffer containing data to be written to the playback buffer.
dwBytesToWrite  Number of bytes to write, must be <= space available.
pFormat  Format of the data (compression,channels,samplerate)

HPI_ERR HPI_OutStreamWrite (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HPI_DATA *  pData
) 
 

Writes a block of audio data to the specified output stream.

The data to write is specified by pData. pData also contains the format of the data (channels, compression, sampleRate). The HPI_OutStreamWrite() call copies the data in pData to the output stream hardware. Once the data has been written to the stream, the memory used to hold that data may be reused.

Deprecated:
Use HPI_OutStreamWriteBuf() instead. This function may disappear from a future version.
A different format will only be accepted in the first write after the stream is opened or reset.

The size of the data block that may be written is limited to half the size of the streams internal data buffer (specified by dwBufferSize returned by HPI_OutStreamGetInfo()).

outstream_buf.png
Example:
wHE = HPI_FormatCreate(
                        &hpiFormat,
                        2,                 // stereo channel
                        HPI_FORMAT_MPEG_L2,// MPEG Layer II
                        44100L,            //sample rate
                        128000L,           //128k bits/sec
                        0                  // no attributes
                        );

wHE = HPI_DataCreate( &Data, &hpiFormat, gabBuffer, BLOCK_SIZE );
wHE = HPI_OutStreamWrite( phSubSys, hOutStream, &Data);
Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to opened OutStream.
pData  Pointer to an HPI_DATA structure containing a description of the audio data to be written to the OutStream and played.

HPI_ERR HPI_OutStreamStart (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream
) 
 

Starts an output stream playing audio data.

Data is taken from the circular buffer on the adapter hardware that has already been partially filled by HPI_OutStreamWrite commands. Audio is played from the current position in the buffer (which may be reset using HPI_OutStreamReset()).

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.

HPI_ERR HPI_OutStreamStop (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream
) 
 

Stops an output stream playing audio data.

The audio data buffer is not cleared, so a subsequent OutStreamStart will resume playing at the position in the buffer where the playback had been stopped.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.

HPI_ERR HPI_OutStreamReset (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream
) 
 

Clears the audio data buffer of an output stream.

If the stream was playing at the time, it will be stopped.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.

HPI_ERR HPI_OutStreamQueryFormat (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HPI_FORMAT *  pFormat
) 
 

Queries an OutStream to see whether it supports a certain audio format, described in pFormat.

The result, returned in the error code, is 0 if supported and HPI_ERROR_INVALID_FORMAT if not supported.

Returns:
0 on success, or one of the HPI Error codes.
Return values:
HPI_ERROR_INVALID_FORMAT if the format is not supported.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
pFormat  Format to query.

HPI_ERR HPI_OutStreamSetVelocity (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
short  nVelocity
) 
 

Sets the playback velocity for scrubbing.

Velocity range is +/- 4.0. nVelocity is set by 

nVelocity = (HW16)(fVelocity * HPI_VELOCITY_UNITS);
where fVelocity is a floating point number in the range of -4.0 to +4.0. This call puts the stream in "scrub" mode. The first call to HPI_OutStreamSetVelocity() should be made while the stream is reset so that scrubbing can be performed after starting playback.

Note:
This functionality is only available on the ASI4300 series adapters.
Call sequence

A typical playback call sequence without scrubbing is: 

Write
Write
Start
Write
.....

Stop
A typical playback sequence with scrubbing is: 
Write
Write
SetVelocity
Start
Write
SetVelocity
.....

Stop - automatically turns of velocity/scrub mode.

Data flow

The scrubbing approach taken here is to decode audio to a "scrub buffer" that contains many seconds of PCM that can be traversed in at a variable rate.

outstream_scrub.png
Forward scrubbing does not have any limitations whatsoever, apart from the maximum speed, as specified by HPI_OutStreamSetVelocity().

Reverse scrubbing operates under the following constraints:
1) The user may not scrub on audio prior to the HPI_OutStreamStart( ) data point.
2) The user may not reverse scrub further than -10 seconds from the forward most scrub position.
If either of these constraints is broken, the stream state will return HPI_STATE_DRAINED and audio playback will cease. The user can then forward scrub again after this error condition.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
nVelocity  The velocity in units HPI_VELOCITY_UNITS.

HPI_ERR HPI_OutStreamAncillaryReset (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW16  wMode
) 
 

Resets MPEG ancillary data extraction.

Initializes the MPEG Layer II / III Ancillary data channel to support the extraction of wBytesPerFrame bytes from the MPEG bitstream.

Note:
This call must be made after HPI_OutStreamOpen() or HPI_OutStreamReset() and before the first HPI_OutStreamWrite() call.
Parameters:
wMode The mode for the ancillary data extraction to operate in. Valid settings are HPI_MPEG_ANC_RAW and HPI_MPEG_ANC_HASENERGY. The "RAW" mode indicates that the entire ancillary data field is taken up by data from the Anc data buffer. The "HASENERGY" option tells the decoder that the MPEG frames have energy information stored in them (5 bytes per stereo frame, 3 per mono).
Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.

HPI_ERR HPI_OutStreamAncillaryGetInfo (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW32 *  pdwFramesAvailable
) 
 

Returns information about the Ancillary stream.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
pdwFramesAvailable  Number of HPI_ANC_FRAMEs in the hardware buffer available for reading.

HPI_ERR HPI_OutStreamAncillaryRead (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HPI_ANC_FRAME *  pAncFrameBuffer,
HW32  dwAncFrameBufferSizeInBytes,
HW32  dwNumberOfAncillaryFramesToRead
) 
 

Reads frames of ancillary data from a stream's ancillary data buffer to pdwBuffer.

Note that in the situation where energy level information is embedded in the ancillary data stream along with ancillary data, only the ancillary data will be returned in the ancillary data buffer.

Bytes are filled in the bData[] array of the HPI_ANC_FRAME structures in the following order:

The first bit of ancillary information that follows the valid audio data is placed in bit 7 of bData[0]. The first 8 bits of ancillary information following valid audio data are all placed in bData[0]. In the case where there are 6 bytes total of ancillary information (48 bits) the last byte filled is bData[5].

Note:
If OutStreamAncillaryReset() was called with mode=HPI_MPEG_ANC_RAW, the ancillary data in its entirety is placed in the AncFrameBuffer, so if the file was recorded with energy information in the ancillary data field, the energy information will be included in the extracted ancillary data.

If OutStreamAncillaryReset() was called with mode=HPI_MPEG_ANC_HASENERGY, the ancillary data minus the energy information is placed in the AncFrameBuffer.

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
pAncFrameBuffer  A pointer to a buffer where the read Ancillary data frames should be placed.
dwAncFrameBufferSizeInBytes  The size of the Ancillary data buffer in bytes (used for a sanity check).
dwNumberOfAncillaryFramesToRead  How many frames to read.

HPI_ERR HPI_OutStreamSetTimeScale (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW32  dwTimeScale
) 
 

Sets the playback timescale with pitch and content preservation.

Range is 0.8-1.2 ( to 120%) of original time.
dwTimeScale in set by:

dwTimeScale = (HW16)(fTimeScale * HPI_OSTREAM_TIMESCALE_UNITS);
where fTimeScale in a floating point number in the range of 0.8 < fTimeScale < 1.2. The actual granularity of this setting is 1 / 2048 or approximately 0.05% (approx 5 HPI_OSTREAM_TIMESCALE_UNITS).

The first call to HPI_OutStreamSetTimeScale should be made while the stream is reset so that time scaling can be performed after starting playback. Subsequent calls to HPI_OutStreamSetTimeScale can be made when the stream is playing to modify the timescale factor.

Note:
This functionality is only available on ASI6000 series adapters.
Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
dwTimeScale  The time scale in units of HPI_OSTREAM_TIMESCALE_UNITS.

HPI_ERR HPI_OutStreamHostBufferAllocate (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW32  dwSizeInBytes
) 
 

Allocates a buffer inside the driver for bus mastering transfers.

Once the buffer is allocated, OutStream data will be transferred from it in the background (rather than the application having to wait for the transfer).

This function is provided so that the application can match the size of its transfers to the size of the buffer.

After a call to HPI_OutStreamHostBufferAllocate(), HPI_OutStreamGetInfoEx() returns the size and data available in host buffer rather than the buffers on the adapter. However, while there is space in the adapter buffers, data will be quickly transferred to the adapter, providing additional buffering against delays in sending more audio data.

Note:
There is a minimum buffer size that will work with a given audio format and polling rate. An appropriate size for the buffer can be calculated using HPI_StreamEstimateBufferSize().
If an error occurs or the adapter doesn't support host buffering then no buffer is allocated. Stream transfers still take place using foreground transfers (all drivers pre 2004). Performance will be relatively worse.

Returns:
0 on success, or one of the HPI Error codes.
Return values:
HPI_ERROR_INVALID_DATASIZE memory can't be allocated (retrying the call with a smaller size may succeed)
HPI_ERROR_INVALID_FUNC the adapter doesn't support busmastering
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
dwSizeInBytes  Buffer size in bytes to allocate.

HPI_ERR HPI_OutStreamHostBufferFree (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream
) 
 

Free any buffers allocated by HPI_OutStreamHostBufferAllocate().

Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.

HPI_ERR HPI_OutStreamGroupAdd (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HPI_HSTREAM  hStream
) 
 

This function adds a stream to a group of streams.

Stream groups are used to synchronise starting and stopping of multiple streams at once. The application of this is to support playing (or recording) multiple streams at once, enabling multi-channel recording and playback.

When using the "Group" functions all streams that are to be grouped together should be opened. One of the streams should be selected to be the master stream and the other streams should be added to it's group. Both in streams and out streams can be added to the same group. Once a group has been formed, HPI_OutStreamStart() called on the master will cause all streams to start at once.

Note:
This function is only supported on on ASI6000 and ASI5000 adapters.
Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
hStream  Handle to an In or Out Stream

HPI_ERR HPI_OutStreamGroupGetMap (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream,
HW32 *  pdwOutStreamMap,
HW32 *  pdwInStreamMap
) 
 

This function returns information about the streams that form a group.

Given an out stream handle, it returns a bit mapped representation of which streams belong to the group.

Note:
This function is only supported on on ASI6000 and ASI5000 adapters.
Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.
pdwOutStreamMap  Bitmapped representation of OutStreams grouped with this output stream. b0 represents OutStream 0, b1 OutStream 1, b2 OutStream 2 etc.
pdwInStreamMap  Bitmapped representation of InStreams grouped with this output stream. b0 represents InStream 0, b1 InStream 1, b2 InStream 2 etc.

HPI_ERR HPI_OutStreamGroupReset (  HPI_HSUBSYS *  phSubSys,
HPI_HOSTREAM  hOutStream
) 
 

Resets stream grouping information for a given out stream.

Note:
This function is only supported on on ASI6000 and ASI5000 adapters.
Returns:
0 on success, or one of the HPI Error codes.
Parameters:
phSubSys  HPI subsystem handle.
hOutStream  Handle to OutStream.

Generated on Tue Nov 18 12:59:30 2008 for AudioScience HPI by  doxygen 1.4.6-NO