Volume controls are usually situated on a "connection" between a source node and a destination node. More...

Defines
#define	HPI_UNITS_PER_dB 100
	volumes units are 100ths of a dB
#define	HPI_GAIN_OFF (-100 * HPI_UNITS_PER_dB)
	turns volume control OFF or MUTE
#define	HPI_BITMASK_ALL_CHANNELS (0xFFFFFFFF)
	channel mask specifying all channels
Enumerations
enum	HPI_VOLUME_AUTOFADES { HPI_VOLUME_AUTOFADE_LOG = 2, HPI_VOLUME_AUTOFADE_LINEAR = 3 }
	autofade profiles More...
Functions
hpi_err_t	HPI_Volume_QueryChannels (const hpi_hsubsys_t phSubSys, const hpi_handle_t hVolume, uint32_t pChannels)
	Get the number of channels supported by this volume control.
hpi_err_t	HPI_VolumeSetGain (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short anLogGain[HPI_MAX_CHANNELS])
	Set the gain of a volume control.
hpi_err_t	HPI_VolumeGetGain (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short anLogGain[HPI_MAX_CHANNELS])
	Gets the current gain of a volume control.
hpi_err_t	HPI_VolumeSetMute (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, uint32_t mute)
	Set the mute of a volume control.
hpi_err_t	HPI_VolumeGetMute (const hpi_hsubsys_t phSubSys, hpi_handle_t hControl, uint32_t mute)
	Gets the current mute setting of a volume control.
hpi_err_t	HPI_VolumeQueryRange (const hpi_hsubsys_t phSubSys, hpi_handle_t hControl, short nMinGain_01dB, short nMaxGain_01dB, short nStepGain_01dB)
	Query the range of a volume or level control.
hpi_err_t	HPI_VolumeAutoFadeProfile (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short anStopGain0_01dB[HPI_MAX_CHANNELS], uint32_t dwDurationMs, uint16_t wProfile)
	Starts an automatic ramp of the volume control from the current gain setting to the specified setting over the specified duration (in milliseconds).
hpi_err_t	HPI_VolumeAutoFade (const hpi_hsubsys_t *phSubSys, hpi_handle_t hControl, short anStopGain0_01dB[HPI_MAX_CHANNELS], uint32_t dwDurationMs)
hpi_err_t	HPI_Volume_QueryAutoFadeProfile (const hpi_hsubsys_t phSubSys, const hpi_handle_t hVolume, const uint32_t i, uint16_t wProfile)
	Enumerate autofade profiles supported by this controls (may be none).

Detailed Description

Volume controls are usually situated on a "connection" between a source node and a destination node.

They can also be present on source nodes, such as Ostream or LineIn. They control the gain/attenuation of the signal passing through them.

For example if you have a -10dB (relative to digital full-scale) signal passing through a volume control with a gain set to -6dB, then the output signal would be -16dB.

The units of gain parameters are milliBels (mB), equivalent to 1/1000 of a Bel, or 1/100 of a decibel. For example a gain of -14.00dB is represented as -1400, or (-14 * HPI_UNITS_PER_dB)

Gain parameters are stereo, stored in a 2 element array, element 0 is the left channel and element 1 is the right channel.

A gain value of HPI_GAIN_OFF will set the gain to its maximum attenuation or mute if the adapter supports it.

While most volume controls are attenuation only, some volume controls support gain as well. This is adapter and control dependant. Use the HPI_VolumeGetRange() function to determine if the control supports gain.

Define Documentation

#define HPI_UNITS_PER_dB 100

volumes units are 100ths of a dB

#define HPI_GAIN_OFF (-100 * HPI_UNITS_PER_dB)

turns volume control OFF or MUTE

#define HPI_BITMASK_ALL_CHANNELS (0xFFFFFFFF)

channel mask specifying all channels

Enumeration Type Documentation

enum HPI_VOLUME_AUTOFADES

autofade profiles

Enumerator:

HPI_VOLUME_AUTOFADE_LOG	log fade - dB attenuation changes linearly over time
HPI_VOLUME_AUTOFADE_LINEAR	linear fade - amplitude changes linearly

Function Documentation

hpi_err_t HPI_Volume_QueryChannels	(	const hpi_hsubsys_t *	phSubSys,
		const hpi_handle_t	hVolume,
		uint32_t *	pChannels
	)

Get the number of channels supported by this volume control.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hVolume	Control to query
pChannels	number of channels

References HPI_ControlQuery().

hpi_err_t HPI_VolumeSetGain	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		short	anLogGain[HPI_MAX_CHANNELS]
	)

Set the gain of a volume control.

Setting the gain of a volume control has the side effect that any autofades currently underway are terminated. The volume would become that of the current Set command.

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

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to volume control.
anLogGain	Gain in 100ths of a dB.

hpi_err_t HPI_VolumeGetGain	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		short	anLogGain[HPI_MAX_CHANNELS]
	)

Gets the current gain of a volume control.

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

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to volume control.
anLogGain	Gain in 100ths of a dB. If an autofade is in progess, it will be reflected here.

hpi_err_t HPI_VolumeSetMute	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint32_t	mute
	)

Set the mute of a volume control.

Mutes the volume control without affecting the current volume setting.

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

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to volume control.
mute	mute, should be 0 or HPI_BITMASK_ALL_CHANNELS

hpi_err_t HPI_VolumeGetMute	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		uint32_t *	mute
	)

Gets the current mute setting of a volume control.

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

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to volume control.
mute	mute, returns 0 or HPI_BITMASK_ALL_CHANNELS

hpi_err_t HPI_VolumeQueryRange	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		short *	nMinGain_01dB,
		short *	nMaxGain_01dB,
		short *	nStepGain_01dB
	)

Query the range of a volume or level control.

Gets the max,min and step of the specified volume control.

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

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to volume control.
nMinGain_01dB	Minimum gain setting in 100ths of a dB.
nMaxGain_01dB	Maximum gain setting in 100ths of a dB.
nStepGain_01dB	Step size in 100ths of a dB.

hpi_err_t HPI_VolumeAutoFadeProfile	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		short	anStopGain0_01dB[HPI_MAX_CHANNELS],
		uint32_t	dwDurationMs,
		uint16_t	wProfile
	)

Starts an automatic ramp of the volume control from the current gain setting to the specified setting over the specified duration (in milliseconds).

The gain starts at the current gain value and fades up/down to anStopGain0_01dB[] over the specified duration.

The fade profile can be either log or linear.

When wProfile==HPI_VOLUME_AUTOFADE_LOG the gain in dB changes linearly over time.

When wProfile==HPI_VOLUME_AUTOFADE_LINEAR the gain multiplier changes linearly over time. For example half way through the fade time of a fade from 0dB (100%) to -100dB (approx 0%) the gain will be -6dB (50%).

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

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to volume control.
anStopGain0_01dB	End point of the fade in 0.01ths of a dB.
dwDurationMs	Duration of fade in milliseconds. Minimum duration is 20 ms. Maximum duration is 100 seconds or 100 000 ms. Durations outside this range will be converted to the nearest limit.
wProfile	The profile, or shape of the autofade curve. Allowed values are HPI_VOLUME_AUTOFADE_LOG or HPI_VOLUME_AUTOFADE_LINEAR.

Referenced by HPI_VolumeAutoFade().

hpi_err_t HPI_VolumeAutoFade	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hControl,
		short	anStopGain0_01dB[HPI_MAX_CHANNELS],
		uint32_t	dwDurationMs
	)

Deprecated:: See HPI_VolumeAutoFadeProfile().

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hControl	Handle to a volume control.
anStopGain0_01dB	The endpoint of the fade.
dwDurationMs	Duration of fade in milliseconds.

References HPI_VOLUME_AUTOFADE_LOG, and HPI_VolumeAutoFadeProfile().

hpi_err_t HPI_Volume_QueryAutoFadeProfile	(	const hpi_hsubsys_t *	phSubSys,
		const hpi_handle_t	hVolume,
		const uint32_t	i,
		uint16_t *	wProfile
	)

Enumerate autofade profiles supported by this controls (may be none).

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
hVolume	Control to query
i	Enumeration index
wProfile	Autofade profile value

References HPI_ControlQuery().

Volume Control

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation