Streams

Perform audio I/O and format conversion. More...


Modules

 Output Stream
 The following section describes the states a stream uses.
 Input Stream
 The following figure describes the states an InStream uses.

Enumerations

enum  HPI_FORMATS {
  HPI_FORMAT_MIXER_NATIVE = 0, HPI_FORMAT_PCM8_UNSIGNED = 1, HPI_FORMAT_PCM16_SIGNED = 2, HPI_FORMAT_MPEG_L1 = 3,
  HPI_FORMAT_MPEG_L2 = 4, HPI_FORMAT_MPEG_L3 = 5, HPI_FORMAT_DOLBY_AC2 = 6, HPI_FORMAT_DOLBY_AC3 = 7,
  HPI_FORMAT_PCM16_BIGENDIAN = 8, HPI_FORMAT_AA_TAGIT1_HITS = 9, HPI_FORMAT_AA_TAGIT1_INSERTS = 10, HPI_FORMAT_PCM32_SIGNED = 11,
  HPI_FORMAT_RAW_BITSTREAM = 12, HPI_FORMAT_AA_TAGIT1_HITS_EX1 = 13, HPI_FORMAT_PCM32_FLOAT = 14, HPI_FORMAT_PCM24_SIGNED = 15,
  HPI_FORMAT_OEM1 = 16, HPI_FORMAT_OEM2 = 17, HPI_FORMAT_UNDEFINED = 0xffff
}
 Audio format types. More...
enum  HPI_STREAM_STATES {
  HPI_STATE_STOPPED = 1, HPI_STATE_PLAYING = 2, HPI_STATE_RECORDING = 3, HPI_STATE_DRAINED = 4,
  HPI_STATE_SINEGEN = 5, HPI_STATE_WAIT = 6
}
 Stream States. More...
enum  HPI_MPEG_ANC_MODES { HPI_MPEG_ANC_HASENERGY = 0, HPI_MPEG_ANC_RAW = 1 }
 MPEG Ancillary Data modes. More...
enum  HPI_MPEG_MODES { HPI_MPEG_MODE_DEFAULT = 0, HPI_MPEG_MODE_STEREO = 1, HPI_MPEG_MODE_JOINTSTEREO = 2, HPI_MPEG_MODE_DUALCHANNEL = 3 }
 MPEG modes MPEG modes - can be used optionally for HPI_FormatCreate() parameter dwAttributes. More...

Functions

HPI_ERR HPI_FormatCreate (HPI_FORMAT *pFormat, HW16 wChannels, HW16 wFormat, HW32 dwSampleRate, HW32 dwBitRate, HW32 dwAttributes)
 Initialize an audio format structure, given various defining parameters.
HPI_ERR HPI_StreamEstimateBufferSize (HPI_FORMAT *pFormat, HW32 dwHostPollingRateInMilliSeconds, HW32 *dwRecommendedBufferSize)
 Given a format and rate that the buffer is processed, return the correct buffer size to support ping-pong buffering of audio.

Detailed Description

Perform audio I/O and format conversion.

Enumeration Type Documentation

enum HPI_FORMATS
 

Audio format types.

Enumerator:
HPI_FORMAT_MIXER_NATIVE  Used internally on adapter.
HPI_FORMAT_PCM8_UNSIGNED  8-bit unsigned PCM.

Windows equivalent is WAVE_FORMAT_PCM.

HPI_FORMAT_PCM16_SIGNED  16-bit signed PCM.

Windows equivalent is WAVE_FORMAT_PCM.

HPI_FORMAT_MPEG_L1  MPEG-1 Layer-1.
HPI_FORMAT_MPEG_L2  MPEG-1 Layer-2.

Windows equivalent is WAVE_FORMAT_MPEG.

The following table shows what combinations of mode and bitrate are possible:

Bitrate (kbs)

Mono

Stereo,
Joint Stereo or
Dual Channel

32X_
40__
48X_
56X_
64XX
80X_
96XX
112XX
128XX
160XX
192XX
224_X
256-X
320-X
384_X

HPI_FORMAT_MPEG_L3  MPEG-1 Layer-3.

Windows equivalent is WAVE_FORMAT_MPEG.

The following table shows what combinations of mode and bitrate are possible:

Bitrate (kbs)

Mono
Stereo @ 8,
11.025 and
12kHz*

Mono
Stereo @ 16,
22.050 and
24kHz*

Mono
Stereo @ 32,
44.1 and
48kHz

16XX_
24XX_
32XXX
40XXX
48XXX
56XXX
64XXX
80_XX
96_XX
112_XX
128_XX
144_X_
160_XX
192__X
224__X
256-_X
320-_X
* Available on the ASI6000 series only

HPI_FORMAT_DOLBY_AC2  Dolby AC-2.
HPI_FORMAT_DOLBY_AC3  Dolbt AC-3.
HPI_FORMAT_PCM16_BIGENDIAN  16-bit PCM big-endian.
HPI_FORMAT_AA_TAGIT1_HITS  TAGIT-1 algorithm - hits.
HPI_FORMAT_AA_TAGIT1_INSERTS  TAGIT-1 algorithm - inserts.
HPI_FORMAT_PCM32_SIGNED  32-bit signed PCM.

Windows equivalent is WAVE_FORMAT_PCM. Each sample is a 32bit word. The most significant 24 bits contain a 24-bit sample and the least significant 8 bits are set to 0.

HPI_FORMAT_RAW_BITSTREAM  Raw bitstream - unknown format.
HPI_FORMAT_AA_TAGIT1_HITS_EX1  TAGIT-1 algorithm hits - extended.
HPI_FORMAT_PCM32_FLOAT  32-bit PCM as an IEEE float.

Windows equivalent is WAVE_FORMAT_IEEE_FLOAT. Each sample is a 32bit word in IEEE754 floating point format. The range is +1.0 to -1.0, which corresponds to digital fullscale.

HPI_FORMAT_PCM24_SIGNED  24-bit PCM signed.

Windows equivalent is WAVE_FORMAT_PCM.

HPI_FORMAT_OEM1  OEM format 1 - private.
HPI_FORMAT_OEM2  OEM format 2 - private.
HPI_FORMAT_UNDEFINED  Undefined format.

enum HPI_STREAM_STATES
 

Stream States.

Enumerator:
HPI_STATE_STOPPED  State stopped - stream is stopped.
HPI_STATE_PLAYING  State playing - stream is playing audio.
HPI_STATE_RECORDING  State recording - stream is recording.
HPI_STATE_DRAINED  State drained - playing stream ran out of data to play.
HPI_STATE_SINEGEN  State generate sine - to be implemented.
HPI_STATE_WAIT  State wait - used for inter-card sync to mean waiting for all cards to be ready.

enum HPI_MPEG_ANC_MODES
 

MPEG Ancillary Data modes.

The mode for the ancillary data insertion or extraction to operate in.

Enumerator:
HPI_MPEG_ANC_HASENERGY  the MPEG frames have energy information stored in them (5 bytes per stereo frame, 3 per mono)
HPI_MPEG_ANC_RAW  the entire ancillary data field is taken up by data from the Anc data buffer On encode, the encoder will insert the energy bytes before filling the remainder of the ancillary data space with data from the ancillary data buffer.

enum HPI_MPEG_MODES
 

MPEG modes MPEG modes - can be used optionally for HPI_FormatCreate() parameter dwAttributes.

Using any mode setting other than HPI_MPEG_MODE_DEFAULT with single channel format will return an error.

Enumerator:
HPI_MPEG_MODE_DEFAULT  Causes the MPEG-1 Layer II bitstream to be recorded in single_channel mode when the number of channels is 1 and in stereo when the number of channels is 2.
HPI_MPEG_MODE_STEREO  Standard stereo without joint-stereo compression.
HPI_MPEG_MODE_JOINTSTEREO  Joint stereo.
HPI_MPEG_MODE_DUALCHANNEL  Left and Right channels are completely independent.

Function Documentation

HPI_ERR HPI_FormatCreate (  HPI_FORMAT *  pFormat,
HW16  wChannels,
HW16  wFormat,
HW32  dwSampleRate,
HW32  dwBitRate,
HW32  dwAttributes
) 
 

Initialize an audio format structure, given various defining parameters.

Used in HPI_InStreamSetFormat() and HPI_OutStreamSetFormat()

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
pFormat  Pointer to the format structure to be initialized.
wChannels  From 1 to 8.
wFormat  One of the HPI_FORMATS.
dwSampleRate  Sample rate in Hz. Samplerate must be between 8000 and 200000.
dwBitRate  Bits per second, must be supplied for MPEG formats, it is calculated for PCM formats.
dwAttributes  Format dependent attributes. E.g. HPI_MPEG_MODES

HPI_ERR HPI_StreamEstimateBufferSize (  HPI_FORMAT *  pFormat,
HW32  dwHostPollingRateInMilliSeconds,
HW32 *  dwRecommendedBufferSize
) 
 

Given a format and rate that the buffer is processed, return the correct buffer size to support ping-pong buffering of audio.

Calculate the minimum buffer size for a stream given the audio format that the stream will be set to use and the rate at which the host polls the stream state and reads or writes data. The buffer size returned by this function should be used as the minimum value passed to HPI_OutStreamHostBufferAllocate() or HPI_InStreamHostBufferAllocate(). If different formats and samplerates will be used on the stream, buffer size should be calculated for the highest datarate format, or the buffer should be freed and allocated again for each format change.

Enabling background bus mastering (BBM) places some additional constraints on your application. In order to allow the BBM to catch up if the host app has got behind, it must be possible to transfer data faster than it is being acquired. This means that the buffer needs to be bigger than minimum. Recommended size is at least 2x minimum. A buffer size of Nx4096 makes the best use of memory.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
pFormat  The format of the stream.
dwHostPollingRateInMilliSeconds  The polling rate of the host thread that fills or empties the buffer.
dwRecommendedBufferSize  The recommended buffer size in milliseconds.

Generated on Thu Jul 29 09:56:41 2010 for AudioScience HPI by  doxygen 1.4.6-NO