 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
The IDsDriverBuffer::SetVolumePanmethod sets the volume and pan of the sound buffer to the value specified by the lVolumemember of the DSVOLUMEPANstructure.
HRESULT SetVolumePan( PDSVOLUMEPAN pDsVolumePan );
Parameters
- pDsVolumePan
- Pointer to a
DSVOLUMEPANstructure describing the new volume and pan
settings, in dB and in linear form.
Return Values
Returns DS_OK if successful, or one of the following error values otherwise:
- DSERR_INVALIDCALL
- DSERR_INVALIDPARAM
Remarks
DirectSound only calls this method if the sound buffer object was created with the DSBCAPS_CTRLVOLUME flag, the DSBCAPS_CTRLPAN flag, or both. If the sound device cannot support these controls, the driver should fail the IDsDriver::CreateSoundBuffercall whenever those control flags are specified.
The DirectSound API specifies volume in hundredths of decibels (dB), where 0 is the original volume of the stream (no adjustment done). Positive decibels correspond to amplification, and negative decibels correspond to attenuation. The decibel (dB) scale corresponds to the logarithmic hearing characteristics of the ear: positive decibels. An attenuation of 10 dB makes a buffer sound half as loud; an attenuation of 20 dB makes a buffer sound one quarter as loud. DirectSound volumes range from 0 (0 dB, no volume adjustment) to -10000 (-100 dB, basically silent). Amplification is not currently supported.
The DirectSound API also specifies pan in hundredths of dB, in the range of -10000 to 10000. Zero is the neutral value; a pan of 0 means that both channels are at full volume (that is, they are attenuated by 0 dB). At any other setting, one of the channels is at full volume and the other is attenuated. For example, a pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume. A pan of -10000 means that the right channel is silent (the sound is "all the way to the left"), and a pan of 10000 means that the left channel is silent (the sound is "all the way to the right"). Many readers may consider this behavior to be "balance" rather than "pan".
The volume and pan values are passed to DirectSound drivers in a DSVOLUMEPANstructure. Although both are specified, if the buffer only supports one or the other, the values reflect only the supported control. The structure specifies the input volume and pan (in hundredths of dB) in the lVolumeand lPanmembers. It also provides the linear equivalents in a fixed point 16.16 representation in the dwVolAmpFactormember (for volume) and the dwPanLeftAmpFactorand dwPanRightAmpFactormembers (for pan). Finally, since volume and pan are cumulative, it specifies the total combined linear factors in the dwTotalLeftAmpFactorand dwTotalRightAmpFactormembers. Drivers should use the values that are most convenient.
Regardless of whether the driver supports volume control, this function should return DS_OK if the requested volume is the same as the current volume.
Last updated on Tuesday, July 13, 2004