Microsoft DirectX 8.1 (Visual Basic)

DSBUFFERDESC

The DSBUFFERDESC type describes the necessary characteristics of a new DirectSound buffer object. This type is used by the DirectSound8.CreateSoundBuffer and DirectSound8.CreatePrimarySoundBuffer methods.

Syntax

Type DSBUFFERDESC
  fxFormat As WaveFormatEx
  guid3DAlgorithm As String
  lBufferBytes As Long 
  lFlags As CONST_DSBCAPSFLAGS 
End Type

Members

fxFormat

WAVEFORMATEX type that specifies the wave format of the buffer.

guid3DAlgorithm

Unique identifier of the two-speaker virtualization algorithm to be used by DirectSound when 3-D effects are not available in hardware. If the DSCAPS_CTRL3D flag is not set for the sound buffer, this value is ignored. If DSBCAPS_CTRL3D is not set in lFlags, this member must be GUID_DS3DALG_DEFAULT. See Remarks.

The following algorithm identifiers are defined in the AUDIOSTRINGCONSTANTS module.

Value	Description	Availability
GUID_DS3DALG_DEFAULT	DirectSound uses the default algorithm. The default algorithm may be based on a Control Panel setting. In most cases it is DS3DALG_NO_VIRTUALIZATION. On WDM drivers, if the user has selected surround sound in Control Panel, the sound is panned among the left, center, right, and surround channels.	Applies to software mixing only. Available on WDM or Vxd Drivers.
GUID_DS3DALG_NO_VIRTUALIZATION	3-D effects are mapped onto normal stereo panning. At 90 degrees to the left, the sound is coming out of only the left speaker; at 90 degrees to the right, sound is coming out of only the right speaker. The vertical axis is ignored except for scaling of volume due to distance. Doppler shift and volume scaling are still applied, but the 3-D filtering is not performed on this buffer. This is the most efficient software implementation, but provides no virtual 3-D audio effect. When the DS3DALG_NO_VIRTUALIZATION flag is specified, HRTF processing is not done. Because DS3DALG_NO_VIRTUALIZATION uses only normal stereo panning, a buffer created with this algorithm may be accelerated by a 2-D hardware voice if no free 3-D hardware voices are available.	Applies to software mixing only. Available on WDM or Vxd Drivers.
GUID_DS3DALG_HRTF_FULL	3-D effects are processed with the high quality 3-D audio algorithm. This algorithm gives the highest quality 3-D audio effect, but uses more CPU cycles. See Remarks.	Applies to software mixing only. Available on Microsoft® Windows® 98 Second Edition and later operating systems when using WDM drivers.
GUID_DS3DALG_HRTF_LIGHT	3-D effects are processed with the efficient 3-D audio algorithm. This algorithm gives a good 3-D audio effect, but uses fewer CPU cycles than DS3DALG_HRTF_FULL. See Remarks.	Applies to software mixing only. Available on Windows 98 Second Edition and later operating systems when using WDM drivers.

lBufferBytes

Size of the buffer, in bytes. This value must be 0 when creating a buffer with the DSBCAPS_PRIMARYBUFFER flag. For secondary buffers, the size must be in the range from 4 to &H0FFFFFFF (268,435,455).

lFlags

Flags specifying the capabilities of the buffer. Can be zero or one or more of the constants of the CONST_DSBCAPSFLAGS enumeration.

Remarks

The DSBCAPS_LOCHARDWARE and DSBCAPS_LOCSOFTWARE flags are optional and mutually exclusive. DSBCAPS_LOCHARDWARE forces the buffer to reside in hardware, meaning that it will be mixed by the sound card. DSBCAPS_LOCSOFTWARE forces the buffer to reside in software, where it is mixed by the CPU. These flags are also returned in the lFlags member of the DSBCAPS type, where they indicate the actual location of the buffer.

The 3-D algorithms represent selection of the software emulation layer only—that is, the software algorithm that is used when no hardware is present for acceleration. In order to maximize hardware utilization, DS3DALG_NO_VIRTUALIZATION is treated as a special case. If no free 3-D hardware voices are available, the buffer is then treated as a 2-D buffer, but with 3-D API control. Specifically, when a sound buffer is created with DS3DALG_NO_VIRTUALIZATION, or when the buffer is played if the buffer was created with DSBPLAY_LOCDEFER, the following procedure is followed:

If a free hardware 3-D voice is available, that 3-D hardware voice is used.
If no free hardware 3-D voices are available and a 2-D hardware voice is available, that 2-D hardware voice will be used. This is possible because the DS3DALG_NO_VIRTUALIZATION algorithm is a simple stereo pan algorithm
If no free 2-D or 3-D hardware voices are available, the voice will be played in software using the DS3DALG_NO_VIRTUALIZATION algorithm.

If a speaker configuration other than DSSPEAKER_HEADPHONE or DSSPEAKER_STEREO is in effect, the processing will be done as if for a two-speaker configuration.

If a buffer is created using one of the HRTF algorithms, and the HRTF algorithm is not available on the system (for example, a non-WDM system), the method succeeds but the sound buffer uses DS3DALG_NO_VIRTUALIZATION instead.