Volume Control
[Mixer and Controls]

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

Functions
HPI_ERR	HPI_Volume_QueryChannels (const HPI_HSUBSYS *phSubSys, const HPI_HCONTROL hVolume, HW32 *pChannels)
	Get the number of channels supported by this volume control.
HPI_ERR	HPI_VolumeSetGain (HPI_HSUBSYS *phSubSys, HPI_HCONTROL hControl, short anLogGain[HPI_MAX_CHANNELS])
	Set the gain of a volume control.
HPI_ERR	HPI_VolumeGetGain (HPI_HSUBSYS *phSubSys, HPI_HCONTROL hControl, short anLogGain[HPI_MAX_CHANNELS])
	Gets the current gain of a volume control.
HPI_ERR	HPI_VolumeQueryRange (HPI_HSUBSYS *phSubSys, HPI_HCONTROL hControl, short *nMinGain_01dB, short *nMaxGain_01dB, short *nStepGain_01dB)
	Query the range of a volume or level control.
HPI_ERR	HPI_VolumeAutoFadeProfile (HPI_HSUBSYS *phSubSys, HPI_HCONTROL hControl, short anStopGain0_01dB[HPI_MAX_CHANNELS], HW32 dwDurationMs, HW16 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	HPI_VolumeAutoFade (HPI_HSUBSYS *phSubSys, HPI_HCONTROL hControl, short anStopGain0_01dB[HPI_MAX_CHANNELS], HW32 dwDurationMs)

---

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.

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.

---

Function Documentation

HPI_ERR HPI_Volume_QueryChannels (  const HPI_HSUBSYS *  phSubSys, const HPI_HCONTROL  hVolume, HW32 *  pChannels )

Get the number of channels supported by this volume control. Parameters: phSubSys  Pointer to HPI subsystem handle hVolume  Control to query pChannels  number of channels

HPI_ERR HPI_VolumeSetGain (  HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  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  Pointer to HPI subsystem handle. hControl  Handle to volume control. anLogGain  Gain in 100ths of a dB.

HPI_ERR HPI_VolumeGetGain (  HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  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  Pointer to HPI subsystem handle. 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 HPI_VolumeQueryRange (  HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  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  Pointer to HPI subsystem handle. 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 HPI_VolumeAutoFadeProfile (  HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  hControl, short  anStopGain0_01dB[HPI_MAX_CHANNELS], HW32  dwDurationMs, HW16  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  Pointer to HPI subsystem handle. 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.

HPI_ERR HPI_VolumeAutoFade (  HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  hControl, short  anStopGain0_01dB[HPI_MAX_CHANNELS], HW32  dwDurationMs )

Deprecated: See HPI_VolumeAutoFadeProfile(). Parameters: phSubSys  Pointer to HPI subsystem handle. hControl  Handle to a volume control. anStopGain0_01dB  The endpoint of the fade. dwDurationMs  Duration of fade in milliseconds.

---