AudioScience HPI Version_4.10.
Functions

Mixer Functions

Mixer

Functions

hpi_err_t HPI_MixerOpen (const hpi_hsubsys_t *phSubSys, uint16_t wAdapterIndex, hpi_handle_t *phMixer)
 Opens and initializes an adapters mixer.
hpi_err_t HPI_MixerClose (const hpi_hsubsys_t *phSubSys, hpi_handle_t hMixer)
 Closes a mixer.
hpi_err_t HPI_MixerGetControl (const hpi_hsubsys_t *phSubSys, hpi_handle_t hMixer, uint16_t wSrcNodeType, uint16_t wSrcNodeTypeIndex, uint16_t wDstNodeType, uint16_t wDstNodeTypeIndex, uint16_t wControlType, hpi_handle_t *phControl)
 Gets a mixer control.
hpi_err_t HPI_MixerGetControlByIndex (const hpi_hsubsys_t *phSubSys, hpi_handle_t hMixer, uint16_t wControlIndex, uint16_t *pwSrcNodeType, uint16_t *pwSrcNodeIndex, uint16_t *pwDstNodeType, uint16_t *pwDstNodeIndex, uint16_t *pwControlType, hpi_handle_t *phControl)
 Get the location and type of a mixer control by index.
hpi_err_t HPI_MixerStore (const hpi_hsubsys_t *phSubSys, hpi_handle_t hMixer, enum HPI_MIXER_STORE_COMMAND command, uint16_t wIndex)
 Execute a command on the Mixer Control store.

Function Documentation

hpi_err_t HPI_MixerOpen ( const hpi_hsubsys_t *  phSubSys,
uint16_t  wAdapterIndex,
hpi_handle_t phMixer 
)

Opens and initializes an adapters mixer.

An Adapter index is passed in and a Mixer handle is passed back. The handle is used for all future calls to that Mixer.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
wAdapterIndexIndex of adapter to be opened. Ranges from 0 to 15 and corresponds to the Adapter Index set on the adapter hardware.
phMixerReturned handle to the Mixer.

References HPI_IndexesToHandle().

hpi_err_t HPI_MixerClose ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hMixer 
)

Closes a mixer.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hMixerHandle to the adapter mixer to close.
hpi_err_t HPI_MixerGetControl ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hMixer,
uint16_t  wSrcNodeType,
uint16_t  wSrcNodeTypeIndex,
uint16_t  wDstNodeType,
uint16_t  wDstNodeTypeIndex,
uint16_t  wControlType,
hpi_handle_t phControl 
)

Gets a mixer control.

The control maybe located in one of three places:

  1. On a connection between a source node and a destination node.
    You specify both source and destination nodes (via type and type index).
  2. On a source node.
    You specify the source node and leave the destination node type and index as 0.
  3. On a destination node.
    You specify the destination node and leave the source node type and index as 0.
Note:
Not all adapters have controls at all nodes, or between all nodes. Consult the Mixer Map for your particular adapter to find out the location and type of controls in its mixer.

Say you have an audio adapter with a mixer that has the following layout:

mixer_get_control.png

You can see that the mixer has two meter controls, located on each of the Outstream source nodes, two volume controls, located between the OutStream sources and the LineOut destination nodes and one level control located on the LineOut destination node.

You would use the following code to obtain a handle to the volume control that lies on the connection between OutStream#1 and LineOut#0:

Example:
err = HPI_MixerGetControl(
                &hSubSys,
                hMixer,
                HPI_SOURCENODE_OSTREAM,
                1,
                HPI_DESTNODE_LINEOUT,
                0,
                HPI_CONTROL_VOLUME,
                &hVolControl
                );

You would use the following code to obtain a handle to the level control that lies on the LineOut#0 node:

Example:
        err = HPI_MixerGetControl(
                        &hSubSys,
                        hMixer,
                        0,
                        0,
                        HPI_DESTNODE_LINEOUT,
                        0,
                        HPI_CONTROL_LEVEL,
                        &hLevControl
                        );
Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hMixerMixer handle.
wSrcNodeTypeSource node type i.e. HPI_SOURCENODE_OSTREAM.
wSrcNodeTypeIndexIndex of particular source node type i.e. the 2nd HPI_SOURCENODE_OSTREAM would be specified as index=1.
wDstNodeTypeDestination node type i.e. HPI_DESTNODE_LINEOUT.
wDstNodeTypeIndexIndex of particular source node type i.e. the 3rd HPI_DESTNODE_LINEOUT would be specified as index=2
wControlTypeType of mixer control i.e. One of the HPI_CONTROLS
phControlHandle to the particular control

References HPI_IndexesToHandle().

hpi_err_t HPI_MixerGetControlByIndex ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hMixer,
uint16_t  wControlIndex,
uint16_t *  pwSrcNodeType,
uint16_t *  pwSrcNodeIndex,
uint16_t *  pwDstNodeType,
uint16_t *  pwDstNodeIndex,
uint16_t *  pwControlType,
hpi_handle_t phControl 
)

Get the location and type of a mixer control by index.

This function is primarily intended to be used to enumerate all the controls in a mixer. To enumerate all the mixer controls of an adapter, iterate wControlIndex from 0 until the function returns HPI_ERROR_INVALID_OBJ_INDEX. The iteration should not be terminated if error HPI_ERROR_CONTROL_DISABLED is returned. This indicates that a control that normally exists is disabled for some reason (possibly hardware failure). The application should not access such controls, but may for instance display a grayed-out GUI control.

A control may exist between two nodes, or on a single node in which case the non-existent node type is set to HPI_SOURCENODE_NONE or HPI_DESTNODE_NONE.

An invalid source node returns HPI_SOURCENODE_NONE, while an invalid destination node will return HPI_DESTNODE_NONE.

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Return values:
HPI_ERROR_INVALID_OBJ_INDEXwhen wControlIndex > number of mixer controls
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hMixerMixer handle.
wControlIndexControl Index to query.
pwSrcNodeTypeReturned source node type for control at index wControlIndex.
pwSrcNodeIndexReturned source node index for control at index wControlIndex.
pwDstNodeTypeReturned destination node type for control at index wControlIndex.
pwDstNodeIndexReturned destination node index for control at index wControlIndex.
pwControlTypeReturned control type for control at index wControlIndex.
phControlReturned control handle for control at index wControlIndex.

References HPI_DESTNODE_NONE, HPI_IndexesToHandle(), and HPI_SOURCENODE_NONE.

Referenced by HPI_Object_BlockParameters().

hpi_err_t HPI_MixerStore ( const hpi_hsubsys_t *  phSubSys,
hpi_handle_t  hMixer,
enum HPI_MIXER_STORE_COMMAND  command,
uint16_t  wIndex 
)

Execute a command on the Mixer Control store.

Valid commands are members of HPI_MIXER_STORE_COMMAND

Returns:
0 on success, or one of the HPI_ERROR_CODES.
Return values:
HPI_ERROR_INVALID_OBJ_INDEXwhen wControlIndex > number of mixer controls
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hMixerMixer handle.
commandCommand to execute.
wIndexOptional index.