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 to store Mixer Controls.
hpi_err_t	HPI_MixerStoreStatus (const hpi_hsubsys_t phSubSys, hpi_handle_t hMixer, uint16_t pwControlsToStore)
	Fetch the number of controls waiting to be stored.

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:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
wAdapterIndex	Index of adapter to be opened. Ranges from 0 to 15 and corresponds to the Adapter Index set on the adapter hardware.
phMixer	Returned 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:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hMixer	Handle 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:

On a connection between a source node and a destination node.
You specify both source and destination nodes (via type and type index).
On a source node.
You specify the source node and leave the destination node type and index as 0.
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:

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:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hMixer	Mixer handle.
wSrcNodeType	Source node type i.e. HPI_SOURCENODE_OSTREAM.
wSrcNodeTypeIndex	Index of particular source node type i.e. the 2nd HPI_SOURCENODE_OSTREAM would be specified as index=1.
wDstNodeType	Destination node type i.e. HPI_DESTNODE_LINEOUT.
wDstNodeTypeIndex	Index of particular source node type i.e. the 3rd HPI_DESTNODE_LINEOUT would be specified as index=2
wControlType	Type of mixer control i.e. One of the HPI_CONTROLS
phControl	Handle 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_INDEX when wControlIndex > number of mixer controls

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hMixer	Mixer handle.
wControlIndex	Control Index to query.
pwSrcNodeType	Returned source node type for control at index wControlIndex.
pwSrcNodeIndex	Returned source node index for control at index wControlIndex.
pwDstNodeType	Returned destination node type for control at index wControlIndex.
pwDstNodeIndex	Returned destination node index for control at index wControlIndex.
pwControlType	Returned control type for control at index wControlIndex.
phControl	Returned 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 to store Mixer Controls.

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_INDEX when wControlIndex > number of mixer controls

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hMixer	Mixer handle.
command	Command to execute.
wIndex	Optional index.

hpi_err_t HPI_MixerStoreStatus	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hMixer,
		uint16_t *	pwControlsToStore
	)

Fetch the number of controls waiting to be stored.

This function has two uses. It can be used before calling HPI_MixerStore() to determine if there are any controls that need to be stored. Additionally, after calling HPI_MixerStore(), it can be called periodically to determine whether all the controls have been successfully saved.

Returns:: 0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hMixer	Mixer handle.
pwControlsToStore	Returned control count to store.

References HPI_ERROR_INVALID_OPERATION.

Mixer Functions

Functions

Function Documentation