DSDM_SETVOLUMEPAN

  • Article

This message sets the volume and pan of the sound buffer to the value specified by the IVolume member of the SDVOLUMEPAN structure.

typedef struct {
  DWORD dwMsg;
  DWORD dwInstance;
  LONG lVolume;
  LONG lPan;
} DSDMP_SETVOLUMEPAN;

Members

  • dwMsg
    Equals DSDM_SETVOLUMEPAN.
  • dwInstance
    DirectSoundBuffer instance data.
  • lVolume
    The new volume setting in decibels.
  • lPan
    The new pan setting in linear form.

Return Values

Returns DS_OK if successful, or one of the following error values otherwise.

Error value Description
DSERR_INVALIDCALL This call is not valid for the current state of this object.
DSERR_INVALIDPARAM An invalid parameter was passed to the returning function.

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 DSDM_CREATEBUFFER call 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. 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 dB, no volume adjustment, to -10000 dB. 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). 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 decibels (dB) and the right channel is at full volume. A pan of -10000 means that the right channel is silent and a pan of 10000 means that the left channel is silent.

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.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Dsdriver.h.

See Also

DirectSound Driver Messages

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.