AudioScience HPI Version_4.23.16
Modules | Enumerations | Functions

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_t HPI_FormatCreate (struct hpi_format *pFormat, uint16_t wChannels, uint16_t wFormat, uint32_t dwSampleRate, uint32_t dwBitRate, uint32_t dwAttributes)
 Initialize an audio format structure, given various defining parameters.
hpi_err_t HPI_StreamEstimateBufferSize (struct hpi_format *pFormat, uint32_t dwHostPollingRateInMilliSeconds, uint32_t *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

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.

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.

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.

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_t HPI_FormatCreate ( struct hpi_format pFormat,
uint16_t  wChannels,
uint16_t  wFormat,
uint32_t  dwSampleRate,
uint32_t  dwBitRate,
uint32_t  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:
pFormatPointer to the format structure to be initialized.
wChannelsFrom 1 to 8.
wFormatOne of the HPI_FORMATS.
dwSampleRateSample rate in Hz. Samplerate must be between 8000 and 200000.
dwBitRateBits per second, must be supplied for MPEG formats, it is calculated for PCM formats.
dwAttributesFormat dependent attributes. E.g. HPI_MPEG_MODES

References HPI_ERROR_INCOMPATIBLE_SAMPLERATE, HPI_ERROR_INVALID_CHANNELS, HPI_ERROR_INVALID_FORMAT, HPI_FORMAT_AA_TAGIT1_HITS, HPI_FORMAT_AA_TAGIT1_HITS_EX1, HPI_FORMAT_AA_TAGIT1_INSERTS, HPI_FORMAT_DOLBY_AC2, HPI_FORMAT_MPEG_L1, HPI_FORMAT_MPEG_L2, HPI_FORMAT_MPEG_L3, HPI_FORMAT_OEM1, HPI_FORMAT_OEM2, HPI_FORMAT_PCM16_BIGENDIAN, HPI_FORMAT_PCM16_SIGNED, HPI_FORMAT_PCM24_SIGNED, HPI_FORMAT_PCM32_FLOAT, HPI_FORMAT_PCM32_SIGNED, HPI_FORMAT_PCM8_UNSIGNED, HPI_FORMAT_RAW_BITSTREAM, HPI_MPEG_MODE_DEFAULT, and HPI_MPEG_MODE_DUALCHANNEL.

hpi_err_t HPI_StreamEstimateBufferSize ( struct hpi_format pFormat,
uint32_t  dwHostPollingRateInMilliSeconds,
uint32_t *  dwRecommendedBufferSize 
)

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

dwRecommendedBufferSize = RoundUpToPowerOf2((bytes per polling period) * 2)

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. The size calculated is rounded up to the nearest power of two which is a requirement of background bus mastering (BBM) buffers.

For some adapters the physical buffers are preallocated during system initialization. The preallocation is based on the maximum format bandwidth supported and assumes a 10 millisecond polling rate. If a slower polling rate is used this calculation may return a value that exceeds the available preallocated physical buffers. In which case it is recommended to poll more frequently.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
pFormatThe format of the stream.
dwHostPollingRateInMilliSecondsThe polling rate of the host thread that fills or empties the buffer.
dwRecommendedBufferSizeThe recommended buffer size in milliseconds.

References hpi_format::dwBitRate, hpi_format::dwSampleRate, HPI_ERROR_INVALID_FORMAT, HPI_FORMAT_DOLBY_AC2, HPI_FORMAT_MPEG_L1, HPI_FORMAT_MPEG_L2, HPI_FORMAT_MPEG_L3, HPI_FORMAT_PCM16_BIGENDIAN, HPI_FORMAT_PCM16_SIGNED, HPI_FORMAT_PCM24_SIGNED, HPI_FORMAT_PCM32_FLOAT, HPI_FORMAT_PCM32_SIGNED, HPI_FORMAT_PCM8_UNSIGNED, hpi_format::wChannels, and hpi_format::wFormat.