AudioScience HPI Version_4.10.
Defines | Enumerations | Functions

Volume Control

Controls

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 audiofade 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

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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hVolumeControl to query
pChannelsnumber 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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to volume control.
anLogGainGain 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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to volume control.
anLogGainGain 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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to volume control.
mutemute
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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to volume control.
mutemute
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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to volume control.
nMinGain_01dBMinimum gain setting in 100ths of a dB.
nMaxGain_01dBMaximum gain setting in 100ths of a dB.
nStepGain_01dBStep 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%).

volume_fade_profile.png
Returns:
0 on success, or one of the HPI_ERROR_CODES.
Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to volume control.
anStopGain0_01dBEnd point of the fade in 0.01ths of a dB.
dwDurationMsDuration 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.
wProfileThe 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:
phSubSysVestigial subsys handle (unused), may be set to NULL
hControlHandle to a volume control.
anStopGain0_01dBThe endpoint of the fade.
dwDurationMsDuration 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 audiofade profiles supported by this controls (may be none).

Parameters:
phSubSysVestigial subsys handle (unused), may be set to NULL
hVolumeControl to query
iEnumeration index
wProfileAutofade profile value

References HPI_ControlQuery().