SharpDX.DirectSound The assembly provides managed DirectSound API. ee416960 DirectSound DirectSound The structure contains all information necessary to uniquely describe the location, orientation, and motion of a 3D sound buffer. This structure is used with theIDirectSound3DBuffer8::GetAllParametersandIDirectSound3DBuffer8::SetAllParametersmethods. microsoft.directx_sdk.reference.ds3dbuffer DS3DBUFFER DS3DBUFFER Initializes a new instance of the class. No documentation. microsoft.directx_sdk.reference.ds3dbuffer unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.ds3dbuffer D3DVECTOR vPosition D3DVECTOR vPosition No documentation. microsoft.directx_sdk.reference.ds3dbuffer D3DVECTOR vVelocity D3DVECTOR vVelocity No documentation. microsoft.directx_sdk.reference.ds3dbuffer unsigned int dwInsideConeAngle unsigned int dwInsideConeAngle No documentation. microsoft.directx_sdk.reference.ds3dbuffer unsigned int dwOutsideConeAngle unsigned int dwOutsideConeAngle No documentation. microsoft.directx_sdk.reference.ds3dbuffer D3DVECTOR vConeOrientation D3DVECTOR vConeOrientation No documentation. microsoft.directx_sdk.reference.ds3dbuffer int lConeOutsideVolume int lConeOutsideVolume No documentation. microsoft.directx_sdk.reference.ds3dbuffer float flMinDistance float flMinDistance No documentation. microsoft.directx_sdk.reference.ds3dbuffer float flMaxDistance float flMaxDistance No documentation. microsoft.directx_sdk.reference.ds3dbuffer unsigned int dwMode unsigned int dwMode The structure describes the capabilities of a device. It is used by theIDirectSound8::GetCapsmethod.

Some audio cards may be unable to report accurately the number of available or free hardware buffers. This can happen, for example, when the card can play more sounds at lower sampling rates than at higher rates. In general, a nonzero value in any of the members relating to number of free hardware buffers signifies that at least one hardware resource of the appropriate type is available.

The unlock transfer rate for software buffers is 0, because the data need not be transferred anywhere. Similarly, the play processing overhead for hardware buffers is 0 because the mixing is done by the sound device.

 microsoft.directx_sdk.reference.dscaps DSCAPS DSCAPS Initializes a new instance of the class. No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_FLAGS dwFlags DSCAPS_FLAGS dwFlags No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMinSecondarySampleRate unsigned int dwMinSecondarySampleRate No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxSecondarySampleRate unsigned int dwMaxSecondarySampleRate No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwPrimaryBuffers unsigned int dwPrimaryBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxHwMixingAllBuffers unsigned int dwMaxHwMixingAllBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxHwMixingStaticBuffers unsigned int dwMaxHwMixingStaticBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxHwMixingStreamingBuffers unsigned int dwMaxHwMixingStreamingBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHwMixingAllBuffers unsigned int dwFreeHwMixingAllBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHwMixingStaticBuffers unsigned int dwFreeHwMixingStaticBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHwMixingStreamingBuffers unsigned int dwFreeHwMixingStreamingBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxHw3DAllBuffers unsigned int dwMaxHw3DAllBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxHw3DStaticBuffers unsigned int dwMaxHw3DStaticBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxHw3DStreamingBuffers unsigned int dwMaxHw3DStreamingBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHw3DAllBuffers unsigned int dwFreeHw3DAllBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHw3DStaticBuffers unsigned int dwFreeHw3DStaticBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHw3DStreamingBuffers unsigned int dwFreeHw3DStreamingBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwTotalHwMemBytes unsigned int dwTotalHwMemBytes No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwFreeHwMemBytes unsigned int dwFreeHwMemBytes No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwMaxContigFreeHwMemBytes unsigned int dwMaxContigFreeHwMemBytes No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwUnlockTransferRateHwBuffers unsigned int dwUnlockTransferRateHwBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwPlayCpuOverheadSwBuffers unsigned int dwPlayCpuOverheadSwBuffers No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwReserved1 unsigned int dwReserved1 No documentation. microsoft.directx_sdk.reference.dscaps unsigned int dwReserved2 unsigned int dwReserved2

The interface is used to manipulate sound capture buffers.

To obtain the interface, call the IDirectSoundCapture8::CreateCaptureBuffer method to obtain , then pass IID_IDirectSoundCaptureBuffer8 to IDirectSoundCaptureBuffer::QueryInterface.

In addition to the methods inherited from , the interface exposes the following methods, arranged by category.

Capture Management
Method Description
IDirectSoundCaptureBuffer8::Lock The Lock method locks a portion of the buffer. Locking the buffer returns references into the buffer, allowing the application to read or write audio data into memory.
IDirectSoundCaptureBuffer8::Start The Start method begins capturing data into the buffer. If the buffer is already capturing, the method has no effect.
IDirectSoundCaptureBuffer8::Stop The Stop method stops the buffer so that it is no longer capturing data. If the buffer is not capturing, the method has no effect.
IDirectSoundCaptureBuffer8::Unlock The Unlock method unlocks the buffer.
Effects
Method Description
The GetFXStatus method retrieves the status of capture effects.
The GetObjectInPath method retrieves an interface to an effect object associated with the buffer.
Initialization
Method Description
IDirectSoundCaptureBuffer8::Initialize The Initialize method initializes a capture buffer object. Because the IDirectSoundCapture8::CreateCaptureBufferIDirectSoundCapture8::CreateCaptureBuffer
Information
Method Description
IDirectSoundCaptureBuffer8::GetCaps The GetCaps method retrieves the capabilities of the buffer.
IDirectSoundCaptureBuffer8::GetCurrentPosition Address of a variable that receives the offset from the start of the buffer, in bytes, of the capture cursor. The parameter can be null if this value is not wanted.
IDirectSoundCaptureBuffer8::GetFormat The GetFormat method retrieves the waveform format of the capture buffer.
IDirectSoundCaptureBuffer8::GetStatus The GetStatus method retrieves the status of the capture buffer.

The LPDIRECTSOUNDCaptureBuffer8 type is defined as a reference to the interface:

 typedef struct  *LPDIRECTSOUNDCaptureBuffer8;
ee418162 IDirectSoundCaptureBuffer8 IDirectSoundCaptureBuffer8 Creates a buffer for capturing waveform audio. a reference to an instance of a structure containing values for the capture buffer being created. No documentation. HRESULT IDirectSoundCapture::CreateCaptureBuffer([In] LPCDSCBUFFERDESC pcDSCBufferDesc,[Out] LPDIRECTSOUNDCAPTUREBUFFER* ppDSCBuffer,[None] IUnknown* pUnkOuter) Retrieves an interface to an effect object associated with the buffer. Index of the object within objects of that class in the path. See Remarks. an effect object associated with the buffer HRESULT IDirectSoundCaptureBuffer8::GetObjectInPath([In] GUID* rguidObject,[None] int dwIndex,[In] GUID* rguidInterface,[Out] void** ppObject) Retrieves the status of capture effects. Sets the notification positions. The positions. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetObjectInPath method retrieves an interface to an effect object associated with the buffer.
Value of type REFGUID that specifies the unique class identifier of the object being searched for, such as .
Index of the object within objects of that class in the path. See Remarks.
Unique identifier of the desired interface, such as IID_IDirectSoundCaptureFXAec8.
Address of a variable that receives the desired interface reference.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_OBJECTNOTFOUND

The value in dwIndex is the index of the object within the array of effects in the structure passed to DirectSoundFullDuplexCreate8 or IDirectSoundCapture8::CreateCaptureBuffer.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getobjectinpath HRESULT IDirectSoundCaptureBuffer8::GetObjectInPath([In] const GUID& rguidObject,[In] unsigned int dwIndex,[In] const GUID& rguidInterface,[Out] void** ppObject) IDirectSoundCaptureBuffer8::GetObjectInPath The GetFXStatus method retrieves the status of capture effects.
Number of elements in the pdwFXStatus array.
Address of an array of DWORD variables that receive the status of each effect. This should contain the same number of elements as the array passed in the dwFXCount member of the structure passed to DirectSoundFullDuplexCreate8 or IDirectSoundCapture8::CreateCaptureBuffer. The possible values returned in the array are as follows:
ValueDescription
DSCFXR_LOCHARDWAREEffect is instantiated in hardware.
DSCFXR_LOCSOFTWAREEffect is instantiated in software.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getfxstatus HRESULT IDirectSoundCaptureBuffer8::GetFXStatus([In] unsigned int dwEffectsCount,[Out, Buffer] DSCFX_ENUM* pdwFXStatus) IDirectSoundCaptureBuffer8::GetFXStatus

The interface is used to manipulate sound capture buffers.

To obtain the interface, call the IDirectSoundCapture8::CreateCaptureBuffer method to obtain , then pass IID_IDirectSoundCaptureBuffer8 to IDirectSoundCaptureBuffer::QueryInterface.

In addition to the methods inherited from , the interface exposes the following methods, arranged by category.

Capture Management
Method Description
IDirectSoundCaptureBuffer8::Lock The Lock method locks a portion of the buffer. Locking the buffer returns references into the buffer, allowing the application to read or write audio data into memory.
IDirectSoundCaptureBuffer8::Start The Start method begins capturing data into the buffer. If the buffer is already capturing, the method has no effect.
IDirectSoundCaptureBuffer8::Stop The Stop method stops the buffer so that it is no longer capturing data. If the buffer is not capturing, the method has no effect.
IDirectSoundCaptureBuffer8::Unlock The Unlock method unlocks the buffer.
Effects
Method Description
The GetFXStatus method retrieves the status of capture effects.
The GetObjectInPath method retrieves an interface to an effect object associated with the buffer.
Initialization
Method Description
IDirectSoundCaptureBuffer8::Initialize The Initialize method initializes a capture buffer object. Because the IDirectSoundCapture8::CreateCaptureBufferIDirectSoundCapture8::CreateCaptureBuffer
Information
Method Description
IDirectSoundCaptureBuffer8::GetCaps The GetCaps method retrieves the capabilities of the buffer.
IDirectSoundCaptureBuffer8::GetCurrentPosition Address of a variable that receives the offset from the start of the buffer, in bytes, of the capture cursor. The parameter can be null if this value is not wanted.
IDirectSoundCaptureBuffer8::GetFormat The GetFormat method retrieves the waveform format of the capture buffer.
IDirectSoundCaptureBuffer8::GetStatus The GetStatus method retrieves the status of the capture buffer.

The LPDIRECTSOUNDCaptureBuffer8 type is defined as a reference to the interface:

 typedef struct  *LPDIRECTSOUNDCaptureBuffer8;
ee418162 IDirectSoundCaptureBuffer IDirectSoundCaptureBuffer True if the buffer is currently capturing. The offset from the start of the buffer, in bytes, of the capture cursor. The offset from the start of the buffer, in bytes, of the read cursor. True if the capture buffer is looping. Gets the waveform format of the capture buffer. The format. The Lock method locks a portion of the buffer. Locking the buffer returns references into the buffer, allowing the application to read or write audio data into memory. Offset, in bytes, from the start of the buffer to the point where the lock begins. Size, in bytes, of the portion of the buffer to lock. Because the buffer is conceptually circular, this number can exceed the number of bytes between dwOffset and the end of the buffer. Flags modifying the lock event. The following flags are defined: ValueDescription DSBLOCK_FROMWRITECURSORStart the lock at the write cursor. The dwOffset parameter is ignored. DSBLOCK_ENTIREBUFFERLock the entire buffer. The dwBytes parameter is ignored. Address of a variable that receives a pointer to the second locked part of the capture buffer. If NULL is returned, the ppvAudioPtr1 parameter points to the entire locked portion of the capture buffer. Address of a variable that receives a pointer to the first locked part of the buffer. HRESULT IDirectSoundCaptureBuffer::Lock([None] int dwOffset,[None] int dwBytes,[Out] void** ppvAudioPtr1,[Out] int* pdwAudioBytes1,[Out] void** ppvAudioPtr2,[Out, Optional] int* pdwAudioBytes2,[None] int dwFlags) The Unlock method releases a locked sound buffer. Address of the value retrieved in the ppvAudioPtr1 parameter of the {{Lock}} method. Address of the value retrieved in the ppvAudioPtr2 parameter of the IDirectSoundBuffer8::Lock method. No documentation. HRESULT IDirectSoundBuffer::Unlock([In, Buffer] void* pvAudioPtr1,[None] int dwAudioBytes1,[In, Buffer, Optional] void* pvAudioPtr2,[None] int dwAudioBytes2) Writes data to the buffer. Writes data to the buffer. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetCaps method retrieves the capabilities of the buffer. microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getcaps GetCaps GetCaps HRESULT IDirectSoundCaptureBuffer::GetCaps([Out] DSCBCAPS* pDSCBCaps) The GetStatus method retrieves the status of the capture buffer. microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getstatus GetStatus GetStatus HRESULT IDirectSoundCaptureBuffer::GetStatus([Out] DSCBSTATUS_FLAGS* pdwStatus) The GetCaps method retrieves the capabilities of the buffer.
Pointer to a structure that receives information about the capture buffer. On input, the dwSize member must specify the size of the structure in bytes.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY
microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getcaps HRESULT IDirectSoundCaptureBuffer::GetCaps([Out] DSCBCAPS* pDSCBCaps) IDirectSoundCaptureBuffer::GetCaps The GetCurrentPosition method retrieves the positions of the capture and read cursors in the buffer.

The capture cursor is ahead of the read cursor. The data after the read position up to and including the capture position is not necessarily valid data.
Address of a variable that receives the offset from the start of the buffer, in bytes, of the capture cursor. The parameter can be null if this value is not wanted.
Address of a variable that receives the offset from the start of the buffer, in bytes, of the read cursor.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY
microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getcurrentposition HRESULT IDirectSoundCaptureBuffer::GetCurrentPosition([Out, Optional] unsigned int* pdwCapturePosition,[Out, Optional] unsigned int* pdwReadPosition) IDirectSoundCaptureBuffer::GetCurrentPosition The GetFormat method retrieves the waveform format of the capture buffer.
Address of a structure that receives a description of the sound data in the capture buffer. To retrieve the buffer size needed to contain the format description, specify null.; in this case, the DWORD pointed to by the pdwSizeWritten parameter receives the size of the structure needed to receive complete format information.
Size, in bytes, of the structure. DirectSoundCapture writes, at most, dwSizeAllocated bytes to the structure.
Address of a variable that receives the number of bytes written to the structure; or, if pwfxFormat is null, the size of the structure that would be necessary to receive the information. This parameter can be null if the value is not wanted.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getformat HRESULT IDirectSoundCaptureBuffer::GetFormat([In] void* pwfxFormat,[In] unsigned int dwSizeAllocated,[Out, Optional] unsigned int* pdwSizeWritten) IDirectSoundCaptureBuffer::GetFormat The GetStatus method retrieves the status of the capture buffer.
Address of a variable that receives the status of the capture buffer. The status can be set to one or more of the following:
ValueDescription
The buffer is capturing audio data.
The buffer is looping.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.getstatus HRESULT IDirectSoundCaptureBuffer::GetStatus([Out] DSCBSTATUS_FLAGS* pdwStatus) IDirectSoundCaptureBuffer::GetStatus The Lock method locks a portion of the buffer. Locking the buffer returns references into the buffer, allowing the application to read or write audio data into memory.
Offset, in bytes, from the start of the buffer to the point where the lock begins.
Size, in bytes, of the portion of the buffer to lock. Because the buffer is conceptually circular, this number can exceed the number of bytes between dwOffset and the end of the buffer.
Address of a variable that receives a reference to the first locked part of the buffer.
Address of a variable that receives the number of bytes in the block at ppvAudioPtr1. If this value is less than dwBytes, the lock has wrapped and ppvAudioPtr2 points to a second block of data at the beginning of the buffer.
Address of a variable that receives a reference to the second locked part of the capture buffer. If null is returned, the ppvAudioPtr1 parameter points to the entire locked portion of the capture buffer.
Address of a variable that receives the number of bytes in the block at ppvAudioPtr2. If ppvAudioPtr2 is null, this value is zero.
Flags modifying the lock event. This value can be zero or the following flag:
ValueDescription
DSCBLOCK_ENTIREBUFFERIgnore dwBytes and lock the entire capture buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values:

Return code
DSERR_INVALIDPARAM
DSERR_INVALIDCALL

This method accepts an offset and a byte count, and returns two read references and their associated sizes. If the locked portion does not extend to the end of the buffer and wrap to the beginning, the second reference, ppvAudioBytes2, receives null. If the lock does wrap, ppvAudioBytes2 points to the beginning of the buffer.

If the application passes null for the ppvAudioPtr2 and pdwAudioBytes2 parameters, the lock extends no further than the end of the buffer and does not wrap.

The application should read data from the references returned by this method and then immediately call Unlock. The sound buffer should not remain locked while it is running; if it does, the capture cursor will reach the locked bytes and audio problems may result.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.lock HRESULT IDirectSoundCaptureBuffer::Lock([In] unsigned int dwOffset,[In] unsigned int dwBytes,[Out] void** ppvAudioPtr1,[Out] unsigned int* pdwAudioBytes1,[Out] void** ppvAudioPtr2,[Out, Optional] unsigned int* pdwAudioBytes2,[In] unsigned int dwFlags) IDirectSoundCaptureBuffer::Lock The Start method begins capturing data into the buffer. If the buffer is already capturing, the method has no effect.
Flags that specify the behavior of the buffer when capturing sound data. The following flag is defined:
ValueDescription
DSCBSTART_LOOPINGAfter the end of the buffer is reached, capture restarts at the beginning and continues until explicitly stopped.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

If the buffer is already capturing, a call to this method using a different value in dwFlags might not change the value returned by GetStatus.

If the application is multithreaded, the thread that starts the buffer must continue to exist as long as the buffer is capturing. Buffers created on WDM drivers stop capturing when the thread is terminated.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.start HRESULT IDirectSoundCaptureBuffer::Start([In] BOOL dwFlags) IDirectSoundCaptureBuffer::Start The Stop method stops the buffer so that it is no longer capturing data. If the buffer is not capturing, the method has no effect.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.stop HRESULT IDirectSoundCaptureBuffer::Stop() IDirectSoundCaptureBuffer::Stop The Unlock method unlocks the buffer.
Address of the value retrieved in the ppvAudioPtr1 parameter of the Lock method.
Number of bytes read from the pvAudioPtr1 parameter. See Remarks.
Address of the value retrieved in the ppvAudioPtr2 parameter of the IDirectSoundCaptureBuffer8::Lock method.
Number of bytes read from the pvAudioPtr2 parameter. See Remarks.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values:

Return code
DSERR_INVALIDPARAM
DSERR_INVALIDCALL

An application must pass both references, pvAudioPtr1 and pvAudioPtr2, returned by the IDirectSoundCaptureBuffer8::Lock method to ensure the correct pairing of IDirectSoundCaptureBuffer8::Lock and IDirectSoundCaptureBuffer8::Unlock. The second reference is needed even if zero bytes were written to the second reference.

The values in dwAudioBytes1 and dwAudioBytes2 must specify the number of bytes actually read from each part of the buffer, which might be less than the size of the lock. DirectSound uses these values to determine how much data to transfer from the device.

Make sure that the capture buffer does not remain locked for long periods of time.

 microsoft.directx_sdk.idirectsoundcapturebuffer8.idirectsoundcapturebuffer8.unlock HRESULT IDirectSoundCaptureBuffer::Unlock([In, Buffer] void* pvAudioPtr1,[In] unsigned int dwAudioBytes1,[In, Buffer, Optional] void* pvAudioPtr2,[In] unsigned int dwAudioBytes2) IDirectSoundCaptureBuffer::Unlock The structure describes the capabilities of a capture buffer. It is used by theIDirectSoundCaptureBuffer8::GetCapsmethod. microsoft.directx_sdk.reference.dscbcaps DSCBCAPS DSCBCAPS Initializes a new instance of the class. No documentation. microsoft.directx_sdk.reference.dscbcaps unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.dscbcaps DSCBCAPS_FLAGS dwFlags DSCBCAPS_FLAGS dwFlags No documentation. microsoft.directx_sdk.reference.dscbcaps unsigned int dwBufferBytes unsigned int dwBufferBytes No documentation. microsoft.directx_sdk.reference.dscbcaps unsigned int dwReserved unsigned int dwReserved The structure describes a capture buffer. It is used by theIDirectSoundCapture8::CreateCaptureBuffermethod and by theDirectSoundFullDuplexCreate8function.

An earlier version of this structure, DSCBUFFERDESC1, is maintained in Dsound.h for compatibility with DirectX 7 and earlier.

The flag is supported only on buffers created by an object of class CLSID_DirectSoundCapture8. If the IDirectSoundCapture8 interface was obtained from the DirectSoundCaptureCreate8 function, this flag is supported; if it was obtained from the earlier DirectSoundCaptureCreate function, it is not supported.

Capture effects require Microsoft Windows XP.

 microsoft.directx_sdk.reference.dscbufferdesc DSCBUFFERDESC DSCBUFFERDESC Initializes a new instance of the class. Gets a value indicating whether [wave mapped]. true if [wave mapped]; otherwise, false. Gets a value indicating whether [control effects]. true if [control effects]; otherwise, false. Gets or sets the format. The format. Describes effects supported by hardware for the buffer. No documentation. microsoft.directx_sdk.reference.dscbufferdesc unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.dscbufferdesc DSCBCAPS_FLAGS dwFlags DSCBCAPS_FLAGS dwFlags No documentation. microsoft.directx_sdk.reference.dscbufferdesc unsigned int dwBufferBytes unsigned int dwBufferBytes No documentation. microsoft.directx_sdk.reference.dscbufferdesc unsigned int dwReserved unsigned int dwReserved No documentation. microsoft.directx_sdk.reference.dscbufferdesc WAVEFORMATEX* lpwfxFormat WAVEFORMATEX lpwfxFormat No documentation. microsoft.directx_sdk.reference.dscbufferdesc unsigned int dwFXCount unsigned int dwFXCount No documentation. microsoft.directx_sdk.reference.dscbufferdesc DSCEFFECTDESC* lpDSCFXDesc DSCEFFECTDESC lpDSCFXDesc The structure describes the capabilities of the capture device. It is used by theIDirectSoundCapture8::GetCapsmethod. microsoft.directx_sdk.reference.dsccaps DSCCAPS DSCCAPS Initializes a new instance of the class. No documentation. microsoft.directx_sdk.reference.dsccaps unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.dsccaps unsigned int dwFlags unsigned int dwFlags No documentation. microsoft.directx_sdk.reference.dsccaps unsigned int dwFormats unsigned int dwFormats No documentation. microsoft.directx_sdk.reference.dsccaps unsigned int dwChannels unsigned int dwChannels The structure contains parameters for an effect associated with a capture buffer. microsoft.directx_sdk.reference.dsceffectdesc DSCEFFECTDESC DSCEFFECTDESC Initializes a new instance of the class.
Size of the structure, in bytes.
microsoft.directx_sdk.reference.dsceffectdesc unsigned int dwSize unsigned int dwSize
Flags that specify desired parameters of the effect. When this structure is passed to DirectSoundFullDuplexCreate8, or IDirectSoundCapture8::CreateCaptureBuffer, this member must be one of the values shown in the following table.
Value Description
Effect specified by guidDSCFXInstance must be in hardware.
Effect specified by guidDSCFXInstance must be in software.

On return, this member can contain one of the values shown in the following table.

Value Description
Effect was created in hardware.
Effect was created in software.
microsoft.directx_sdk.reference.dsceffectdesc DSCFX_ENUM dwFlags DSCFX_ENUM dwFlags
Value of type that specifies the class identifier of the effect. The following standard identifiers are defined.
Value Description
Acoustic echo cancellation.
Noise suppression.
microsoft.directx_sdk.reference.dsceffectdesc GUID guidDSCFXClass GUID guidDSCFXClass
Value of type that specifies the unique identifier of the preferred effect. The following standard identifiers are defined.
Value Description
Microsoft acoustic echo cancellation. Available in software only.
Microsoft noise suppression. Available in software only.
System default acoustic echo cancellation.
System default noise suppression.
microsoft.directx_sdk.reference.dsceffectdesc GUID guidDSCFXInstance GUID guidDSCFXInstance
Reserved. Must be zero.
microsoft.directx_sdk.reference.dsceffectdesc unsigned int dwReserved1 unsigned int dwReserved1
Reserved. Must be zero.
microsoft.directx_sdk.reference.dsceffectdesc unsigned int dwReserved2 unsigned int dwReserved2

The IDirectSoundFXChorus8 interface is used to set and retrieve effect parameters on a buffer that supports chorus.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXChorus8 interface exposes the following methods.

IDirectSoundFXChorus8 Members
Method Description
IDirectSoundFXChorus8::GetAllParameters The GetAllParameters method retrieves the chorus parameters of a buffer.
IDirectSoundFXChorus8::SetAllParameters The SetAllParameters method sets the chorus parameters of a buffer.
ee418208 IDirectSoundFXChorus IDirectSoundFXChorus Default number of milliseconds the input is delayed before it is played back. The default value is 50. Maximum number of milliseconds the input is delayed before it is played back. Minimum number of milliseconds the input is delayed before it is played back. Default percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. The default value is 10. Maximum percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Minimum percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Default percentage of output signal to feed back into the effect's input. The default value is 25. Maximum percentage of output signal to feed back into the effect's input. Minimum percentage of output signal to feed back into the effect's input. Default frequency of the LFO. The default value is 1.1. Maximum frequency of the LFO. Minimum frequency of the LFO. Positive 180 phase differential between left and right LFOs. Positive 90 phase differential between left and right LFOs. Default phase differential between left and right LFOs. The default value is Phase90. Maximum phase differential between left and right LFOs. Minimum phase differential between left and right LFOs. Negative 180 phase differential between left and right LFOs. Negative 90 phase differential between left and right LFOs. Zero phase differential between left and right LFOs. Default waveform shape of the LFO. By default, the waveform is a sine. Sine waveform shape of the LFO. Triangle waveform shape of the LFO. Default ratio of wet (processed) signal to dry (unprocessed) signal. Maximum ratio of wet (processed) signal to dry (unprocessed) signal. Minimum ratio of wet (processed) signal to dry (unprocessed) signal. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the chorus parameters of a buffer. microsoft.directx_sdk.idirectsoundfxchorus8.idirectsoundfxchorus8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXChorus::GetAllParameters([Out] DSFXChorus* pDsFxChorus) The SetAllParameters method sets the chorus parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxchorus8.idirectsoundfxchorus8.setallparameters HRESULT IDirectSoundFXChorus::SetAllParameters([In] const DSFXChorus* pcDsFxChorus) IDirectSoundFXChorus::SetAllParameters The GetAllParameters method retrieves the chorus parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxchorus8.idirectsoundfxchorus8.getallparameters HRESULT IDirectSoundFXChorus::GetAllParameters([Out] DSFXChorus* pDsFxChorus) IDirectSoundFXChorus::GetAllParameters

The IDirectSoundFXCompressor8 interface is used to set and retrieve effect parameters on a buffer that supports compression.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXCompressor8 interface exposes the following methods.

IDirectSoundFXCompressor8 Members
Method Description
IDirectSoundFXCompressor8::GetAllParameters The GetAllParameters method retrieves the compression parameters of a buffer.
IDirectSoundFXCompressor8::SetAllParameters The SetAllParameters method sets the compression parameters of a buffer.
ee418215 IDirectSoundFXCompressor IDirectSoundFXCompressor Default time before compression reaches its full value, in decibels (dB). The default value is 10 ms. Maximum time before compression reaches its full value, in decibels (dB). Minimum time before compression reaches its full value, in decibels (dB). Default output gain of signal after compression, in decibels (dB). The default value is 0 dB. Maximum output gain of signal after compression, in decibels (dB). Minimum output gain of signal after compression, in decibels (dB). Default time after threshold is reached before attack phase is started, in milliseconds. The default value is 4 ms. Maximum time after threshold is reached before attack phase is started, in milliseconds. Minimum time after threshold is reached before attack phase is started, in milliseconds. Default compression ratio. The default value is 3, which means 3:1 compression. Maximum compression ratio. Minimum compression ratio. Default speed at which compression is stopped after input drops below Threshold, in milliseconds. The default value is 200 ms. Maximum speed at which compression is stopped after input drops below Threshold, in milliseconds. Minimum speed at which compression is stopped after input drops below Threshold, in milliseconds. Default point at which compression begins, in decibels, in decibels (dB). The default value is -20 dB. Maximum point at which compression begins, in decibels, in decibels (dB). Minimum point at which compression begins, in decibels, in decibels (dB). Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the compression parameters of a buffer. microsoft.directx_sdk.idirectsoundfxcompressor8.idirectsoundfxcompressor8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXCompressor::GetAllParameters([Out] DSFXCompressor* pDsFxCompressor) The SetAllParameters method sets the compression parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxcompressor8.idirectsoundfxcompressor8.setallparameters HRESULT IDirectSoundFXCompressor::SetAllParameters([In] const DSFXCompressor* pcDsFxCompressor) IDirectSoundFXCompressor::SetAllParameters The GetAllParameters method retrieves the compression parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxcompressor8.idirectsoundfxcompressor8.getallparameters HRESULT IDirectSoundFXCompressor::GetAllParameters([Out] DSFXCompressor* pDsFxCompressor) IDirectSoundFXCompressor::GetAllParameters Contains information about a DirectSound device. Initializes a new instance of the class. The driver GUID. The description. Name of the module. Identifies the DirectSound driver being enumerated String that provides a textual description of the DirectSound device. String that specifies the module name of the DirectSound driver corresponding to this device.

The interface is used to create buffer objects, manage devices, and set up the environment. This interface supersedes and adds new methods.

Obtain this interface by using the DirectSoundCreate8 or DirectSoundFullDuplexCreate8 function, or by using CoCreateInstance or CoCreateInstanceEx to create an object of class CLSID_DirectSound8.

In addition to the methods inherited from , the interface exposes the following methods.

IDirectSound8 Members
Method Description
IDirectSound8::Compact The Compact method has no effect.
IDirectSound8::CreateSoundBuffer The CreateSoundBuffer method creates a sound buffer object to manage audio samples.
IDirectSound8::DuplicateSoundBuffer The DuplicateSoundBuffer method creates a new secondary buffer that shares the original buffer's memory.
IDirectSound8::GetCaps The GetCaps method retrieves the capabilities of the hardware device that is represented by the device object.
IDirectSound8::GetSpeakerConfig The GetSpeakerConfig method retrieves the speaker configuration.
IDirectSound8::Initialize The Initialize method initializes a device object that was created by using the CoCreateInstance function.
IDirectSound8::SetCooperativeLevel The SetCooperativeLevel method sets the cooperative level of the application for this sound device.
IDirectSound8::SetSpeakerConfig The SetSpeakerConfig method specifies the speaker configuration of the device.
The VerifyCertification method ascertains whether the device driver is certified for DirectX.

The LPDIRECTSOUND8 type is defined as a reference to the interface:

 typedef struct   *LPDIRECTSOUND8;

Only objects of class CLSID_DirectSound8 support this interface. All device objects created by DirectSoundCreate8 and DirectSoundFullDuplexCreate8 fall into this category. Objects of class CLSID_DirectSound, which include all those created by using the earlier DirectSoundCreate function, support only the earlier interface.

The behavior of CLSID_DirectSound8 objects is somewhat different from that of CLSID_DirectSound objects. These differences are found in the interface as well as the interface. Specific differences in the behavior of the newer object include the following:

  • In calls to and CreateSoundBuffer, cannot be set on a buffer with a non-mono format, and cannot be combined with .

  • New buffer creation flags are supported.

  • Buffers are not filled with silence on creation.

  • The interface returned by CreateSoundBuffer can be queried for the interface.

  • WAV formats in the structure that have the format tag are checked more strictly for validity.

 ee418035 IDirectSound8 IDirectSound8 Initializes a new instance of the class. Initializes a new instance of the class. The driver GUID. Verifies the certification. Return true if the driver is certified Retrieves the speaker configuration of the device. Sets the speaker configuration of the device. Enumerates the DirectSound devices installed in the system. A collection of the devices found. Duplicates the sound buffer. The source buffer. A duplicate of this soundBuffer. HRESULT IDirectSound::DuplicateSoundBuffer([In] IDirectSoundBuffer* pDSBufferOriginal,[Out] void** ppDSBufferDuplicate) IDirectSound::DuplicateSoundBuffer Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The VerifyCertification method ascertains whether the device driver is certified for DirectX.
Address of a DWORD variable that receives one of the values shown in the following table.
ValueDescription
DS_CERTIFIEDDriver is certified for DirectSound.
DS_UNCERTIFIEDDriver is not certified for DirectSound.

If the function succeeds, the return value is DS_OK.

If the function fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_INVALIDPARAM
DSERR_UNSUPPORTED

This method may attempt to retrieve certification information from the Internet.

On emulated devices, the method returns DSERR_UNSUPPORTED. Emulated devices are identified by the flag in the dwFlags member of .

 microsoft.directx_sdk.idirectsound8.idirectsound8.verifycertification HRESULT IDirectSound8::VerifyCertification([Out] unsigned int* pdwCertified) IDirectSound8::VerifyCertification

The IDirectSoundCapture8 interface is used to create sound capture buffers.

The interface is obtained by using the DirectSoundCaptureCreate8 or DirectSoundFullDuplexCreate8 functions, or by using CoCreateInstance or CoCreateInstanceEx to create an object of class CLSID_DirectSoundCapture8.

IDirectSoundCapture8 is a define for . The two interface names are interchangeable. However, objects supporting this interface can have different functionality, depending on their class. For more information, see DirectSoundCaptureCreate8 and IDirectSoundCapture8::CreateCaptureBuffer.

In addition to the methods inherited from , the IDirectSoundCapture8 interface exposes the following methods.

IDirectSoundCapture8 Members
Method Description
IDirectSoundCapture8::CreateCaptureBuffer The CreateCaptureBuffer method creates a buffer for capturing waveform audio.
IDirectSoundCapture8::GetCaps The GetCaps method retrieves the capabilities of the capture device.
IDirectSoundCapture8::Initialize The Initialize method initializes a capture device object created by using CoCreateInstance. Calling this method is not required when the DirectSoundCaptureCreate8 or DirectSoundFullDuplexCreate8 function is used to create the object.

The LPDIRECTSOUNDCAPTURE type is defined as a reference to the interface:

 typedef struct  *LPDIRECTSOUNDCAPTURE;
ee418154 IDirectSoundCapture IDirectSoundCapture Initializes a new instance of the class. Initializes a new instance of the class. Enumerates the DirectSoundCapture devices installed in the system. A collection of the devices found. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetCaps method retrieves the capabilities of the capture device. microsoft.directx_sdk.idirectsoundcapture8.idirectsoundcapture8.getcaps GetCaps GetCaps HRESULT IDirectSoundCapture::GetCaps([Out] DSCCAPS* pDSCCaps) The CreateCaptureBuffer method creates a buffer for capturing waveform audio.
Pointer to a structure containing values for the capture buffer being created.
Address of a variable that receives an interface reference. Use QueryInterface to obtain . See Remarks.
Address of the controlling object's interface for COM aggregation. Must be null.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values.

Return code
DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

On Microsoft Windows98 and Windows2000, each capture device supports a single buffer.

The interface is supported only on buffers created by an object of class CLSID_DirectSoundCapture8. If the IDirectSoundCapture8 interface was obtained from DirectSoundCaptureCreate8, is supported. If IDirectSoundCapture8 was obtained from the earlier DirectSoundCaptureCreate function, only is supported.

 microsoft.directx_sdk.idirectsoundcapture8.idirectsoundcapture8.createcapturebuffer HRESULT IDirectSoundCapture::CreateCaptureBuffer([In] const DSCBUFFERDESC* pcDSCBufferDesc,[Out] IDirectSoundCaptureBuffer** ppDSCBuffer,[In] IUnknown* pUnkOuter) IDirectSoundCapture::CreateCaptureBuffer The GetCaps method retrieves the capabilities of the capture device.
Pointer to a structure to be receive information about the capture device. When the method is called, the dwSize member must specify the size of the structure in bytes.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
microsoft.directx_sdk.idirectsoundcapture8.idirectsoundcapture8.getcaps HRESULT IDirectSoundCapture::GetCaps([Out] DSCCAPS* pDSCCaps) IDirectSoundCapture::GetCaps

The IDirectSoundFXDistortion8 interface is used to set and retrieve effect parameters on a buffer that supports distortion.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXDistortion8 interface exposes the following methods.

IDirectSoundFXDistortion8 Members
Method Description
IDirectSoundFXDistortion8::GetAllParameters The GetAllParameters method retrieves the distortion parameters of a buffer.
IDirectSoundFXDistortion8::SetAllParameters The SetAllParameters method sets the distortion parameters of a buffer.
ee418218 IDirectSoundFXDistortion IDirectSoundFXDistortion Default percentage of distortion intensity. Maximum percentage of distortion intensity. Minimum percentage of distortion intensity. Default amount of signal change after distortion. Maximum amount of signal change after distortion. Minimum amount of signal change after distortion. Default width of frequency band that determines range of harmonic content addition. Maximum width of frequency band that determines range of harmonic content addition. Minimum width of frequency band that determines range of harmonic content addition. Default center frequency of harmonic content addition. Maximum center frequency of harmonic content addition. Minimum center frequency of harmonic content addition. Default filter cutoff for high-frequency harmonics attenuation. Maximum filter cutoff for high-frequency harmonics attenuation. Minimum filter cutoff for high-frequency harmonics attenuation. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the distortion parameters of a buffer. microsoft.directx_sdk.idirectsoundfxdistortion8.idirectsoundfxdistortion8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXDistortion::GetAllParameters([Out] DSFXDistortion* pDsFxDistortion) The SetAllParameters method sets the distortion parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK or S_FALSE. See the Remarks for . If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxdistortion8.idirectsoundfxdistortion8.setallparameters HRESULT IDirectSoundFXDistortion::SetAllParameters([In] const DSFXDistortion* pcDsFxDistortion) IDirectSoundFXDistortion::SetAllParameters The GetAllParameters method retrieves the distortion parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxdistortion8.idirectsoundfxdistortion8.getallparameters HRESULT IDirectSoundFXDistortion::GetAllParameters([Out] DSFXDistortion* pDsFxDistortion) IDirectSoundFXDistortion::GetAllParameters

The IDirectSoundFXEcho8 interface is used to set and retrieve effect parameters on a buffer that supports echo.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXEcho8 interface exposes the following methods.

IDirectSoundFXEcho8 Members
Method Description
IDirectSoundFXEcho8::GetAllParameters The GetAllParameters method retrieves the echo parameters of a buffer.
IDirectSoundFXEcho8::SetAllParameters The SetAllParameters method sets the echo parameters of a buffer.
ee418221 IDirectSoundFXEcho IDirectSoundFXEcho Default percentage of output fed back into input. Maximum percentage of output fed back into input. Minimum percentage of output fed back into input. Default delay for left channel, in milliseconds. Maximum delay for left channel, in milliseconds. Minimum delay for left channel, in milliseconds. Default value that specifies whether to swap left and right delays with each successive echo. The default value is zero, meaning no swap. Maximum value that specifies whether to swap left and right delays with each successive echo. The default value is zero, meaning no swap. Minimum value that specifies whether to swap left and right delays with each successive echo. The default value is zero, meaning no swap. Default delay for right channel, in milliseconds. Maximum delay for right channel, in milliseconds. Minimum delay for right channel, in milliseconds. Default ratio of wet (processed) signal to dry (unprocessed) signal. Maximum ratio of wet (processed) signal to dry (unprocessed) signal. Minimum ratio of wet (processed) signal to dry (unprocessed) signal. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the echo parameters of a buffer. microsoft.directx_sdk.idirectsoundfxecho8.idirectsoundfxecho8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXEcho::GetAllParameters([Out] DSFXEcho* pDsFxEcho) The SetAllParameters method sets the echo parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxecho8.idirectsoundfxecho8.setallparameters HRESULT IDirectSoundFXEcho::SetAllParameters([In] const DSFXEcho* pcDsFxEcho) IDirectSoundFXEcho::SetAllParameters The GetAllParameters method retrieves the echo parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxecho8.idirectsoundfxecho8.getallparameters HRESULT IDirectSoundFXEcho::GetAllParameters([Out] DSFXEcho* pDsFxEcho) IDirectSoundFXEcho::GetAllParameters Enumerator callback for DirectSound and DirectCaptureSound. Initializes a new instance of the class. Natives the pointer. Gets or sets the device informations. The device informations.

The IDirectSoundFXFlanger8 interface is used to set and retrieve effect parameters on a buffer that supports flange.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXFlanger8 interface exposes the following methods.

IDirectSoundFXFlanger8 Members
Method Description
IDirectSoundFXFlanger8::GetAllParameters The GetAllParameters method retrieves the flange parameters of a buffer.
IDirectSoundFXFlanger8::SetAllParameters The SetAllParameters method sets the flange parameters of a buffer.
ee418225 IDirectSoundFXFlanger IDirectSoundFXFlanger Default number of milliseconds the input is delayed before it is played back. Maximum number of milliseconds the input is delayed before it is played back. Minimum number of milliseconds the input is delayed before it is played back. Default percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Maximum percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Minimum percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Default percentage of output signal to feed back into the effect's input. Maximum percentage of output signal to feed back into the effect's input. Minimum percentage of output signal to feed back into the effect's input. Default frequency of the LFO(low-frequency oscillator). Maximum frequency of the LFO(low-frequency oscillator). Minimum frequency of the LFO(low-frequency oscillator). Positive 180 phase differential between left and right LFOs. Positive 90 phase differential between left and right LFOs. Default phase differential between left and right LFOs. Maximum phase differential between left and right LFOs. Minimum phase differential between left and right LFOs. Negative 180 phase differential between left and right LFOs. Negative 90 phase differential between left and right LFOs. Zero phase differential between left and right LFOs. Default waveform shape of the LFO. By default, the waveform is a sine. Sine waveform shape of the LFO. By default, the waveform is a sine. Triangular waveform shape of the LFO. By default, the waveform is a sine. Default ratio of wet (processed) signal to dry (unprocessed) signal. Maximum ratio of wet (processed) signal to dry (unprocessed) signal. Minimum ratio of wet (processed) signal to dry (unprocessed) signal. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the flange parameters of a buffer. microsoft.directx_sdk.idirectsoundfxflanger8.idirectsoundfxflanger8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXFlanger::GetAllParameters([Out] DSFXFlanger* pDsFxFlanger) The SetAllParameters method sets the flange parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxflanger8.idirectsoundfxflanger8.setallparameters HRESULT IDirectSoundFXFlanger::SetAllParameters([In] const DSFXFlanger* pcDsFxFlanger) IDirectSoundFXFlanger::SetAllParameters The GetAllParameters method retrieves the flange parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxflanger8.idirectsoundfxflanger8.getallparameters HRESULT IDirectSoundFXFlanger::GetAllParameters([Out] DSFXFlanger* pDsFxFlanger) IDirectSoundFXFlanger::GetAllParameters

The IDirectSoundFullDuplex8 interface represents a full-duplex stream.

The interface is obtained by using the DirectSoundFullDuplexCreate8 function. This function initializes DirectSound capture and playback.

The interface can also be obtained by using CoCreateInstance or CoCreateInstanceEx to create an object of class CLSID_DirectSoundFullDuplex8.

IDirectSoundFullDuplex8 is a define for . The interface names are interchangeable.

In addition to the methods inherited from , the IDirectSoundFullDuplex8 interface exposes the following method.

IDirectSoundFullDuplex8 Members
Method Description
IDirectSoundFullDuplex8::Initialize The Initialize method initializes a full duplex object that was created by using CoCreateInstance.

The LPDIRECTSOUNDFULLDUPLEX type is defined as a reference to .

 typedef struct  *LPDIRECTSOUNDFULLDUPLEX;
Info

Operating System: Requires Microsoft Windows XP or later.

Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 ee418204 IDirectSoundFullDuplex IDirectSoundFullDuplex Initializes a new instance of the class. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion.

The IDirectSoundFXGargle8 interface is used to set and retrieve effect parameters on a buffer that supports amplitude modulation.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXGargle8 interface exposes the following methods.

IDirectSoundFXGargle8 Members
Method Description
IDirectSoundFXGargle8::GetAllParameters The GetAllParameters method retrieves the amplitude modulation parameters of a buffer.
IDirectSoundFXGargle8::SetAllParameters The SetAllParameters method sets the amplitude modulation parameters of a buffer.
ee418228 IDirectSoundFXGargle IDirectSoundFXGargle Default rate of modulation, in Hertz. Maximum rate of modulation, in Hertz. Minimum rate of modulation, in Hertz. Default shape of the modulation waveform. Square shape of the modulation waveform. Triangular shape of the modulation waveform. Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the amplitude modulation parameters of a buffer. microsoft.directx_sdk.idirectsoundfxgargle8.idirectsoundfxgargle8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXGargle::GetAllParameters([Out] DSFXGargle* pDsFxGargle) The SetAllParameters method sets the amplitude modulation parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value can be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxgargle8.idirectsoundfxgargle8.setallparameters HRESULT IDirectSoundFXGargle::SetAllParameters([In] const DSFXGargle* pcDsFxGargle) IDirectSoundFXGargle::SetAllParameters The GetAllParameters method retrieves the amplitude modulation parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value can be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxgargle8.idirectsoundfxgargle8.getallparameters HRESULT IDirectSoundFXGargle::GetAllParameters([Out] DSFXGargle* pDsFxGargle) IDirectSoundFXGargle::GetAllParameters The structure contains parameters for acoustic echo cancellation in a capture buffer.

The dwMode member is ignored when this structure is passed to IDirectSoundCaptureFXAec8::SetAllParameters.

Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.reference.dscfxaec DSCFX_AEC_MODE DSCFX_AEC_MODE
Boolean value that specifies whether the effect is enabled.
microsoft.directx_sdk.reference.dscfxaec DSCFX_AEC_MODE_PASS_THROUGH DSCFX_AEC_MODE_PASS_THROUGH
Boolean value that specifies whether to enable background comfort noise, which makes the capture signal sound more natural by preventing periods of dead silence. By default, background comfort noise is not enabled.
microsoft.directx_sdk.reference.dscfxaec DSCFX_AEC_MODE_HALF_DUPLEX DSCFX_AEC_MODE_HALF_DUPLEX
Operation mode. This member contains one of the following values.
Value Description
The effect is passing capture and render data through without modifying it.
The effect is running in half duplex mode. Not presently supported.
The effect is running in full duplex mode.
microsoft.directx_sdk.reference.dscfxaec DSCFX_AEC_MODE_FULL_DUPLEX DSCFX_AEC_MODE_FULL_DUPLEX

The KSPROPERTY_AEC_STATUS property is used to monitor the status of an AEC node (KSNODETYPE_ACOUSTIC_ECHO_CANCEL). This is an optional property of an AEC node.

The three least significant bits in the AEC status flags (see preceding table) represent the convergence history (CH) of the AEC algorithm. The CH status bits can be used by a Microsoft DirectSound application to determine whether the algorithm has converged and also whether it has remained in the converged state since the time that it started processing data. Depending on the audio hardware, the AEC algorithm might fail to converge, in which case the resulting capture buffer is likely to include the echo from the speakers.

When the filter containing the AEC node is created or the node is reset, the AEC algorithm initially sets the three CH status bits to zero. This setting represents the uninitialized state, AEC_STATUS_FD_HISTORY_UNINITIALIZED.

After the AEC algorithm converges, the CH status switches to the converged state, AEC_STATUS_FD_HISTORY_CONTINUOUSLY_CONVERGED. If the AEC algorithm ever loses convergence, the CH status switches to the diverged state, AEC_STATUS_FD_HISTORY_PREVIOUSLY_DIVERGED. Although the status is most likely to switch to the diverged state from the converged state, it might also switch directly from the uninitialized state to the diverged state. After the CH status has switched to the diverged state, it will remain in that state until the algorithm is reset or starvation is detected.

When the AEC system filter detects starvation at any of its four pins--capture in, capture out, render in, or render out--it resets its internal state, including the convergence history.

Note that bit 2 of the three CH status bits is not currently used.

As an alternative to using the CH status bits, the application can monitor the real-time convergence status by checking the AEC_STATUS_FD_CURRENTLY_CONVERGED flag bit. If this bit is set, the algorithm is currently converged. The algorithm can lose convergence temporarily when changes occur in the acoustic path. The real-time convergence flag is filtered to prevent such momentary losses from inappropriately switching the CH status bits to the DSCFX_AEC_STATUS_FD_HISTORY_PREVIOUSLY_DIVERGED state.

 ff537230 DSCFX_AEC_STATUS DSCFX_AEC_STATUS No documentation. ff537230 DSCFX_AEC_STATUS_HISTORY_UNINITIALIZED DSCFX_AEC_STATUS_HISTORY_UNINITIALIZED No documentation. ff537230 DSCFX_AEC_STATUS_HISTORY_CONTINUOUSLY_CONVERGED DSCFX_AEC_STATUS_HISTORY_CONTINUOUSLY_CONVERGED No documentation. ff537230 DSCFX_AEC_STATUS_HISTORY_PREVIOUSLY_DIVERGED DSCFX_AEC_STATUS_HISTORY_PREVIOUSLY_DIVERGED No documentation. ff537230 DSCFX_AEC_STATUS_CURRENTLY_CONVERGED DSCFX_AEC_STATUS_CURRENTLY_CONVERGED No documentation. DSBCAPS_FLAGS DSBCAPS_FLAGS No documentation. DSBCAPS_PRIMARYBUFFER DSBCAPS_PRIMARYBUFFER No documentation. DSBCAPS_STATIC DSBCAPS_STATIC No documentation. DSBCAPS_LOCHARDWARE DSBCAPS_LOCHARDWARE No documentation. DSBCAPS_LOCSOFTWARE DSBCAPS_LOCSOFTWARE No documentation. DSBCAPS_CTRL3D DSBCAPS_CTRL3D No documentation. DSBCAPS_CTRLFREQUENCY DSBCAPS_CTRLFREQUENCY No documentation. DSBCAPS_CTRLPAN DSBCAPS_CTRLPAN No documentation. DSBCAPS_CTRLVOLUME DSBCAPS_CTRLVOLUME No documentation. DSBCAPS_CTRLPOSITIONNOTIFY DSBCAPS_CTRLPOSITIONNOTIFY No documentation. DSBCAPS_CTRLFX DSBCAPS_CTRLFX No documentation. DSBCAPS_STICKYFOCUS DSBCAPS_STICKYFOCUS No documentation. DSBCAPS_GLOBALFOCUS DSBCAPS_GLOBALFOCUS No documentation. DSBCAPS_GETCURRENTPOSITION2 DSBCAPS_GETCURRENTPOSITION2 No documentation. DSBCAPS_MUTE3DATMAXDISTANCE DSBCAPS_MUTE3DATMAXDISTANCE No documentation. DSBCAPS_LOCDEFER DSBCAPS_LOCDEFER No documentation. DSBCAPS_TRUEPLAYPOSITION DSBCAPS_TRUEPLAYPOSITION None. None None No documentation. DSBSTATUS_FLAGS DSBSTATUS_FLAGS No documentation. DSBSTATUS_PLAYING DSBSTATUS_PLAYING No documentation. DSBSTATUS_BUFFERLOST DSBSTATUS_BUFFERLOST No documentation. DSBSTATUS_LOOPING DSBSTATUS_LOOPING No documentation. DSBSTATUS_LOCHARDWARE DSBSTATUS_LOCHARDWARE No documentation. DSBSTATUS_LOCSOFTWARE DSBSTATUS_LOCSOFTWARE No documentation. DSBSTATUS_TERMINATED DSBSTATUS_TERMINATED None. None None The structure describes the capabilities of a device. It is used by theIDirectSound8::GetCapsmethod.

Some audio cards may be unable to report accurately the number of available or free hardware buffers. This can happen, for example, when the card can play more sounds at lower sampling rates than at higher rates. In general, a nonzero value in any of the members relating to number of free hardware buffers signifies that at least one hardware resource of the appropriate type is available.

The unlock transfer rate for software buffers is 0, because the data need not be transferred anywhere. Similarly, the play processing overhead for hardware buffers is 0 because the mixing is done by the sound device.

 microsoft.directx_sdk.reference.dscaps DSCAPS_FLAGS DSCAPS_FLAGS No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_PRIMARYMONO DSCAPS_PRIMARYMONO No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_PRIMARYSTEREO DSCAPS_PRIMARYSTEREO No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_PRIMARY8BIT DSCAPS_PRIMARY8BIT No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_PRIMARY16BIT DSCAPS_PRIMARY16BIT No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_CONTINUOUSRATE DSCAPS_CONTINUOUSRATE No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_EMULDRIVER DSCAPS_EMULDRIVER No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_CERTIFIED DSCAPS_CERTIFIED No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_SECONDARYMONO DSCAPS_SECONDARYMONO No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_SECONDARYSTEREO DSCAPS_SECONDARYSTEREO No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_SECONDARY8BIT DSCAPS_SECONDARY8BIT No documentation. microsoft.directx_sdk.reference.dscaps DSCAPS_SECONDARY16BIT DSCAPS_SECONDARY16BIT None. None None No documentation. DSCBCAPS_FLAGS DSCBCAPS_FLAGS No documentation. DSCBCAPS_WAVEMAPPED DSCBCAPS_WAVEMAPPED No documentation. DSCBCAPS_CTRLFX DSCBCAPS_CTRLFX None. None None No documentation. DSCBSTATUS_FLAGS DSCBSTATUS_FLAGS No documentation. DSCBSTATUS_CAPTURING DSCBSTATUS_CAPTURING No documentation. DSCBSTATUS_LOOPING DSCBSTATUS_LOOPING None. None None The structure describes the capabilities of the capture device. It is used by theIDirectSoundCapture8::GetCapsmethod. microsoft.directx_sdk.reference.dsccaps DSCCAPS_FLAGS DSCCAPS_FLAGS No documentation. microsoft.directx_sdk.reference.dsccaps DSCCAPS_EMULDRIVER DSCCAPS_EMULDRIVER No documentation. microsoft.directx_sdk.reference.dsccaps DSCCAPS_CERTIFIED DSCCAPS_CERTIFIED No documentation. microsoft.directx_sdk.reference.dsccaps DSCCAPS_MULTIPLECAPTURE DSCCAPS_MULTIPLECAPTURE None. None None The structure contains parameters for an effect associated with a capture buffer. microsoft.directx_sdk.reference.dsceffectdesc DSCFX_ENUM DSCFX_ENUM
Size of the structure, in bytes.
microsoft.directx_sdk.reference.dsceffectdesc DSCFX_LOCHARDWARE DSCFX_LOCHARDWARE
Flags that specify desired parameters of the effect. When this structure is passed to DirectSoundFullDuplexCreate8, or IDirectSoundCapture8::CreateCaptureBuffer, this member must be one of the values shown in the following table.
Value Description
Effect specified by guidDSCFXInstance must be in hardware.
Effect specified by guidDSCFXInstance must be in software.

On return, this member can contain one of the values shown in the following table.

Value Description
Effect was created in hardware.
Effect was created in software.
microsoft.directx_sdk.reference.dsceffectdesc DSCFX_LOCSOFTWARE DSCFX_LOCSOFTWARE No documentation. DSSCL_ENUM DSSCL_ENUM No documentation. DSSCL_NORMAL DSSCL_NORMAL No documentation. DSSCL_PRIORITY DSSCL_PRIORITY No documentation. DSSCL_EXCLUSIVE DSSCL_EXCLUSIVE No documentation. DSSCL_WRITEPRIMARY DSSCL_WRITEPRIMARY No documentation. DSOUND_ENUM_1 DSOUND_ENUM_1 No documentation. DSFXR_PRESENT DSFXR_PRESENT No documentation. DSFXR_LOCHARDWARE DSFXR_LOCHARDWARE No documentation. DSFXR_LOCSOFTWARE DSFXR_LOCSOFTWARE No documentation. DSFXR_UNALLOCATED DSFXR_UNALLOCATED No documentation. DSFXR_FAILED DSFXR_FAILED No documentation. DSFXR_UNKNOWN DSFXR_UNKNOWN No documentation. DSFXR_SENDLOOP DSFXR_SENDLOOP No documentation. DSOUND_ENUM_2 DSOUND_ENUM_2 No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_DEFAULT DSFX_I3DL2_ENVIRONMENT_PRESET_DEFAULT No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_GENERIC DSFX_I3DL2_ENVIRONMENT_PRESET_GENERIC No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_PADDEDCELL DSFX_I3DL2_ENVIRONMENT_PRESET_PADDEDCELL No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_ROOM DSFX_I3DL2_ENVIRONMENT_PRESET_ROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_BATHROOM DSFX_I3DL2_ENVIRONMENT_PRESET_BATHROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_LIVINGROOM DSFX_I3DL2_ENVIRONMENT_PRESET_LIVINGROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_STONEROOM DSFX_I3DL2_ENVIRONMENT_PRESET_STONEROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_AUDITORIUM DSFX_I3DL2_ENVIRONMENT_PRESET_AUDITORIUM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_CONCERTHALL DSFX_I3DL2_ENVIRONMENT_PRESET_CONCERTHALL No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_CAVE DSFX_I3DL2_ENVIRONMENT_PRESET_CAVE No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_ARENA DSFX_I3DL2_ENVIRONMENT_PRESET_ARENA No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_HANGAR DSFX_I3DL2_ENVIRONMENT_PRESET_HANGAR No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_CARPETEDHALLWAY DSFX_I3DL2_ENVIRONMENT_PRESET_CARPETEDHALLWAY No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_HALLWAY DSFX_I3DL2_ENVIRONMENT_PRESET_HALLWAY No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_STONECORRIDOR DSFX_I3DL2_ENVIRONMENT_PRESET_STONECORRIDOR No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_ALLEY DSFX_I3DL2_ENVIRONMENT_PRESET_ALLEY No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_FOREST DSFX_I3DL2_ENVIRONMENT_PRESET_FOREST No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_CITY DSFX_I3DL2_ENVIRONMENT_PRESET_CITY No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_MOUNTAINS DSFX_I3DL2_ENVIRONMENT_PRESET_MOUNTAINS No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_QUARRY DSFX_I3DL2_ENVIRONMENT_PRESET_QUARRY No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_PLAIN DSFX_I3DL2_ENVIRONMENT_PRESET_PLAIN No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_PARKINGLOT DSFX_I3DL2_ENVIRONMENT_PRESET_PARKINGLOT No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_SEWERPIPE DSFX_I3DL2_ENVIRONMENT_PRESET_SEWERPIPE No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_UNDERWATER DSFX_I3DL2_ENVIRONMENT_PRESET_UNDERWATER No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_SMALLROOM DSFX_I3DL2_ENVIRONMENT_PRESET_SMALLROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMROOM DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEROOM DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEROOM No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMHALL DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMHALL No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEHALL DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEHALL No documentation. DSFX_I3DL2_ENVIRONMENT_PRESET_PLATE DSFX_I3DL2_ENVIRONMENT_PRESET_PLATE No documentation. DSBLOCK_ENUM DSBLOCK_ENUM No documentation. DSBLOCK_FROMWRITECURSOR DSBLOCK_FROMWRITECURSOR No documentation. DSBLOCK_ENTIREBUFFER DSBLOCK_ENTIREBUFFER None. None None The GetMode method retrieves the operation mode for 3D sound processing. microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmode DS3DMODE DS3DMODE
Address of a variable that receives the mode setting. This value will be one of those in the following table.
Value Description
Processing of 3D sound is disabled. The sound seems to originate from the center of the listener's head.
Sound parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener's parameters change, so that the relative parameters remain constant.
Normal processing. This is the default mode.
microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmode DS3DMODE_NORMAL DS3DMODE_NORMAL No documentation. microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmode DS3DMODE_HEADRELATIVE DS3DMODE_HEADRELATIVE No documentation. microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmode DS3DMODE_DISABLE DS3DMODE_DISABLE No documentation. DSBPLAY_FLAGS DSBPLAY_FLAGS No documentation. DSBPLAY_LOOPING DSBPLAY_LOOPING No documentation. DSBPLAY_LOCHARDWARE DSBPLAY_LOCHARDWARE No documentation. DSBPLAY_LOCSOFTWARE DSBPLAY_LOCSOFTWARE No documentation. DSBPLAY_TERMINATEBY_TIME DSBPLAY_TERMINATEBY_TIME No documentation. DSBPLAY_TERMINATEBY_DISTANCE DSBPLAY_TERMINATEBY_DISTANCE No documentation. DSBPLAY_TERMINATEBY_PRIORITY DSBPLAY_TERMINATEBY_PRIORITY None. None None No documentation. DSOUND_ENUM_0 DSOUND_ENUM_0 No documentation. DSFX_I3DL2_MATERIAL_PRESET_SINGLEWINDOW DSFX_I3DL2_MATERIAL_PRESET_SINGLEWINDOW No documentation. DSFX_I3DL2_MATERIAL_PRESET_DOUBLEWINDOW DSFX_I3DL2_MATERIAL_PRESET_DOUBLEWINDOW No documentation. DSFX_I3DL2_MATERIAL_PRESET_THINDOOR DSFX_I3DL2_MATERIAL_PRESET_THINDOOR No documentation. DSFX_I3DL2_MATERIAL_PRESET_THICKDOOR DSFX_I3DL2_MATERIAL_PRESET_THICKDOOR No documentation. DSFX_I3DL2_MATERIAL_PRESET_WOODWALL DSFX_I3DL2_MATERIAL_PRESET_WOODWALL No documentation. DSFX_I3DL2_MATERIAL_PRESET_BRICKWALL DSFX_I3DL2_MATERIAL_PRESET_BRICKWALL No documentation. DSFX_I3DL2_MATERIAL_PRESET_STONEWALL DSFX_I3DL2_MATERIAL_PRESET_STONEWALL No documentation. DSFX_I3DL2_MATERIAL_PRESET_CURTAIN DSFX_I3DL2_MATERIAL_PRESET_CURTAIN No documentation. DSSPEAKER_ENUM DSSPEAKER_ENUM No documentation. DSSPEAKER_DIRECTOUT DSSPEAKER_DIRECTOUT No documentation. DSSPEAKER_HEADPHONE DSSPEAKER_HEADPHONE No documentation. DSSPEAKER_MONO DSSPEAKER_MONO No documentation. DSSPEAKER_QUAD DSSPEAKER_QUAD No documentation. DSSPEAKER_STEREO DSSPEAKER_STEREO No documentation. DSSPEAKER_SURROUND DSSPEAKER_SURROUND No documentation. DSSPEAKER_5POINT1 DSSPEAKER_5POINT1 No documentation. DSSPEAKER_7POINT1 DSSPEAKER_7POINT1 No documentation. DSSPEAKER_7POINT1_SURROUND DSSPEAKER_7POINT1_SURROUND No documentation. DSSPEAKER_5POINT1_SURROUND DSSPEAKER_5POINT1_SURROUND No documentation. DSSPEAKER_7POINT1_WIDE DSSPEAKER_7POINT1_WIDE No documentation. DSSPEAKER_5POINT1_BACK DSSPEAKER_5POINT1_BACK No documentation. DSSPEAKER_GEOMETRY_ENUM DSSPEAKER_GEOMETRY_ENUM No documentation. DSSPEAKER_GEOMETRY_MIN DSSPEAKER_GEOMETRY_MIN No documentation. DSSPEAKER_GEOMETRY_NARROW DSSPEAKER_GEOMETRY_NARROW No documentation. DSSPEAKER_GEOMETRY_WIDE DSSPEAKER_GEOMETRY_WIDE No documentation. DSSPEAKER_GEOMETRY_MAX DSSPEAKER_GEOMETRY_MAX Functions Constant AcousticEchoCancellationCaptureEffect. GUID_DSCFX_CLASS_AEC Constant MicrosoftAcousticEchoCancellationCaptureEffect. GUID_DSCFX_MS_AEC Constant SystemAcousticEchoCancellationCaptureEffect. GUID_DSCFX_SYSTEM_AEC Constant NoiseSuppressionCaptureEffect. GUID_DSCFX_CLASS_NS Constant MicrosoftNoiseSuppressionCaptureEffect. GUID_DSCFX_MS_NS Constant SystemNoiseSuppressionCaptureEffect. GUID_DSCFX_SYSTEM_NS Functions Constant FullHrt3DAlgorithm. DS3DALG_HRTF_FULL Constant LightHrt3DAlgorithm. DS3DALG_HRTF_LIGHT Constant NoVirtualization3DAlgorithm. DS3DALG_NO_VIRTUALIZATION Functions Constant AllObjects. GUID_All_Objects The DirectSoundCaptureCreate8 function creates and initializes an object that supports the IDirectSoundCapture8 interface. Although the olderDirectSoundCaptureCreatefunction can also be used to obtain theIDirectSoundCapture8interface, the object created by that function cannot be used to create capture buffers that support theIDirectSoundCaptureBuffer8interface. No documentation. No documentation. No documentation.

If the function succeeds, it returns DS_OK. If it fails, the return value may be one of the following values.

Return Code
DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

On sound cards that do not support full duplex, this method will fail and return DSERR_ALLOCATED.

 microsoft.directx_sdk.reference.directsoundcapturecreate8 HRESULT DirectSoundCaptureCreate8([In, Optional] const GUID* pcGuidDevice,[Out, Fast] IDirectSoundCapture** ppDSC8,[In] IUnknown* pUnkOuter) DirectSoundCaptureCreate8 The DirectSoundEnumerate function enumerates the DirectSound drivers installed in the system.
Address of the DSEnumCallback function that will be called for each device installed in the system.
Address of the user-defined context passed to the enumeration callback function every time that function is called.

If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.reference.directsoundenumerate HRESULT DirectSoundEnumerateA([In] __function__stdcall* pDSEnumCallback,[In, Optional] void* pContext) DirectSoundEnumerateA The DirectSoundEnumerate function enumerates the DirectSound drivers installed in the system.
Address of the DSEnumCallback function that will be called for each device installed in the system.
Address of the user-defined context passed to the enumeration callback function every time that function is called.

If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.reference.directsoundenumerate HRESULT DirectSoundEnumerateW([In] __function__stdcall* pDSEnumCallback,[In, Optional] void* pContext) DirectSoundEnumerateW The DirectSoundCaptureCreate8 function creates and initializes an object that supports the IDirectSoundCapture8 interface. Although the olderDirectSoundCaptureCreatefunction can also be used to obtain theIDirectSoundCapture8interface, the object created by that function cannot be used to create capture buffers that support theIDirectSoundCaptureBuffer8interface. No documentation. No documentation. No documentation.

If the function succeeds, it returns DS_OK. If it fails, the return value may be one of the following values.

Return Code
DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

On sound cards that do not support full duplex, this method will fail and return DSERR_ALLOCATED.

 microsoft.directx_sdk.reference.directsoundcapturecreate8 HRESULT DirectSoundCaptureCreate([In, Optional] const GUID* pcGuidDevice,[Out] IDirectSoundCapture** ppDSC,[In] IUnknown* pUnkOuter) DirectSoundCaptureCreate

The DirectSoundFullDuplexCreate function is documented under a different name. For complete documentation of this function, see DirectSoundFullDuplexCreate8.

No documentation. No documentation. No documentation. No documentation. No documentation. No documentation. No documentation. No documentation. No documentation. No documentation.

If this function succeeds, it returns . Otherwise, it returns an error code.

 bb432248 HRESULT DirectSoundFullDuplexCreate([In, Optional] const GUID* pcGuidCaptureDevice,[In, Optional] const GUID* pcGuidRenderDevice,[In] const DSCBUFFERDESC* pcDSCBufferDesc,[In] const DSBUFFERDESC* pcDSBufferDesc,[In] HWND hWnd,[In] unsigned int dwLevel,[Out, Fast] IDirectSoundFullDuplex** ppDSFD,[Out] IDirectSoundCaptureBuffer8** ppDSCBuffer8,[Out] IDirectSoundBuffer8** ppDSBuffer8,[In] IUnknown* pUnkOuter) DirectSoundFullDuplexCreate No documentation. No documentation. No documentation. No documentation. No documentation. HRESULT DirectSoundCreate([In, Optional] const GUID* pcGuidDevice,[Out] IDirectSound** ppDS,[In] IUnknown* pUnkOuter) DirectSoundCreate The GetDeviceID function retrieves the unique device identifier of the default playback and capture devices selected by the user in Control Panel.
Address of a variable that specifies a valid device identifier, or the address of one of the following predefined variables.
ValueDescription
DSDEVID_DefaultPlaybackSystem-wide default audio playback device.
DSDEVID_DefaultCaptureSystem-wide default audio capture device.
DSDEVID_DefaultVoicePlaybackDefault voice playback device.
DSDEVID_DefaultVoiceCaptureDefault voice capture device.
Address of a variable that receives the unique identifier of the device.

If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.

If pGuidSrc points to a valid device identifier, the same value is returned in pGuidDest. If pGuidSrc is one of the listed constants, pGuidDest returns the address of the corresponding device .

 microsoft.directx_sdk.reference.getdeviceid HRESULT GetDeviceID([In, Optional] const GUID* pGuidSrc,[Out] GUID* pGuidDest) GetDeviceID The DirectSoundCaptureEnumerate function enumerates the DirectSoundCapture objects installed in the system.
Address of the DSEnumCallback function that will be called for each DirectSoundCapture object installed in the system.
Address of the user-defined context passed to the enumeration callback function every time that function is called.

If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.reference.directsoundcaptureenumerate HRESULT DirectSoundCaptureEnumerateA([In] __function__stdcall* pDSEnumCallback,[In, Optional] void* pContext) DirectSoundCaptureEnumerateA The DirectSoundCaptureEnumerate function enumerates the DirectSoundCapture objects installed in the system.
Address of the DSEnumCallback function that will be called for each DirectSoundCapture object installed in the system.
Address of the user-defined context passed to the enumeration callback function every time that function is called.

If the function succeeds, it returns DS_OK. If it fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.reference.directsoundcaptureenumerate HRESULT DirectSoundCaptureEnumerateW([In] __function__stdcall* pDSEnumCallback,[In, Optional] void* pContext) DirectSoundCaptureEnumerateW The DirectSoundCreate8 function creates and initializes an object that supports theIDirectSound8interface. No documentation. No documentation. No documentation.

If the function succeeds, it returns DS_OK. If it fails, the return value may be one of the following.

Return Code
DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY

The application must call the IDirectSound8::SetCooperativeLevel method immediately after creating a device object.

 microsoft.directx_sdk.reference.directsoundcreate8 HRESULT DirectSoundCreate8([In, Optional] const GUID* pcGuidDevice,[Out, Fast] IDirectSound8** ppDS8,[In] IUnknown* pUnkOuter) DirectSoundCreate8 Functions Constant StandardFlanger. GUID_DSFX_STANDARD_FLANGER Constant StandardChorus. GUID_DSFX_STANDARD_CHORUS Constant StandardCompressor. GUID_DSFX_STANDARD_COMPRESSOR Constant StandardI3DL2REVERB. GUID_DSFX_STANDARD_I3DL2REVERB Constant WavesReverb. GUID_DSFX_WAVES_REVERB Constant StandardGargle. GUID_DSFX_STANDARD_GARGLE Constant StandardEcho. GUID_DSFX_STANDARD_ECHO Constant StandardParameq. GUID_DSFX_STANDARD_PARAMEQ Constant StandardDistortion. GUID_DSFX_STANDARD_DISTORTION Functions Constant Minimum. DSBVOLUME_MIN Constant Maximum. DSBVOLUME_MAX

The IDirectSoundCaptureFXAec8 interface is used to set and retrieve parameters on a capture buffer that supports acoustic echo cancellation. This interface requires Microsoft Windows XP or later operating systems.

IDirectSoundCaptureFXAec8 is a define for . The interface names are interchangeable.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundCaptureFXAec8 interface exposes the following methods.

IDirectSoundCaptureFXAec8 Members
Method Description
IDirectSoundCaptureFXAec8::GetAllParameters The IDirectSoundCaptureFXAec8::GetAllParameters method retrieves the acoustic echo cancellation parameters of a buffer.
IDirectSoundCaptureFXAec8::GetStatus The IDirectSoundCaptureFXAec8::GetStatus method retrieves the status of the effect.
IDirectSoundCaptureFXAec8::Reset The IDirectSoundCaptureFXAec8::Reset method resets the effect to its initial state.
IDirectSoundCaptureFXAec8::SetAllParameters The IDirectSoundCaptureFXAec8::SetAllParameters method sets the acoustic echo cancellation parameters of a buffer.

The LPDIRECTSOUNDCAPTUREFXAEC8 type is defined as a reference to the IDirectSoundCaptureFXAec8 interface:

 typedef struct IDirectSoundCaptureFXAec8 *LPDIRECTSOUNDCAPTUREFXAEC8;
Info

Operating System: Requires Microsoft WindowsXP or later.

Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 ee418187 IDirectSoundCaptureFXAec IDirectSoundCaptureFXAec Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the acoustic echo cancellation parameters of a buffer.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.idirectsoundcapturefxaec8.idirectsoundcapturefxaec8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundCaptureFXAec::GetAllParameters([Out] DSCFXAec* pDscFxAec) The IDirectSoundCaptureFXAec8::GetStatus method retrieves the status of the effect.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

The three least significant bits in *pdwStatus describe the convergence history; that is, the success of the effect in canceling the echo. The convergence history can be used by the application to determine if the algorithm has converged and remained in the converged state since it started processing data.

Initially, the AEC algorithm sets the three lower bits to 0 for the uninitialized state (). When the AEC algorithm has converged, the convergence history is switched to the state. If the AEC algorithm ever loses convergence, the convergence history is then transitioned to the state. A transition from to is also possible. The convergence history remains in the state until the algorithm is reset or timely data is no longer arriving on the capture or render stream.

 microsoft.directx_sdk.idirectsoundcapturefxaec8.idirectsoundcapturefxaec8.getstatus GetStatus GetStatus HRESULT IDirectSoundCaptureFXAec::GetStatus([Out] DSCFX_AEC_STATUS* pdwStatus) The SetAllParameters method sets the acoustic echo cancellation parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values.

Return code
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.idirectsoundcapturefxaec8.idirectsoundcapturefxaec8.setallparameters HRESULT IDirectSoundCaptureFXAec::SetAllParameters([In] const DSCFXAec* pDscFxAec) IDirectSoundCaptureFXAec::SetAllParameters The GetAllParameters method retrieves the acoustic echo cancellation parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values.

Return code
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY

If the method fails, the return value may be DSERR_INVALIDPARAM.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.idirectsoundcapturefxaec8.idirectsoundcapturefxaec8.getallparameters HRESULT IDirectSoundCaptureFXAec::GetAllParameters([Out] DSCFXAec* pDscFxAec) IDirectSoundCaptureFXAec::GetAllParameters The IDirectSoundCaptureFXAec8::GetStatus method retrieves the status of the effect.
Address of a DWORD variable to receive the status. The following flags are defined. See Remarks.
ConstantValue
0x0
0x1
0x2
0x8

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values.

Return code
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

The three least significant bits in *pdwStatus describe the convergence history; that is, the success of the effect in canceling the echo. The convergence history can be used by the application to determine if the algorithm has converged and remained in the converged state since it started processing data.

Initially, the AEC algorithm sets the three lower bits to 0 for the uninitialized state (). When the AEC algorithm has converged, the convergence history is switched to the state. If the AEC algorithm ever loses convergence, the convergence history is then transitioned to the state. A transition from to is also possible. The convergence history remains in the state until the algorithm is reset or timely data is no longer arriving on the capture or render stream.

 microsoft.directx_sdk.idirectsoundcapturefxaec8.idirectsoundcapturefxaec8.getstatus HRESULT IDirectSoundCaptureFXAec::GetStatus([Out] DSCFX_AEC_STATUS* pdwStatus) IDirectSoundCaptureFXAec::GetStatus The IDirectSoundCaptureFXAec8::Reset method resets the effect to its initial state.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_OUTOFMEMORY.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

Applications should not reset an effect except when necessary because it has entered an incorrect state. This might be done in response to user input. An effect must not be reset arbitrarily at startup, because another application might be using the same effect.

 microsoft.directx_sdk.idirectsoundcapturefxaec8.idirectsoundcapturefxaec8.reset HRESULT IDirectSoundCaptureFXAec::Reset() IDirectSoundCaptureFXAec::Reset

The interface is used to create buffer objects, manage devices, and set up the environment. This interface supersedes and adds new methods.

Obtain this interface by using the DirectSoundCreate8 or DirectSoundFullDuplexCreate8 function, or by using CoCreateInstance or CoCreateInstanceEx to create an object of class CLSID_DirectSound8.

In addition to the methods inherited from , the interface exposes the following methods.

IDirectSound8 Members
Method Description
IDirectSound8::Compact The Compact method has no effect.
IDirectSound8::CreateSoundBuffer The CreateSoundBuffer method creates a sound buffer object to manage audio samples.
IDirectSound8::DuplicateSoundBuffer The DuplicateSoundBuffer method creates a new secondary buffer that shares the original buffer's memory.
IDirectSound8::GetCaps The GetCaps method retrieves the capabilities of the hardware device that is represented by the device object.
IDirectSound8::GetSpeakerConfig The GetSpeakerConfig method retrieves the speaker configuration.
IDirectSound8::Initialize The Initialize method initializes a device object that was created by using the CoCreateInstance function.
IDirectSound8::SetCooperativeLevel The SetCooperativeLevel method sets the cooperative level of the application for this sound device.
IDirectSound8::SetSpeakerConfig The SetSpeakerConfig method specifies the speaker configuration of the device.
The VerifyCertification method ascertains whether the device driver is certified for DirectX.

The LPDIRECTSOUND8 type is defined as a reference to the interface:

 typedef struct   *LPDIRECTSOUND8;

Only objects of class CLSID_DirectSound8 support this interface. All device objects created by DirectSoundCreate8 and DirectSoundFullDuplexCreate8 fall into this category. Objects of class CLSID_DirectSound, which include all those created by using the earlier DirectSoundCreate function, support only the earlier interface.

The behavior of CLSID_DirectSound8 objects is somewhat different from that of CLSID_DirectSound objects. These differences are found in the interface as well as the interface. Specific differences in the behavior of the newer object include the following:

  • In calls to and CreateSoundBuffer, cannot be set on a buffer with a non-mono format, and cannot be combined with .

  • New buffer creation flags are supported.

  • Buffers are not filled with silence on creation.

  • The interface returned by CreateSoundBuffer can be queried for the interface.

  • WAV formats in the structure that have the format tag are checked more strictly for validity.

 ee418035 IDirectSound IDirectSound Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetCaps method retrieves the capabilities of the hardware device that is represented by the device object.

Information retrieved in the structure describes the maximum capabilities of the sound device and those currently available, such as the number of hardware mixing channels and the amount of on-board sound memory. You can use this information to fine-tune performance and optimize resource allocation.

Because of resource-sharing requirements, the maximum capabilities in one area might be available only at the cost of another area.

 microsoft.directx_sdk.idirectsound8.idirectsound8.getcaps GetCaps GetCaps HRESULT IDirectSound::GetCaps([Out] DSCAPS* pDSCaps) The CreateSoundBuffer method creates a sound buffer object to manage audio samples.
Address of a structure that describes the sound buffer to create.
Address of a variable that receives the interface of the new buffer object. Use QueryInterface to obtain . is not available for the primary buffer.
Address of the controlling object's interface for COM aggregation. Must be null.

If the method succeeds, the return value is DS_OK, or DS_NO_VIRTUALIZATION if a requested 3D algorithm was not available and stereo panning was substituted. See the description of the guid3DAlgorithm member of . If the method fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_BUFFERTOOSMALL
DSERR_CONTROLUNAVAIL
DSERR_DS8_REQUIRED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

DirectSound does not initialize the contents of the buffer, and the application cannot assume that it contains silence.

If an attempt is made to create a buffer with the flag on a system where hardware acceleration is not available, the method fails with either DSERR_CONTROLUNAVAIL or DSERR_INVALIDCALL, depending on the operating system.

 microsoft.directx_sdk.idirectsound8.idirectsound8.createsoundbuffer HRESULT IDirectSound::CreateSoundBuffer([In] const DSBUFFERDESC* pcDSBufferDesc,[Out] void** ppDSBuffer,[In] IUnknown* pUnkOuter) IDirectSound::CreateSoundBuffer The GetCaps method retrieves the capabilities of the hardware device that is represented by the device object.
Address of a structure that receives the capabilities of this sound device.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

Information retrieved in the structure describes the maximum capabilities of the sound device and those currently available, such as the number of hardware mixing channels and the amount of on-board sound memory. You can use this information to fine-tune performance and optimize resource allocation.

Because of resource-sharing requirements, the maximum capabilities in one area might be available only at the cost of another area.

 microsoft.directx_sdk.idirectsound8.idirectsound8.getcaps HRESULT IDirectSound::GetCaps([Out] DSCAPS* pDSCaps) IDirectSound::GetCaps The DuplicateSoundBuffer method creates a new secondary buffer that shares the original buffer's memory.
Address of the or interface of the buffer to duplicate.
Address of a variable that receives the interface reference for the new buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

This method is not valid for buffers created with the flag.

Initially, the duplicate buffer will have the same parameters as the original buffer. However, the application can change the parameters of each buffer independently, and each can be played or stopped without affecting the other.

The buffer memory is released when the last object referencing it is released.

There is a known issue with volume levels of duplicated buffers. The duplicated buffer will play at full volume unless you change the volume to a different value than the original buffer's volume setting. If the volume stays the same (even if you explicitly set the same volume in the duplicated buffer with a IDirectSoundBuffer8::SetVolume call), the buffer will play at full volume regardless. To work around this problem, immediately set the volume of the duplicated buffer to something slightly different than what it was, even if you change it one millibel. The volume may then be immediately set back again to the original desired value.

 microsoft.directx_sdk.idirectsound8.idirectsound8.duplicatesoundbuffer HRESULT IDirectSound::DuplicateSoundBuffer([In] IDirectSoundBuffer* pDSBufferOriginal,[Out] void** ppDSBufferDuplicate) IDirectSound::DuplicateSoundBuffer The SetCooperativeLevel method sets the cooperative level of the application for this sound device.
Handle to the application window.
Requested level. Specify one of the values shown in the following table.
ValueDescription
For DirectX 8.0 and later, has the same effect as . For previous versions, sets the application to the exclusive level. This means that when it has the input focus, the application will be the only one audible; sounds from applications with the flag set will be muted. With this level, it also has all the privileges of the level. DirectSound will restore the hardware format, as specified by the most recent call to the SetFormat method, after the application gains the input focus.
Sets the normal level. This level has the smoothest multitasking and resource-sharing behavior, but because it does not allow the primary buffer format to change, output is restricted to the default 8-bit format.
Sets the priority level. Applications with this cooperative level can call the SetFormat and Compact methods.
Sets the write-primary level. The application has write access to the primary buffer. No secondary buffers can be played. This level cannot be set if the DirectSound driver is being emulated for the device; that is, if the GetCaps method returns the flag in the structure.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

The application must set the cooperative level by calling this method before its buffers can be played. The recommended cooperative level is .

Do not call this method if any buffers are locked.

 microsoft.directx_sdk.idirectsound8.idirectsound8.setcooperativelevel HRESULT IDirectSound::SetCooperativeLevel([In] HWND hwnd,[In] DSSCL_ENUM dwLevel) IDirectSound::SetCooperativeLevel The Compact method has no effect.

The return value is DS_OK.

This method was formerly used for compacting the on-board memory of ISA sound cards.

 microsoft.directx_sdk.idirectsound8.idirectsound8.compact HRESULT IDirectSound::Compact() IDirectSound::Compact The GetSpeakerConfig method retrieves the speaker configuration.
Address of the speaker configuration (see remarks in IDirectSound8::SetSpeakerConfig).

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

The value returned at pdwSpeakerConfig can be a packed DWORD containing both configuration and geometry information. Use the DSSPEAKER_CONFIG and DSSPEAKER_GEOMETRY macros to unpack the DWORD, as in the following example:

 if (DSSPEAKER_CONFIG(dwSpeakerConfig) == ) { if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) == ) { // Configuration is wide stereo. ...} }

To use #defines implemented in Windows Vista, set the DIRECTSOUND_VERSION to 0x1000 before including dsound.h.

 microsoft.directx_sdk.idirectsound8.idirectsound8.getspeakerconfig HRESULT IDirectSound::GetSpeakerConfig([Out] unsigned int* pdwSpeakerConfig) IDirectSound::GetSpeakerConfig TheSetSpeakerConfigmethod specifies the speaker configuration of the device.
The speaker configuration. See the following remarks.
No documentation. microsoft.directx_sdk.idirectsound8.idirectsound8.setspeakerconfig HRESULT IDirectSound::SetSpeakerConfig([In] unsigned int dwSpeakerConfig) IDirectSound::SetSpeakerConfig No documentation. bb280379 IDirectSoundFXI3DL2Reverb IDirectSoundFXI3DL2Reverb Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. No documentation. GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXI3DL2Reverb::GetAllParameters([Out] DSFXI3DL2Reverb* pDsFxI3DL2Reverb) No documentation. GetPreset / SetPreset GetPreset HRESULT IDirectSoundFXI3DL2Reverb::GetPreset([Out] unsigned int* pdwPreset) No documentation. GetQuality / SetQuality GetQuality HRESULT IDirectSoundFXI3DL2Reverb::GetQuality([Out] int* plQuality) No documentation. No documentation. No documentation. HRESULT IDirectSoundFXI3DL2Reverb::SetAllParameters([In] const DSFXI3DL2Reverb* pcDsFxI3DL2Reverb) IDirectSoundFXI3DL2Reverb::SetAllParameters No documentation. No documentation. No documentation. HRESULT IDirectSoundFXI3DL2Reverb::GetAllParameters([Out] DSFXI3DL2Reverb* pDsFxI3DL2Reverb) IDirectSoundFXI3DL2Reverb::GetAllParameters No documentation. No documentation. No documentation. HRESULT IDirectSoundFXI3DL2Reverb::SetPreset([In] unsigned int dwPreset) IDirectSoundFXI3DL2Reverb::SetPreset No documentation. No documentation. No documentation. HRESULT IDirectSoundFXI3DL2Reverb::GetPreset([Out] unsigned int* pdwPreset) IDirectSoundFXI3DL2Reverb::GetPreset No documentation. No documentation. No documentation. HRESULT IDirectSoundFXI3DL2Reverb::SetQuality([In] int lQuality) IDirectSoundFXI3DL2Reverb::SetQuality No documentation. No documentation. No documentation. HRESULT IDirectSoundFXI3DL2Reverb::GetQuality([Out] int* plQuality) IDirectSoundFXI3DL2Reverb::GetQuality Default ratio of the decay time at high frequencies to the decay time at low frequencies. Maximum ratio of the decay time at high frequencies to the decay time at low frequencies. Minimum ratio of the decay time at high frequencies to the decay time at low frequencies. Default decay time, in seconds. Maximum decay time, in seconds. Minimum decay time, in seconds. Default modal density in the late reverberation decay, in percent. Maximum modal density in the late reverberation decay, in percent. Minimum modal density in the late reverberation decay, in percent. Default echo density in the late reverberation decay, in percent. Maximum echo density in the late reverberation decay, in percent. Minimum echo density in the late reverberation decay, in percent. Default reference high frequency, in hertz. Maximum reference high frequency, in hertz. Minimum reference high frequency, in hertz. Default attenuation of early reflections relative to Room, in mB. Default delay time of the first reflection relative to the direct path, in seconds. Maximum delay time of the first reflection relative to the direct path, in seconds. Minimum delay time of the first reflection relative to the direct path, in seconds. Maximum attenuation of early reflections relative to Room, in mB. Minimum attenuation of early reflections relative to Room, in mB. Default attenuation of late reverberation relative to Room, in mB. Default time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds. Maximum time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds. Minimum time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds. Maximum attenuation of late reverberation relative to Room, in mB. Minimum attenuation of late reverberation relative to Room, in mB. Default attenuation of the room effect, in millibels (mB). Default attenuation of the room high-frequency effect, in mB. Maximum attenuation of the room high-frequency effect, in mB. Minimum attenuation of the room high-frequency effect, in mB. Maximum attenuation of the room effect, in millibels (mB). Minimum attenuation of the room effect, in millibels (mB). Default rolloff factor for the reflected signals. The rolloff factor for the direct path is controlled by the DirectSound listener. Maximum rolloff factor for the reflected signals. The rolloff factor for the direct path is controlled by the DirectSound listener. Minimum rolloff factor for the reflected signals. The rolloff factor for the direct path is controlled by the DirectSound listener.

The IDirectSoundCaptureFXNoiseSuppress8 interface is used to set and retrieve parameters on a capture buffer that supports noise suppression. This interface requires Microsoft WindowsXP or later.

IDirectSoundCaptureFXNoiseSuppress8 is a define for . The interface names are interchangeable.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundCaptureFXNoiseSuppress8 interface exposes the following methods.

IDirectSoundCaptureFXNoiseSuppress8 Members
Method Description
IDirectSoundCaptureFXNoiseSuppress8::GetAllParameters The IDirectSoundCaptureFXNoiseSuppress8::GetAllParameters method retrieves the noise suppression parameters of a buffer.
IDirectSoundCaptureFXNoiseSuppress8::Reset The IDirectSoundCaptureFXNoiseSuppress8::Reset method resets the effect to its initial state.
IDirectSoundCaptureFXNoiseSuppress8::SetAllParameters The IDirectSoundCaptureFXNoiseSuppress8::SetAllParameters method sets the noise suppression parameters of a buffer.

The LPDIRECTSOUNDNOISESUPPRESS8 type is defined as a reference to the IDirectSoundNoiseSuppress8 interface:

 typedef struct IDirectSoundCaptureFXNoiseSuppress8  *LPDIRECTSOUNDCAPTUREFXNOISESUPPRESS8;
Info

Operating System: Requires Microsoft WindowsXP or later.

Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 ee418197 IDirectSoundCaptureFXNoiseSuppress IDirectSoundCaptureFXNoiseSuppress Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the noise suppression parameters of a buffer.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.idirectsoundcapturefxnoisesuppress8.idirectsoundcapturefxnoisesuppress8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundCaptureFXNoiseSuppress::GetAllParameters([Out] DSCFXNoiseSuppress* pDscFxNoiseSuppress) The SetAllParameters method sets the noise suppression parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values:

Return code
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.idirectsoundcapturefxnoisesuppress8.idirectsoundcapturefxnoisesuppress8.setallparameters HRESULT IDirectSoundCaptureFXNoiseSuppress::SetAllParameters([In] const DSCFXNoiseSuppress* pcDscFxNoiseSuppress) IDirectSoundCaptureFXNoiseSuppress::SetAllParameters The GetAllParameters method retrieves the noise suppression parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following values:

Return code
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.idirectsoundcapturefxnoisesuppress8.idirectsoundcapturefxnoisesuppress8.getallparameters HRESULT IDirectSoundCaptureFXNoiseSuppress::GetAllParameters([Out] DSCFXNoiseSuppress* pDscFxNoiseSuppress) IDirectSoundCaptureFXNoiseSuppress::GetAllParameters The IDirectSoundCaptureFXNoiseSuppress8::Reset method resets the effect to its initial state.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_OUTOFMEMORY.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

Applications should not reset an effect except when necessary because it has entered an incorrect state. This might be done in response to user input. An effect must not be reset arbitrarily at startup, because another application might be using the same effect.

 microsoft.directx_sdk.idirectsoundcapturefxnoisesuppress8.idirectsoundcapturefxnoisesuppress8.reset HRESULT IDirectSoundCaptureFXNoiseSuppress::Reset() IDirectSoundCaptureFXNoiseSuppress::Reset Gets or sets he noise suppression parameters of a buffer.

The IDirectSoundFXParamEq8 interface is used to set and retrieve effect parameters on a buffer that supports parametric equalizer effects.

In addition to the methods inherited from , the IDirectSoundFXParamEq8 interface exposes the following methods.

IDirectSoundFXParamEq8 Members
Method Description
IDirectSoundFXParamEq8::GetAllParameters The GetAllParameters method retrieves the parametric equalizer parameters of a buffer.
IDirectSoundFXParamEq8::SetAllParameters The SetAllParameters method sets the parametric equalizer parameters of a buffer.
ee418238 IDirectSoundFXParamEq IDirectSoundFXParamEq Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the parametric equalizer parameters of a buffer. microsoft.directx_sdk.idirectsoundfxparameq8.idirectsoundfxparameq8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXParamEq::GetAllParameters([Out] DSFXParamEq* pDsFxParamEq) The SetAllParameters method sets the parametric equalizer parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK or S_FALSE. See the Remarks for . If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxparameq8.idirectsoundfxparameq8.setallparameters HRESULT IDirectSoundFXParamEq::SetAllParameters([In] const DSFXParamEq* pcDsFxParamEq) IDirectSoundFXParamEq::SetAllParameters The GetAllParameters method retrieves the parametric equalizer parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxparameq8.idirectsoundfxparameq8.getallparameters HRESULT IDirectSoundFXParamEq::GetAllParameters([Out] DSFXParamEq* pDsFxParamEq) IDirectSoundFXParamEq::GetAllParameters Default bandwidth, in semitones. Maximum bandwidth, in semitones. Minimum bandwidth, in semitones. Default center frequency, in hertz. Maximum center frequency, in hertz. Minimum center frequency, in hertz. Default gain. Maximum gain. Minimum gain.

The interface is used to manage sound buffers.

The interface supersedes and adds new methods.

To obtain the interface, use the CreateSoundBuffer method to retrieve , and then pass IID_IDirectSoundBuffer8 to IDirectSoundBuffer::QueryInterface.

For the primary buffer, you must use the interface; is not available. is not documented separately. For documentation, see the corresponding methods.

Not all methods of are valid for primary buffers. For example, SetCurrentPosition will fail. See the reference topics for individual methods.

In addition to the methods inherited from , the interface exposes the following methods, arranged by category.

Effects
Method Description
The GetObjectInPath method retrieves an interface for an effect object associated with the buffer.
Number of elements in the pDSFXDesc and pdwResultCodes arrays. If this value is 0, pDSFXDesc and pdwResultCodes must both be null. Set to 0 to remove all effects from the buffer.
Resource Management
Method Description
The AcquireResources method allocates resources for a buffer that was created with the flag in the DSBUFFERDESCDSBUFFERDESC
IDirectSoundBuffer8::Restore The Restore method restores the memory allocation for a lost sound buffer.
Play Management
Method Description
IDirectSoundBuffer8::GetCurrentPosition The GetCurrentPosition method retrieves the position of the play and write cursors in the sound buffer.
IDirectSoundBuffer8::Lock The Lock method readies all or part of the buffer for a data write and returns references to which data can be written.
IDirectSoundBuffer8::Play The Play method causes the sound buffer to play, starting at the play cursor.
IDirectSoundBuffer8::SetCurrentPosition The SetCurrentPosition method sets the position of the play cursor, which is the point at which the next byte of data is read from the buffer.
IDirectSoundBuffer8::Stop The Stop method causes the sound buffer to stop playing.
IDirectSoundBuffer8::Unlock The Unlock method releases a locked sound buffer.
Sound Parameters
Method Description
IDirectSoundBuffer8::GetFrequency The GetFrequency method retrieves the frequency, in samples per second, at which the buffer is playing.
IDirectSoundBuffer8::GetPan The GetPan method retrieves the relative volume of the left and right audio channels.
IDirectSoundBuffer8::GetVolume The GetVolume method retrieves the attenuation of the sound.
IDirectSoundBuffer8::SetFrequency The SetFrequency method sets the frequency at which the audio samples are played.
IDirectSoundBuffer8::SetPan The SetPan method sets the relative volume of the left and right channels.
IDirectSoundBuffer8::SetVolume The SetVolume method sets the attenuation of the sound.
Miscellaneous
Method Description
IDirectSoundBuffer8::GetCaps The GetCaps method retrieves the capabilities of the buffer object.
IDirectSoundBuffer8::GetFormat The GetFormat method retrieves a description of the format of the sound data in the buffer, or the buffer size needed to retrieve the format description.
IDirectSoundBuffer8::GetStatus The GetStatus method retrieves the status of the sound buffer.
IDirectSoundBuffer8::Initialize The Initialize method initializes a sound buffer object if it has not yet been initialized.
IDirectSoundBuffer8::SetFormat The SetFormat method sets the format of the primary buffer. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

The LPDIRECTSOUNDBUFFER8 type is defined as a reference to the interface:

 typedef struct   *LPDIRECTSOUNDBUFFER8;
ee418055 IDirectSoundBuffer8 IDirectSoundBuffer8 Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The SetFX method enables effects on a buffer.

For this method to succeed, CoInitialize must have been called. Additionally, the buffer must not be playing or locked.
Number of elements in the pDSFXDesc and pdwResultCodes arrays. If this value is 0, pDSFXDesc and pdwResultCodes must both be null. Set to 0 to remove all effects from the buffer.
Address of an array of structures, of size dwEffectsCount, that specifies the effects wanted on the buffer. Must be null if dwEffectsCount is 0.
Address of an array of DWORD elements, of size dwEffectsCount. Each element receives one of the values shown in the following table, indicating the result of the attempt to create the corresponding effect in the pDSFXDesc array.
Note
This parameter must be null if dwEffectsCount is 0, or can be null if results are not wanted.
ValueDescription
Effect is instantiated in hardware.
Effect is instantiated in software.
Effect has not yet been assigned to hardware or software. This value is returned if the buffer was created with the flag in .
No effect was created because resources weren't available.
Effect is available but was not created because one of the other effects requested could not be created. If any of the effects requested cannot be created, none of them are, and the call fails.
Effect is not registered on the system, and the method failed as a result.

If the method succeeds, the return value is DS_OK or DS_INCOMPLETE. If the method fails, the return value may be one of the error values shown in the following table.

Return code
CO_E_NOTINITIALIZED
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_INVALIDCALL
DSERR_NOINTERFACE
DSERR_PRIOLEVELNEEDED

In addition, the method can return an error value from DMO methods, including and . See the DirectShow documentation for possible error values.

If the method fails, the value for each effect in pdwResultCodes is either DSFXF_PRESENT or . Check these values to determine which effects caused the failure.

For the method to succeed, the buffer must have been created with the flag and must not be playing or locked.

If the method returns DSERR_NOINTERFACE or another COM error, check the result code array for or to ascertain which effect caused the error. If the method returns DSERR_INVALIDPARAM, check the result codes for to see which effects failed to acquire resources.

An effect must be set on a buffer before the effect interface can be obtained. To obtain the effect interface, use GetObjectInPath.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setfx HRESULT IDirectSoundBuffer8::SetFX([In] unsigned int dwEffectsCount,[In, Buffer, Optional] DSEFFECTDESC* pDSFXDesc,[InOut, Buffer] DSOUND_ENUM_0* pdwResultCodes) IDirectSoundBuffer8::SetFX The AcquireResources method allocates resources for a buffer that was created with the flag in theDSBUFFERDESCstructure. No documentation. No documentation. No documentation.

If the method succeeds, the return value is DS_OK or DS_INCOMPLETE. If the method fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM

Normally, buffers created with are not allocated resources until Play is called. can be used to allocate resources for a deferred buffer before it is played. By doing so, the application can retrieve information about effects processing and set effect parameters. If the method fails, check the values in pdwResultCodes to determine which effects caused the failure.

A buffer with acquired resources that is not yet playing is not a candidate for premature termination by the voice management flags passed to the Play method.

Resources that have been acquired by AcquireResources are released when playback is stopped.

If the method is called on a buffer on which it has already been called, the status of the effects is returned but no additional resources are allocated.

The dwEffectsCount parameter to this function must be the same as the one passed in the call to SetFX.

If an attempt is made to acquire resources for a buffer with the flag on a system where hardware acceleration is not available, the method fails with either DSERR_CONTROLUNAVAIL or DSERR_INVALIDCALL, depending on the operating system.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.acquireresources HRESULT IDirectSoundBuffer8::AcquireResources([In] unsigned int dwFlags,[In] unsigned int dwEffectsCount,[Out, Buffer] unsigned int* pdwResultCodes) IDirectSoundBuffer8::AcquireResources The GetObjectInPath method retrieves an interface for an effect object associated with the buffer.
Unique class identifier of the object being searched for, such as . Set this parameter to to search for objects of any class.
Index of the object within objects of that class in the path. See Remarks.
Unique identifier of the desired interface. See Remarks.
Address of a variable that receives the desired interface reference.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_OBJECTNOTFOUND

Any DMO that has been set on a buffer by using SetFX can be retrieved, even it has not been allocated resources.

The following interfaces can be retrieved for the various DMOs supplied with DirectX.

rguidInterface *ppObject
IID_IDirectSoundFXGargle8 IDirectSoundFXGargle8
IID_IDirectSoundFXChorus8 IDirectSoundFXChorus8
IID_IDirectSoundFXFlanger8 IDirectSoundFXFlanger8
IID_IDirectSoundFXEcho8 IDirectSoundFXEcho8
IID_IDirectSoundFXDistortion8 IDirectSoundFXDistortion8
IID_IDirectSoundFXCompressor8 IDirectSoundFXCompressor8
IID_IDirectSoundFXParamEq8 IDirectSoundFXParamEq8
IID_IDirectSoundFXWavesReverb8 IDirectSoundFXWavesReverb8
IID_IDirectSoundFXI3DL2Reverb8 IDirectSoundFXI3DL2Reverb8

In addition, the following interfaces are available for any of the standard DMOs. For information on these interfaces, see the Help for DirectX Media Objects.

rguidInterface *ppObject
IID_IMediaObject
IID_IMediaObjectInPlace
IID_IMediaParams IMediaParams

NoteWhen the DirectSound API is used to play buffers, parameter curves (envelopes) set by using the IMediaParams interface do not work, because DirectSound does not timestamp the DMO buffers.

The value in dwIndex is the index of the object within the array of effects passed to SetFX. This is not necessarily the actual position of the object in the effects chain, because some effects might not have been created.

An object is returned solely on the basis of whether it matches rguidObject and dwIndex. It is up to the application to ensure that rguidInterface specifies an interface that can be expected to be found on the object.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getobjectinpath HRESULT IDirectSoundBuffer8::GetObjectInPath([In] const GUID& rguidObject,[In] unsigned int dwIndex,[In] const GUID& rguidInterface,[Out] void** ppObject) IDirectSoundBuffer8::GetObjectInPath Initializes a new instance of the class. an instance of the The buffer description. Retrieves an interface to an effect object associated with the buffer. Index of the object within objects of that class in the path. See Remarks. an effect object associated with the buffer HRESULT IDirectSoundCaptureBuffer8::GetObjectInPath([In] GUID* rguidObject,[None] int dwIndex,[In] GUID* rguidInterface,[Out] void** ppObject) Enables effects on a buffer. Effects guids No documentation. HRESULT IDirectSoundBuffer8::SetFX([None] int dwEffectsCount,[In, Buffer, Optional] LPDSEFFECTDESC pDSFXDesc,[Out, Buffer, Optional] int* pdwResultCodes)

The interface is used to manage sound buffers.

The interface supersedes and adds new methods.

To obtain the interface, use the CreateSoundBuffer method to retrieve , and then pass IID_IDirectSoundBuffer8 to IDirectSoundBuffer::QueryInterface.

For the primary buffer, you must use the interface; is not available. is not documented separately. For documentation, see the corresponding methods.

Not all methods of are valid for primary buffers. For example, SetCurrentPosition will fail. See the reference topics for individual methods.

In addition to the methods inherited from , the interface exposes the following methods, arranged by category.

Effects
Method Description
The GetObjectInPath method retrieves an interface for an effect object associated with the buffer.
Number of elements in the pDSFXDesc and pdwResultCodes arrays. If this value is 0, pDSFXDesc and pdwResultCodes must both be null. Set to 0 to remove all effects from the buffer.
Resource Management
Method Description
The AcquireResources method allocates resources for a buffer that was created with the flag in the DSBUFFERDESCDSBUFFERDESC
IDirectSoundBuffer8::Restore The Restore method restores the memory allocation for a lost sound buffer.
Play Management
Method Description
IDirectSoundBuffer8::GetCurrentPosition The GetCurrentPosition method retrieves the position of the play and write cursors in the sound buffer.
IDirectSoundBuffer8::Lock The Lock method readies all or part of the buffer for a data write and returns references to which data can be written.
IDirectSoundBuffer8::Play The Play method causes the sound buffer to play, starting at the play cursor.
IDirectSoundBuffer8::SetCurrentPosition The SetCurrentPosition method sets the position of the play cursor, which is the point at which the next byte of data is read from the buffer.
IDirectSoundBuffer8::Stop The Stop method causes the sound buffer to stop playing.
IDirectSoundBuffer8::Unlock The Unlock method releases a locked sound buffer.
Sound Parameters
Method Description
IDirectSoundBuffer8::GetFrequency The GetFrequency method retrieves the frequency, in samples per second, at which the buffer is playing.
IDirectSoundBuffer8::GetPan The GetPan method retrieves the relative volume of the left and right audio channels.
IDirectSoundBuffer8::GetVolume The GetVolume method retrieves the attenuation of the sound.
IDirectSoundBuffer8::SetFrequency The SetFrequency method sets the frequency at which the audio samples are played.
IDirectSoundBuffer8::SetPan The SetPan method sets the relative volume of the left and right channels.
IDirectSoundBuffer8::SetVolume The SetVolume method sets the attenuation of the sound.
Miscellaneous
Method Description
IDirectSoundBuffer8::GetCaps The GetCaps method retrieves the capabilities of the buffer object.
IDirectSoundBuffer8::GetFormat The GetFormat method retrieves a description of the format of the sound data in the buffer, or the buffer size needed to retrieve the format description.
IDirectSoundBuffer8::GetStatus The GetStatus method retrieves the status of the sound buffer.
IDirectSoundBuffer8::Initialize The Initialize method initializes a sound buffer object if it has not yet been initialized.
IDirectSoundBuffer8::SetFormat The SetFormat method sets the format of the primary buffer. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

The LPDIRECTSOUNDBUFFER8 type is defined as a reference to the interface:

 typedef struct   *LPDIRECTSOUNDBUFFER8;
ee418055 IDirectSoundBuffer IDirectSoundBuffer Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetCaps method retrieves the capabilities of the buffer object.

The structure contains similar information to the structure passed to the CreateSoundBuffer method, with some additional information. This additional information can include the buffer's location, either in hardware or software, and performance measures.

The flags specified in the dwFlags member of the structure are the same flags used by the structure. The only difference is that in the structure, either or will be specified according to the location of the buffer memory. In the structure, these flags are optional and, depending on which flag is specified, force the buffer to be located in either hardware or software.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getcaps GetCaps GetCaps HRESULT IDirectSoundBuffer::GetCaps([Out] DSBCAPS* pDSBufferCaps) The GetVolume method retrieves the attenuation of the sound.

The return value is between and . These values are defined as 0 and ?10,000, respectively. The value represents the original, unadjusted volume of the sound. The value indicates an audio volume attenuated by 100 dB, which, for practical purposes, is silence.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getvolume GetVolume / SetVolume GetVolume HRESULT IDirectSoundBuffer::GetVolume([Out] int* plVolume) The GetPan method retrieves the relative volume of the left and right audio channels.

The returned value is measured in hundredths of a decibel (dB), in the range of DSBPAN_LEFT to DSBPAN_RIGHT. These values are defined in Dsound.h as -10,000 and 10,000 respectively. The value DSBPAN_LEFT means the right channel is effectively silent. The value DSBPAN_RIGHT means the left channel is effectively silent. The neutral value is DSBPAN_CENTER, defined as 0, which means that both channels are at full volume. When one channel is attenuated, the other remains at full volume.

The pan control acts cumulatively with the volume control.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getpan GetPan / SetPan GetPan HRESULT IDirectSoundBuffer::GetPan([Out] int* plPan) The GetFrequency method retrieves the frequency, in samples per second, at which the buffer is playing.

The frequency value for software buffers is in the range of DSBFREQUENCY_MIN to DSBFREQUENCY_MAX, defined in Dsound.h. Hardware buffers can return other values.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getfrequency GetFrequency / SetFrequency GetFrequency HRESULT IDirectSoundBuffer::GetFrequency([Out] unsigned int* pdwFrequency) The GetStatus method retrieves the status of the sound buffer.

is set if the buffer is being heard. Because of latency, a call to Play or Stop might not immediately change the status.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getstatus GetStatus GetStatus HRESULT IDirectSoundBuffer::GetStatus([Out] unsigned int* pdwStatus) The SetCurrentPosition method sets the position of the play cursor, which is the point at which the next byte of data is read from the buffer.

This method cannot be called on the primary buffer.

If the buffer is playing, the cursor immediately moves to the new position and play continues from that point. If it is not playing, playback will begin from the new position the next time the Play method is called.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setcurrentposition SetCurrentPosition SetCurrentPosition HRESULT IDirectSoundBuffer::SetCurrentPosition([In] unsigned int dwNewPosition) The GetCaps method retrieves the capabilities of the buffer object.
Address of a structure to contain the capabilities of this sound buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The structure contains similar information to the structure passed to the CreateSoundBuffer method, with some additional information. This additional information can include the buffer's location, either in hardware or software, and performance measures.

The flags specified in the dwFlags member of the structure are the same flags used by the structure. The only difference is that in the structure, either or will be specified according to the location of the buffer memory. In the structure, these flags are optional and, depending on which flag is specified, force the buffer to be located in either hardware or software.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getcaps HRESULT IDirectSoundBuffer::GetCaps([Out] DSBCAPS* pDSBufferCaps) IDirectSoundBuffer::GetCaps The GetCurrentPosition method retrieves the position of the play and write cursors in the sound buffer.
Address of a variable that receives the offset, in bytes, of the play cursor. This parameter can be null if the value is not wanted.
Address of a variable that receives the offset, in bytes, of the write cursor. This parameter can be null if the value is not wanted.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

The write cursor is the point in the buffer ahead of which it is safe to write data to the buffer. Data should not be written to the part of the buffer after the play cursor and before the write cursor.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getcurrentposition HRESULT IDirectSoundBuffer::GetCurrentPosition([Out, Optional] unsigned int* pdwCurrentPlayCursor,[Out, Optional] unsigned int* pdwCurrentWriteCursor) IDirectSoundBuffer::GetCurrentPosition The GetFormat method retrieves a description of the format of the sound data in the buffer, or the buffer size needed to retrieve the format description.
Address of a or structure that receives a description of the sound data in the buffer. To retrieve the buffer size needed to contain the format description, specify null. In this case the variable at pdwSizeWritten receives the size of the structure needed to receive the data.
Size, in bytes, of the structure at pwfxFormat. If pwfxFormat is not null, this value must be equal to or greater than the size of the expected data.
Address of a variable that receives the number of bytes written to the structure at pwfxFormat. This parameter can be null.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The format structure can have a variable length that depends on the format. Before retrieving the format description, the application should query the buffer object for the size of the format by calling this method and specifying null for the pwfxFormat parameter. The necessary size of the structure is returned in the pdwSizeWritten parameter. The application can then allocate sufficient memory and call GetFormat again to retrieve the format description.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getformat HRESULT IDirectSoundBuffer::GetFormat([Out, Buffer, Optional] WAVEFORMATEX* pwfxFormat,[In] unsigned int dwSizeAllocated,[Out, Optional] unsigned int* pdwSizeWritten) IDirectSoundBuffer::GetFormat The GetVolume method retrieves the attenuation of the sound.
Address of a variable that receives the attenuation, in hundredths of a decibel.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

The return value is between and . These values are defined as 0 and ?10,000, respectively. The value represents the original, unadjusted volume of the sound. The value indicates an audio volume attenuated by 100 dB, which, for practical purposes, is silence.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getvolume HRESULT IDirectSoundBuffer::GetVolume([Out] int* plVolume) IDirectSoundBuffer::GetVolume The GetPan method retrieves the relative volume of the left and right audio channels.
Address of a variable that receives the relative volume, in hundredths of a decibel.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

The returned value is measured in hundredths of a decibel (dB), in the range of DSBPAN_LEFT to DSBPAN_RIGHT. These values are defined in Dsound.h as -10,000 and 10,000 respectively. The value DSBPAN_LEFT means the right channel is effectively silent. The value DSBPAN_RIGHT means the left channel is effectively silent. The neutral value is DSBPAN_CENTER, defined as 0, which means that both channels are at full volume. When one channel is attenuated, the other remains at full volume.

The pan control acts cumulatively with the volume control.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getpan HRESULT IDirectSoundBuffer::GetPan([Out] int* plPan) IDirectSoundBuffer::GetPan The GetFrequency method retrieves the frequency, in samples per second, at which the buffer is playing.
Address of a variable that receives the frequency at which the audio buffer is being played, in hertz.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

The frequency value for software buffers is in the range of DSBFREQUENCY_MIN to DSBFREQUENCY_MAX, defined in Dsound.h. Hardware buffers can return other values.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getfrequency HRESULT IDirectSoundBuffer::GetFrequency([Out] unsigned int* pdwFrequency) IDirectSoundBuffer::GetFrequency The GetStatus method retrieves the status of the sound buffer.
Address of a variable that receives the status of the sound buffer. The status can be a combination of the following flags:
ValueDescription
The buffer is lost and must be restored before it can be played or locked.
The buffer is being looped. If this value is not set, the buffer will stop when it reaches the end of the sound data. This value is returned only in combination with .
The buffer is playing. If this value is not set, the buffer is stopped.
The buffer is playing in software. Set only for buffers created with the flag.
The buffer is playing in hardware. Set only for buffers created with the flag.
The buffer was prematurely terminated by the voice manager and is not playing. Set only for buffers created with the flag.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

is set if the buffer is being heard. Because of latency, a call to Play or Stop might not immediately change the status.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.getstatus HRESULT IDirectSoundBuffer::GetStatus([Out] unsigned int* pdwStatus) IDirectSoundBuffer::GetStatus The Initialize method initializes a sound buffer object if it has not yet been initialized.
Address of the device object associated with this buffer.
Address of a structure that contains the values used to initialize this sound buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values.

Return code
DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

Because the CreateSoundBuffer method calls Initialize internally, applications do not need to call this method.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.initialize HRESULT IDirectSoundBuffer::Initialize([In] IDirectSound* pDirectSound,[In] const DSBUFFERDESC* pcDSBufferDesc) IDirectSoundBuffer::Initialize The Lock method readies all or part of the buffer for a data write and returns references to which data can be written.
Offset, in bytes, from the start of the buffer to the point where the lock begins. This parameter is ignored if is specified in the dwFlags parameter.
Size, in bytes, of the portion of the buffer to lock. The buffer is conceptually circular, so this number can exceed the number of bytes between dwOffset and the end of the buffer.
Address of a variable that receives a reference to the first locked part of the buffer.
Address of a variable that receives the number of bytes in the block at ppvAudioPtr1. If this value is less than dwBytes, the lock has wrapped and ppvAudioPtr2 points to a second block of data at the beginning of the buffer.
Address of a variable that receives a reference to the second locked part of the capture buffer. If null is returned, the ppvAudioPtr1 parameter points to the entire locked portion of the capture buffer.
Address of a variable that receives the number of bytes in the block at ppvAudioPtr2. If ppvAudioPtr2 is null, this value is zero.
Flags modifying the lock event. The following flags are defined:
ValueDescription
Start the lock at the write cursor. The dwOffset parameter is ignored.
Lock the entire buffer. The dwBytes parameter is ignored.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

This method accepts an offset and a byte count, and returns two write references and their associated sizes. If the locked portion does not extend to the end of the buffer and wrap to the beginning, the second reference, ppvAudioBytes2, receives null. If the lock does wrap, ppvAudioBytes2 points to the beginning of the buffer.

If the application passes null for the ppvAudioPtr2 and pdwAudioBytes2 parameters, the lock extends no further than the end of the buffer and does not wrap.

After writing data to the references returned by this method, the application must immediately call Unlock to notify DirectSound that the data is ready for playback. Failure to do so can cause audio breakup or silence on some sound device configurations.

This method returns write references only. The application should not try to read sound data from this reference, because the data might not be valid. For example, if the buffer is located in on-card memory, the reference might be an address to a temporary buffer in system memory. When IDirectSoundBuffer8::Unlock is called, the contents of this temporary buffer are transferred to the on-card memory.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.lock HRESULT IDirectSoundBuffer::Lock([In] unsigned int dwOffset,[In] unsigned int dwBytes,[Out] void** ppvAudioPtr1,[Out] unsigned int* pdwAudioBytes1,[Out] void** ppvAudioPtr2,[Out, Optional] unsigned int* pdwAudioBytes2,[In] DSBLOCK_ENUM dwFlags) IDirectSoundBuffer::Lock The Play method causes the sound buffer to play, starting at the play cursor.
Reserved. Must be 0.
Priority for the sound, used by the voice manager when assigning hardware mixing resources. The lowest priority is 0, and the highest priority is 0xFFFFFFFF. If the buffer was not created with the flag, this value must be 0.
Flags specifying how to play the buffer. The following flags are defined:

Looping flag

ValueDescription
After the end of the audio buffer is reached, play restarts at the beginning of the buffer. Play continues until explicitly stopped. This flag must be set when playing a primary buffer.

Voice allocation flags

The voice allocation flags are valid only for buffers created with the flag. One of the following flags can be used to force the processing of the sound into hardware or software. If neither DBSPLAY_LOCHARDWARE nor DBSPLAY_LOCSOFTWARE is set, the sound is played in either software or hardware, depending on the availability of resources at the time the method is called. See Remarks.

ValueDescription
Play this voice in a hardware buffer only. If the hardware has no available voices and no voice management flags are set, the call to IDirectSoundBuffer8::Play fails. This flag cannot be combined with .
Play this voice in a software buffer only. This flag cannot be combined with or any voice management flag.

Voice management flags

The voice management flags are valid only for buffers created with the flag, and are used for sounds that are to play in hardware. These flags enable hardware resources that are already in use to be yielded to the current sound. Only buffers created with the flag are candidates for premature termination. See Remarks.

ValueDescription
If the hardware has no available voices, a currently playing nonlooping buffer will be stopped to make room for the new buffer. The buffer prematurely terminated is the one with the least time left to play.
If the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. The buffer prematurely terminated will be selected from buffers that have the buffer's DSBCAPS_ MUTE3DATMAXDISTANCE flag set and are beyond their maximum distance. If there are no such buffers, the method fails.
If the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. The buffer prematurely terminated will be the one with the lowest priority as set by the dwPriority parameter passed to IDirectSoundBuffer8::Play for the buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

If SetCooperativeLevel has not been called, the method returns DS_OK, but no sound will be produced until a cooperative level has been set.

If the application is multithreaded, the thread that plays the buffer must continue to exist as long as the buffer is playing. Buffers created on WDM drivers stop playing when the thread is terminated.

If the buffer specified in the method is already playing, the call to the method succeeds and the buffer continues to play. However, the flags defined in the most recent call supersede flags defined in previous calls.

When called on the primary buffer, this method causes the buffer to start playing to the sound device. If the application has set the cooperative level, any audio data put in the primary buffer by the application is sent to the sound device. Under any other cooperative level, the primary buffer plays silence if no secondary buffers are playing. Primary buffers must be played with the flag set.

If the method is called with a voice allocation or voice management flag set on a buffer that was not created with the flag, the call fails with DSERR_INVALIDPARAM.

and cannot be combined, but either may be combined with , in which case the or flag is used to determine which buffer should be terminated in the event of a priority tie.

The following table shows the behavior of the method under various combinations of the voice allocation and voice management flags when no free hardware voices are available.

Neither nor
Sound with least time left to play is terminated and the new sound plays on the released voice. Sound with least time left to play is terminated and the new sound plays on the released voice. New sound plays in software.
If any sounds currently playing in hardware are beyond their maximum distance and have the flag set, one of them is terminated and the new sound plays in hardware. Otherwise, the call fails. If any sounds currently playing in hardware are beyond their maximum distance and have the flag set, one of them is terminated and the new sound plays in hardware. Otherwise, the new sound plays in software. New sound plays in software.
If the new sound's priority is higher than or equal to that of any sound currently playing in hardware, one of the lowest-priority sounds is terminated and the new sound plays in hardware. Otherwise, the call fails. If the new sound's priority is higher than or equal to that of any sound currently playing in hardware, one of the lowest-priority sounds is terminated and the new sound plays in hardware. Otherwise, the new sound plays in software. New sound plays in software.
microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.play HRESULT IDirectSoundBuffer::Play([In] unsigned int dwReserved1,[In] unsigned int dwPriority,[In] DSBPLAY_FLAGS dwFlags) IDirectSoundBuffer::Play The SetCurrentPosition method sets the position of the play cursor, which is the point at which the next byte of data is read from the buffer.
Offset of the play cursor, in bytes, from the beginning of the buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

This method cannot be called on the primary buffer.

If the buffer is playing, the cursor immediately moves to the new position and play continues from that point. If it is not playing, playback will begin from the new position the next time the Play method is called.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setcurrentposition HRESULT IDirectSoundBuffer::SetCurrentPosition([In] unsigned int dwNewPosition) IDirectSoundBuffer::SetCurrentPosition The SetFormat method sets the format of the primary buffer. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.
Address of a structure that describes the new format for the primary sound buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

The format of the primary buffer should be set before secondary buffers are created.

The method fails if the application has the cooperative level.

If the application is using DirectSound at the cooperative level, and the format is not supported, the method fails.

If the cooperative level is , DirectSound stops the primary buffer, changes the format, and restarts the buffer. The method succeeds even if the hardware does not support the requested format; DirectSound sets the buffer to the closest supported format. To determine whether this has happened, an application can call the GetFormat method for the primary buffer and compare the result with the format that was requested with the SetFormat method.

This method is not available for secondary sound buffers. If a new format is required, the application must create a new DirectSoundBuffer object.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setformat HRESULT IDirectSoundBuffer::SetFormat([In] const void* pcfxFormat) IDirectSoundBuffer::SetFormat The SetVolume method sets the attenuation of the sound.
Attenuation, in hundredths of a decibel (dB).

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

Allowable values are between (no attenuation) and (silence). These values are defined in Dsound.h as 0 and ?10,000 respectively. The value represents the original, unadjusted volume of the stream. The value indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. DirectSound does not support amplification.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setvolume HRESULT IDirectSoundBuffer::SetVolume([In] int lVolume) IDirectSoundBuffer::SetVolume The SetPan method sets the relative volume of the left and right channels.
Relative volume between the left and right channels.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

The returned value is measured in hundredths of a decibel (dB), in the range of DSBPAN_LEFT to DSBPAN_RIGHT. These values are defined in Dsound.h as -10,000 and 10,000 respectively. The value DSBPAN_LEFT means the right channel is attenuated by 100 dB and is effectively silent. The value DSBPAN_RIGHT means the left channel is silent. The neutral value is DSBPAN_CENTER, defined as 0, which means that both channels are at full volume. When one channel is attenuated, the other remains at full volume.

The pan control acts cumulatively with the volume control.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setpan HRESULT IDirectSoundBuffer::SetPan([In] int lPan) IDirectSoundBuffer::SetPan The SetFrequency method sets the frequency at which the audio samples are played.
Frequency, in hertz (Hz), at which to play the audio samples. A value of DSBFREQUENCY_ORIGINAL resets the frequency to the default value of the buffer format.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

Increasing or decreasing the frequency changes the perceived pitch of the audio data. This method does not affect the format of the buffer.

Before setting the frequency, you should ascertain whether the frequency is supported by checking the dwMinSecondarySampleRate and dwMaxSecondarySampleRate members of the structure for the device. Some operating systems do not support frequencies greater than 100,000 Hz.

This method is not valid for the primary buffer.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.setfrequency HRESULT IDirectSoundBuffer::SetFrequency([In] unsigned int dwFrequency) IDirectSoundBuffer::SetFrequency The Stop method causes the sound buffer to stop playing.

If the method succeeds, the return value is DS_OK. Returns an error code if the method fails.

For secondary sound buffers, IDirectSoundBuffer8::Stop sets the play cursor to the sample that follows the last sample played. This means that when the Play method is next called on the buffer, it will continue playing where it left off.

For the primary buffer, if an application has the level, this method will stop the buffer and reset the play cursor to 0 (the beginning of the buffer). This is necessary because the primary buffers on most sound cards can play only from the beginning of the buffer.

However, if IDirectSoundBuffer8::Stop is called on a primary buffer and the application has a cooperative level other than , this method simply reverses the effects of IDirectSoundBuffer8::Play. It configures the primary buffer to stop if no secondary buffers are playing. If other buffers are playing in this or other applications, the primary buffer will not actually stop until they are stopped. This method is useful because playing the primary buffer consumes processing overhead even if the buffer is playing sound data with the amplitude of 0 decibels.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.stop HRESULT IDirectSoundBuffer::Stop() IDirectSoundBuffer::Stop The Unlock method releases a locked sound buffer.
Address of the value retrieved in the ppvAudioPtr1 parameter of the Lock method.
Number of bytes written to the portion of the buffer at pvAudioPtr1. See Remarks.
Address of the value retrieved in the ppvAudioPtr2 parameter of the IDirectSoundBuffer8::Lock method.
Number of bytes written to the portion of the buffer at pvAudioPtr2. See Remarks.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

An application must pass both references, pvAudioPtr1 and pvAudioPtr2, returned by the IDirectSoundBuffer8::Lock method to ensure the correct pairing of IDirectSoundBuffer8::Lock and IDirectSoundBuffer8::Unlock. The second reference is needed even if nothing was written to the second reference.

The values in dwAudioBytes1 and dwAudioBytes2 must specify the number of bytes actually written to each part of the buffer, which might be less than the size of the lock. DirectSound uses these values to determine how much data to commit to the device.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.unlock HRESULT IDirectSoundBuffer::Unlock([In, Buffer] void* pvAudioPtr1,[In] unsigned int dwAudioBytes1,[In, Buffer, Optional] void* pvAudioPtr2,[In] unsigned int dwAudioBytes2) IDirectSoundBuffer::Unlock The Restore method restores the memory allocation for a lost sound buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code

  • DSERR_BUFFERLOST

  • DSERR_INVALIDCALL

  • DSERR_PRIOLEVELNEEDED

If the application does not have the input focus, IDirectSoundBuffer8::Restore might not succeed. For example, if the application with the input focus has the cooperative level, no other application will be able to restore its buffers. Similarly, an application with the cooperative level must have the input focus to restore its primary buffer.

After DirectSound restores the buffer memory, the application must rewrite the buffer with valid sound data. DirectSound cannot restore the contents of the memory, only the memory itself.

The application can receive notification that a buffer is lost when it specifies that buffer in a call to the Lock or Play method. These methods return DSERR_BUFFERLOST to indicate a lost buffer. The GetStatus method can also be used to retrieve the status of the sound buffer and test for the flag.

 microsoft.directx_sdk.idirectsoundbuffer8.idirectsoundbuffer8.restore HRESULT IDirectSoundBuffer::Restore() IDirectSoundBuffer::Restore HRESULT IDirectSoundBuffer::Play([None] int dwReserved1,[None] int dwPriority,[None] int dwFlags) The Lock method readies all or part of the buffer for a data write and returns pointers to which data can be written. Offset, in bytes, from the start of the buffer to the point where the lock begins. This parameter is ignored if DSBLOCK_FROMWRITECURSOR is specified in the dwFlags parameter. Size, in bytes, of the portion of the buffer to lock. The buffer is conceptually circular, so this number can exceed the number of bytes between dwOffset and the end of the buffer. Flags modifying the lock event. The following flags are defined: ValueDescription DSBLOCK_FROMWRITECURSORStart the lock at the write cursor. The dwOffset parameter is ignored. DSBLOCK_ENTIREBUFFERLock the entire buffer. The dwBytes parameter is ignored. Address of a variable that receives a pointer to the second locked part of the capture buffer. If NULL is returned, the ppvAudioPtr1 parameter points to the entire locked portion of the capture buffer. Address of a variable that receives a pointer to the first locked part of the buffer. HRESULT IDirectSoundBuffer::Lock([None] int dwOffset,[None] int dwBytes,[Out] void** ppvAudioPtr1,[Out] int* pdwAudioBytes1,[Out] void** ppvAudioPtr2,[Out, Optional] int* pdwAudioBytes2,[None] int dwFlags) The Unlock method releases a locked sound buffer. Address of the value retrieved in the ppvAudioPtr1 parameter of the {{Lock}} method. Address of the value retrieved in the ppvAudioPtr2 parameter of the IDirectSoundBuffer8::Lock method. No documentation. HRESULT IDirectSoundBuffer::Unlock([In, Buffer] void* pvAudioPtr1,[None] int dwAudioBytes1,[In, Buffer, Optional] void* pvAudioPtr2,[None] int dwAudioBytes2) Writes data to the buffer. The data. The buffer offset. The flags. Writes data to the buffer. The data. The start index. The count. The buffer offset. The flags. Sets the notification positions. The positions. Sets the new format for the primary sound buffer. The wave format. HRESULT IDirectSoundBuffer::SetFormat([In] const WAVEFORMATEX* pcfxFormat)

The IDirectSound3DBuffer8 interface is used to retrieve and set parameters that describe the position, orientation, and environment of a sound buffer in 3D space.

IDirectSound3DBuffer8 is a define for . The two interface names are interchangeable.

The IDirectSound3DBuffer8 interface is obtained from a buffer that was created with the flag. You can get it from the interface by using the QueryInterface method.

In addition to the methods inherited from , the IDirectSound3DBuffer8 interface exposes the following methods, arranged by category.

3D mode
Method Description
IDirectSound3DBuffer8::GetMode The GetMode method retrieves the operation mode for 3D sound processing.
IDirectSound3DBuffer8::SetMode The SetMode method sets the operation mode for 3D sound processing.
Batch Parameters
Method Description
IDirectSound3DBuffer8::GetAllParameters The GetAllParameters method retrieves the 3D properties of the sound buffer.
IDirectSound3DBuffer8::SetAllParameters The SetAllParameters method sets all 3D sound buffer properties.
Minimum and Maximum Distance
Method Description
IDirectSound3DBuffer8::GetMaxDistance The GetMaxDistance method retrieves the maximum distance, which is the distance from the listener beyond which sounds in this buffer are no longer attenuated.
IDirectSound3DBuffer8::GetMinDistance The GetMinDistance method retrieves the minimum distance, which is the distance from the listener at which sounds in this buffer begin to be attenuated.
IDirectSound3DBuffer8::SetMaxDistance The SetMaxDistance method sets the maximum distance, which is the distance from the listener beyond which sounds in this buffer are no longer attenuated.
IDirectSound3DBuffer8::SetMinDistance The SetMinDistance method sets the minimum distance, which is the distance from the listener at which sounds in this buffer begin to be attenuated.
Position
Method Description
IDirectSound3DBuffer8::GetPosition The GetPosition method retrieves the position of the sound source.
IDirectSound3DBuffer8::SetPosition The SetPosition method sets the position of the sound source.
Sound Projection Cone
Method Description
IDirectSound3DBuffer8::GetConeAngles The GetConeAngles method retrieves the inside and outside angles of the sound projection cone.
IDirectSound3DBuffer8::GetConeOrientation The GetConeOrientation method retrieves the orientation of the sound projection cone.
IDirectSound3DBuffer8::GetConeOutsideVolume The GetConeOutsideVolume method retrieves the volume of the sound outside the outside angle of the sound projection cone.
IDirectSound3DBuffer8::SetConeAngles The SetConeAngles method sets the inside and outside angles of the sound projection cone.
IDirectSound3DBuffer8::SetConeOrientation The SetConeOrientation method sets the orientation of the sound projection cone.
IDirectSound3DBuffer8::SetConeOutsideVolume The SetConeOutsideVolume method sets the volume of the sound outside the outside angle of the sound projection cone.
Velocity
Method Description
IDirectSound3DBuffer8::GetVelocity The GetVelocity method retrieves the velocity of the sound source.
IDirectSound3DBuffer8::SetVelocity The SetVelocity method sets the velocity of the sound source.

The LPDIRECTSOUND3DBUFFER type is defined as a reference to the IDirectSound3DBuffer8 interface:

 typedef struct   *LPDIRECTSOUND3DBUFFER;
ee417960 IDirectSound3DBuffer IDirectSound3DBuffer Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the 3D properties of the sound buffer.
Address of a structure that receives the information describing the 3D characteristics of the sound buffer.

If the method succeeds, the return value is DS_OK.

If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getallparameters HRESULT IDirectSound3DBuffer::GetAllParameters([Out] DS3DBUFFER* pDs3dBuffer) IDirectSound3DBuffer::GetAllParameters The GetConeAngles method retrieves the inside and outside angles of the sound projection cone.
Addresses of a variable that receives the inside angle of the sound projection cone, in degrees. This is the angle within which the sound is at its normal volume.
Addresses of a variable that receives the outside angle of the sound projection cone, in degrees. This is the angle outside of which the sound is at its outside volume.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The minimum, maximum, and default cone angles are defined in Dsound.h as DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, and DS3D_DEFAULTCONEANGLE.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getconeangles HRESULT IDirectSound3DBuffer::GetConeAngles([Out] unsigned int* pdwInsideConeAngle,[Out] unsigned int* pdwOutsideConeAngle) IDirectSound3DBuffer::GetConeAngles The GetConeOrientation method retrieves the orientation of the sound projection cone.
Address of a structure that receives the orientation of the sound projection cone. The vector information represents the center of the sound cone.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The values returned are not necessarily the same as those set by using the SetConeOrientation method. DirectSound normalizes orientation vectors so that all axes have a magnitude of less than or equal to 1.0.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getconeorientation HRESULT IDirectSound3DBuffer::GetConeOrientation([Out] D3DVECTOR* pvOrientation) IDirectSound3DBuffer::GetConeOrientation The GetConeOutsideVolume method retrieves the volume of the sound outside the outside angle of the sound projection cone.
Address of a variable that receives the cone outside volume for this buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

Volume levels are expressed as attenuation, in hundredths of a decibel. Allowable values are between (no attenuation) and (silence). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation). These values are defined in Dsound.h. DirectSound does not support amplification.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getconeoutsidevolume HRESULT IDirectSound3DBuffer::GetConeOutsideVolume([Out] int* plConeOutsideVolume) IDirectSound3DBuffer::GetConeOutsideVolume The GetMaxDistance method retrieves the maximum distance, which is the distance from the listener beyond which sounds in this buffer are no longer attenuated.
Address of a variable that receives the maximum distance, in meters by default. D3DVALUE is defined as float.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The default maximum distance, defined as DS3D_DEFAULTMAXDISTANCE, is effectively infinite.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmaxdistance HRESULT IDirectSound3DBuffer::GetMaxDistance([Out] float* pflMaxDistance) IDirectSound3DBuffer::GetMaxDistance The GetMinDistance method retrieves the minimum distance, which is the distance from the listener at which sounds in this buffer begin to be attenuated.
Address of a variable that receives the minimum distance, in meters by default. D3DVALUE is defined as float.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

By default, the minimum distance value is DS3D_DEFAULTMINDISTANCE, defined as 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 meters per unit).

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmindistance HRESULT IDirectSound3DBuffer::GetMinDistance([Out] float* pflMinDistance) IDirectSound3DBuffer::GetMinDistance The GetMode method retrieves the operation mode for 3D sound processing.
Address of a variable that receives the mode setting. This value will be one of those in the following table.
ValueDescription
Processing of 3D sound is disabled. The sound seems to originate from the center of the listener's head.
Sound parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener's parameters change, so that the relative parameters remain constant.
Normal processing. This is the default mode.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getmode HRESULT IDirectSound3DBuffer::GetMode([Out] unsigned int* pdwMode) IDirectSound3DBuffer::GetMode The GetPosition method retrieves the position of the sound source.
Address of a structure that receives the position of the sound buffer.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

By default, distance units are meters, but the units can be changed by using the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getposition HRESULT IDirectSound3DBuffer::GetPosition([Out] D3DVECTOR* pvPosition) IDirectSound3DBuffer::GetPosition The GetVelocity method retrieves the velocity of the sound source.
Address of a structure that receives the sound buffer's velocity, in meters per second by default.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

Velocity is used for Doppler effects only. It does not actually move the buffer. For more information, see Doppler Effect.

The default unit of measurement is meters per second, but this can be changed by using the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.getvelocity HRESULT IDirectSound3DBuffer::GetVelocity([Out] D3DVECTOR* pvVelocity) IDirectSound3DBuffer::GetVelocity The SetAllParameters method sets all 3D sound buffer properties.
Address of a structure that describes the 3D characteristics of the sound buffer.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setallparameters HRESULT IDirectSound3DBuffer::SetAllParameters([In] const DS3DBUFFER* pcDs3dBuffer,[In] unsigned int dwApply) IDirectSound3DBuffer::SetAllParameters The SetConeAngles method sets the inside and outside angles of the sound projection cone.
Inside cone angle, in degrees. This is the angle within which the sound is at its normal volume.
Outside cone angle, in degrees. This is the angle outside of which the sound is at its outside volume.
Value that indicates when the setting should be applied. Must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The minimum, maximum, and default cone angles are defined in Dsound.h as DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, and DS3D_DEFAULTCONEANGLE. Each angle must be in the range of 0 degrees (no cone) to 360 degrees (the full sphere). The default value is 360.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setconeangles HRESULT IDirectSound3DBuffer::SetConeAngles([In] unsigned int dwInsideConeAngle,[In] unsigned int dwOutsideConeAngle,[In] unsigned int dwApply) IDirectSound3DBuffer::SetConeAngles The SetConeOrientation method sets the orientation of the sound projection cone.
Value that specifies the x coordinate of the sound cone orientation vector. D3DVALUE is defined as float.
Value that specifies the y coordinate of the sound cone orientation vector. D3DVALUE is defined as float.
Value that specifies the z coordinate of the sound cone orientation vector. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

This method has no effect unless the cone angle and cone outside volume have also been set to values other than the default.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setconeorientation HRESULT IDirectSound3DBuffer::SetConeOrientation([In] float x,[In] float y,[In] float z,[In] unsigned int dwApply) IDirectSound3DBuffer::SetConeOrientation The SetConeOutsideVolume method sets the volume of the sound outside the outside angle of the sound projection cone.
Cone outside volume, in hundredths of a decibel.
Value that specifies when the setting should be applied. This value must be one of the those shown in the following table.
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

Volume levels are represented by attenuation. Allowable values are between (no attenuation) and (silence). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation). These values are defined in Dsound.h. DirectSound does not support amplification.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setconeoutsidevolume HRESULT IDirectSound3DBuffer::SetConeOutsideVolume([In] int lConeOutsideVolume,[In] unsigned int dwApply) IDirectSound3DBuffer::SetConeOutsideVolume The SetMaxDistance method sets the maximum distance, which is the distance from the listener beyond which sounds in this buffer are no longer attenuated.
Maximum distance, in meters by default. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The default maximum distance, defined as DS3D_DEFAULTMAXDISTANCE, is effectively infinite.

The default unit of measurement is meters, but this can be changed by using the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setmaxdistance HRESULT IDirectSound3DBuffer::SetMaxDistance([In] float flMaxDistance,[In] unsigned int dwApply) IDirectSound3DBuffer::SetMaxDistance The SetMinDistance method sets the minimum distance, which is the distance from the listener at which sounds in this buffer begin to be attenuated.
Minimum distance, in meters by default. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

By default, the minimum distance value is DS3D_DEFAULTMINDISTANCE, defined as 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 meters per unit).

The default unit of measurement is meters, but this can be changed by using the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setmindistance HRESULT IDirectSound3DBuffer::SetMinDistance([In] float flMinDistance,[In] unsigned int dwApply) IDirectSound3DBuffer::SetMinDistance The SetMode method sets the operation mode for 3D sound processing.
Flag specifying the 3D sound processing mode to be set. The flags in the following table are defined.
ValueDescription
Processing of 3D sound is disabled. The sound seems to originate from the center of the listener's head.
Sound parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener's parameters change, so that the relative parameters remain constant.
Normal processing. This is the default mode.
Value that specifies when the setting should be applied. This value must be one of those in the following table.
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setmode HRESULT IDirectSound3DBuffer::SetMode([In] unsigned int dwMode,[In] unsigned int dwApply) IDirectSound3DBuffer::SetMode The SetPosition method sets the position of the sound source.
Value that specifies the x coordinate of the position vector. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the y coordinate of the position vector. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the z coordinate of the position vector. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The default unit of measurement is meters, but this can be changed by using the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setposition HRESULT IDirectSound3DBuffer::SetPosition([In] float x,[In] float y,[In] float z,[In] unsigned int dwApply) IDirectSound3DBuffer::SetPosition The SetVelocity method sets the velocity of the sound source.
Value that specifies the x coordinate of the velocity vector, in meters per second by default. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the y coordinate of the velocity vector, in meters per second by default. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the z coordinate of the velocity vector, in meters per second by default. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

Velocity is used only for calculating Doppler effect. It does not change the position of the buffer. For more information, see Doppler Effect.

The default unit of measurement is meters per second, but this can be changed by using the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dbuffer8.idirectsound3dbuffer8.setvelocity HRESULT IDirectSound3DBuffer::SetVelocity([In] float x,[In] float y,[In] float z,[In] unsigned int dwApply) IDirectSound3DBuffer::SetVelocity Default cone angle, in degrees. Default outside cone volume. Volume levels are expressed as attenuation, in hundredths of a decibel. Default maximum distance, in meters. Default minimum distance, in meters. Maximum cone angle, in degrees. Minimum cone angle, in degrees. Initializes a new instance of the class. Gets or sets all the parameters of a buffer The orientation of the sound projection cone. The volume of the sound outside the outside angle of the sound projection cone. Settings are not applied until the application calls the SoundListener3D.CommitDeferredSettings() if true. The inside angle of the sound projection cone. The maximum distance, which is the distance from the listener beyond which sounds in this buffer are no longer attenuated. The minimum distance, which is the distance from the listener at which sounds in this buffer begin to be attenuated. The operation mode for 3-D sound processing. The outside angle of the sound projection cone. The position of the sound source. The velocity of the sound source.

The IDirectSoundNotify8 interface sets up notification events for a playback or capture buffer.

IDirectSoundNotify8 is a define for . The two interface names are interchangeable.

The interface is obtained by calling the QueryInterface method of an existing interface on a DirectSound buffer object. Secondary buffers support notifications only if they are created with the flag.

In addition to the methods inherited from , the IDirectSoundNotify8 interface exposes the following method.

IDirectSoundNotify8 Member
Method Description
IDirectSoundNotify8::SetNotificationPositions The SetNotificationPositions method sets the notification positions. During capture or playback, whenever the read or play cursor reaches one of the specified offsets, the associated event is signaled.

The LPDIRECTSOUNDNOTIFY type is defined as a reference to the interface:

 typedef struct   *LPDIRECTSOUNDNOTIFY;
ee418244 IDirectSoundNotify IDirectSoundNotify Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The SetNotificationPositions method sets the notification positions. During capture or playback, whenever the read or play cursor reaches one of the specified offsets, the associated event is signaled.
Number of structures.
Pointer to an array of structures (the maximum array size is DSBNOTIFICATIONS_MAX).

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY

The value DSBPN_OFFSETSTOP can be specified in the dwOffset member to tell DirectSound to signal the associated event when the Stop or Stop method is called or when the end of the buffer has been reached and the playback is not looping. If it is used, this should be the last item in the position-notify array.

If a position-notify array has already been set, the method replaces the previous array.

The buffer must be stopped when this method is called.

 microsoft.directx_sdk.idirectsoundnotify8.idirectsoundnotify8.setnotificationpositions HRESULT IDirectSoundNotify::SetNotificationPositions([In] unsigned int dwPositionNotifies,[In, Buffer] const DSBPOSITIONNOTIFY* pcPositionNotifies) IDirectSoundNotify::SetNotificationPositions

The IDirectSound3DListener8 interface is used to retrieve and set parameters that describe a listener's position, orientation, and listening environment in 3D space.

The interface can be obtained by calling the IDirectSoundBuffer8::QueryInterface method on a primary buffer created with the flag.

In addition to the methods inherited from , the IDirectSound3DListener8 interface exposes the following methods, arranged by category.

Batch Parameters
Method Description
IDirectSound3DListener8::CommitDeferredSettings The CommitDeferredSettings method commits any deferred settings made since the last call to this method.
IDirectSound3DListener8::GetAllParameters The GetAllParameters method retrieves all 3D parameters of the sound environment and the listener.
IDirectSound3DListener8::SetAllParameters The SetAllParameters method sets all 3D parameters of the sound environment and the listener.
Global Sound Properties
Method Description
IDirectSound3DListener8::GetDistanceFactor The GetDistanceFactor method retrieves the distance factor, which is the number of meters in a vector unit.
IDirectSound3DListener8::GetDopplerFactor The GetDopplerFactor method retrieves the multiplier for the Doppler effect.
IDirectSound3DListener8::GetRolloffFactor The GetRolloffFactor method retrieves the rolloff factor, which determines the rate of attenuation over distance.
IDirectSound3DListener8::SetDistanceFactor The SetDistanceFactor method sets the distance factor, which is the number of meters in a vector unit.
IDirectSound3DListener8::SetDopplerFactor The SetDopplerFactor method sets the multiplier for the Doppler effect.
IDirectSound3DListener8::SetRolloffFactor The SetRolloffFactor method sets the rolloff factor, which determines the rate of attenuation over distance.
Listener Properties
Method Description
IDirectSound3DListener8::GetOrientation The GetOrientation method retrieves the orientation of the listener's head.
IDirectSound3DListener8::GetPosition The GetPosition method retrieves the listener's position.
IDirectSound3DListener8::GetVelocity The GetVelocity method retrieves the listener's velocity.
IDirectSound3DListener8::SetOrientation The SetOrientation method sets the orientation of the listener's head.
IDirectSound3DListener8::SetPosition The SetPosition method sets the listener's position.
IDirectSound3DListener8::SetVelocity The SetVelocity method sets the listener's velocity.

The LPDIRECTSOUND3DLISTENER type is defined as a reference to the interface:

 typedef struct   *LPDIRECTSOUND3DLISTENER;
ee418003 IDirectSound3DListener IDirectSound3DListener Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves all 3D parameters of the sound environment and the listener.
Address of a structure that receives the state of the 3D world and listener.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getallparameters HRESULT IDirectSound3DListener::GetAllParameters([Out] DS3DLISTENER* pListener) IDirectSound3DListener::GetAllParameters The GetDistanceFactor method retrieves the distance factor, which is the number of meters in a vector unit.
Address of a variable that receives the distance factor value. D3DVALUE is defined as float.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getdistancefactor HRESULT IDirectSound3DListener::GetDistanceFactor([Out] float* pflDistanceFactor) IDirectSound3DListener::GetDistanceFactor The GetDopplerFactor method retrieves the multiplier for the Doppler effect.
Address of a variable that receives the Doppler factor value. D3DVALUE is defined as float.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The Doppler factor has a range of DS3D_MINDOPPLERFACTOR (no Doppler effects) to DS3D_MAXDOPPLERFACTOR (defined as 10 times the Doppler effects found in the real world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getdopplerfactor HRESULT IDirectSound3DListener::GetDopplerFactor([Out] float* pflDopplerFactor) IDirectSound3DListener::GetDopplerFactor The GetOrientation method retrieves the orientation of the listener's head.
Address of a structure that receives the listener's front orientation vector.
Address of a structure that receives the listener's top orientation vector.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The front vector points in the direction of the listener's nose, and the top vector points up from the top of the listener's head. By default, the front vector is (0,0,1.0) and the top vector is (0,1.0,0).

The values returned are not necessarily the same as those set by using SetOrientation. DirectSound normalizes orientation vectors so that they are at right angles and have a magnitude of less than or equal to 1.0.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getorientation HRESULT IDirectSound3DListener::GetOrientation([Out] D3DVECTOR* pvOrientFront,[Out] D3DVECTOR* pvOrientTop) IDirectSound3DListener::GetOrientation The GetPosition method retrieves the listener's position.
Address of a structure that receives the listener's position vector.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

By default, measurement units are meters, but this can be changed by calling the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getposition HRESULT IDirectSound3DListener::GetPosition([Out] D3DVECTOR* pvPosition) IDirectSound3DListener::GetPosition The GetRolloffFactor method retrieves the rolloff factor, which determines the rate of attenuation over distance.
Address of a variable that receives the rolloff factor. D3DVALUE is defined as float.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The rolloff factor has a range of DS3D_MINROLLOFFFACTOR (no rolloff) to DS3D_MAXROLLOFFFACTOR (defined as 10 times the rolloff found in the real world). The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0). For more information, see Rolloff Factor.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getrollofffactor HRESULT IDirectSound3DListener::GetRolloffFactor([Out] float* pflRolloffFactor) IDirectSound3DListener::GetRolloffFactor The GetVelocity method retrieves the listener's velocity.
Address of a structure that receives the listener's velocity.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

Velocity is used only for calculating Doppler effect. It does not change the listener's position. To move the listener, use the SetPosition method.

The default velocity is (0,0,0).

By default, measurement units are meters per second, but this can be changed by calling the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.getvelocity HRESULT IDirectSound3DListener::GetVelocity([Out] D3DVECTOR* pvVelocity) IDirectSound3DListener::GetVelocity The SetAllParameters method sets all 3D parameters of the sound environment and the listener.
Address of a structure that contains information describing all 3D listener parameters.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setallparameters HRESULT IDirectSound3DListener::SetAllParameters([In] const DS3DLISTENER* pcListener,[In] unsigned int dwApply) IDirectSound3DListener::SetAllParameters The SetDistanceFactor method sets the distance factor, which is the number of meters in a vector unit.
Distance factor. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The distance factor has a range of DS3D_MINDISTANCEFACTOR to DS3D_MAXDISTANCEFACTOR, defined in Dsound.h as FLT_MIN and FLT_MAX respectively. The default value is DS3D_DEFAULTDISTANCEFACTOR, or 1.0.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setdistancefactor HRESULT IDirectSound3DListener::SetDistanceFactor([In] float flDistanceFactor,[In] unsigned int dwApply) IDirectSound3DListener::SetDistanceFactor The SetDopplerFactor method sets the multiplier for the Doppler effect.
Doppler factor. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The Doppler factor has a range of DS3D_MINDOPPLERFACTOR (no Doppler effects) to DS3D_MAXDOPPLERFACTOR (defined as 10 times the Doppler effects found in the real world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setdopplerfactor HRESULT IDirectSound3DListener::SetDopplerFactor([In] float flDopplerFactor,[In] unsigned int dwApply) IDirectSound3DListener::SetDopplerFactor The SetOrientation method sets the orientation of the listener's head.
Value that specifies the x coordinate of the front orientation vector. D3DVALUE is defined as float.
Value that specifies the y coordinate of the front orientation vector. D3DVALUE is defined as float.
Value that specifies the z coordinate of the front orientation vector. D3DVALUE is defined as float.
Value that specifies the x coordinates of the top orientation vector.
Value that specifies the y coordinates of the top orientation vector.
Value that specifies the z coordinates of the top orientation vector.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The front vector points in the direction of the listener's nose, and the top vector points up from the top of the listener's head. By default, the front vector is (0,0,1.0) and the top vector is (0,1.0,0).

The top vector must be at right angles to the front vector. If necessary, DirectSound adjusts the top vector after setting the front vector.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setorientation HRESULT IDirectSound3DListener::SetOrientation([In] float xFront,[In] float yFront,[In] float zFront,[In] float xTop,[In] float yTop,[In] float zTop,[In] unsigned int dwApply) IDirectSound3DListener::SetOrientation The SetPosition method sets the listener's position.
Value that specifies the x coordinate of the listener's position vector. Note that DirectSound may adjust this value to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the y coordinate of the listener's position vector. Note that DirectSound may adjust this value to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the z coordinate of the listener's position vector. Note that DirectSound may adjust this value to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

By default, measurement units are meters, but this can be changed by calling the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setposition HRESULT IDirectSound3DListener::SetPosition([In] float x,[In] float y,[In] float z,[In] unsigned int dwApply) IDirectSound3DListener::SetPosition The SetRolloffFactor method sets the rolloff factor, which determines the rate of attenuation over distance.
Rolloff factor. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

The rolloff factor has a range of DS3D_MINROLLOFFFACTOR (no rolloff) to DS3D_MAXROLLOFFFACTOR (defined as 10 times the rolloff found in the real world). The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0). For more information, see Rolloff Factor.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setrollofffactor HRESULT IDirectSound3DListener::SetRolloffFactor([In] float flRolloffFactor,[In] unsigned int dwApply) IDirectSound3DListener::SetRolloffFactor The SetVelocity method sets the listener's velocity.
Value that specifies the x coordinate of the listener's velocity vector. DirectSound may adjust this value to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the y coordinate of the listener's velocity vector. DirectSound may adjust this value to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies the z coordinate of the listener's velocity vector. DirectSound may adjust this value to prevent floating-point overflow. D3DVALUE is defined as float.
Value that specifies when the setting should be applied. This value must be one of the following:
ValueDescription
DS3D_DEFERREDSettings are not applied until the application calls the CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATESettings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use the SetPosition method. The default velocity is (0,0,0).

By default, measurement units are meters per second, but this can be changed by calling the SetDistanceFactor method.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.setvelocity HRESULT IDirectSound3DListener::SetVelocity([In] float x,[In] float y,[In] float z,[In] unsigned int dwApply) IDirectSound3DListener::SetVelocity The CommitDeferredSettings method commits any deferred settings made since the last call to this method.

If the method succeeds, the return value is DS_OK.

 microsoft.directx_sdk.idirectsound3dlistener8.idirectsound3dlistener8.commitdeferredsettings HRESULT IDirectSound3DListener::CommitDeferredSettings() IDirectSound3DListener::CommitDeferredSettings Default distance factor. The default value is (1.0). Default Doppler factor. The default value is (1.0). Default rolloff factor. The default value is (1.0). Maximum distance factor. The default value is (1.0). Maximum Doppler factor. The default value is (1.0). Maximum rolloff factor. The default value is (1.0). Minimum distance factor. The default value is (1.0). Minimum Doppler factor. The default value is (1.0). Minimum rolloff factor. The default value is (1.0). Initializes a new instance of the class with a previously created sound buffer. The SlimDX::DirectSound::SoundBuffer object. Determines if settings are set immediately or deferred. Gets or sets the distance factor, which is the number of meters in a vector unit. Gets or sets the multiplier for the Doppler effect. Describes the listener's front orientation. Gets or sets the listener's position. Gets or sets the rolloff factor, which determines the rate of attenuation over distance. Describes the listener's top orientation. Gets or sets the listener's velocity.

The IDirectSoundFXWavesReverb8 interface is used to set and retrieve effect parameters on a buffer that supports Waves reverberation.

This interface is obtained by calling GetObjectInPath on the buffer that supports the effect.

In addition to the methods inherited from , the IDirectSoundFXWavesReverb8 interface exposes the following methods.

IDirectSoundFXWavesReverb8 Members
Method Description
IDirectSoundFXWavesReverb8::GetAllParameters The GetAllParameters method retrieves the music reverberation parameters of a buffer.
IDirectSoundFXWavesReverb8::SetAllParameters The SetAllParameters method sets the music reverberation parameters of a buffer.

The Waves reverberation DMO is based on the Waves MaxxVerb technology, which is licenced to Microsoft.

 ee418241 IDirectSoundFXWavesReverb IDirectSoundFXWavesReverb Initializes a new instance of the class. The native pointer. Performs an explicit conversion from to . (This method is a shortcut to ) The native pointer. The result of the conversion. The GetAllParameters method retrieves the music reverberation parameters of a buffer. microsoft.directx_sdk.idirectsoundfxwavesreverb8.idirectsoundfxwavesreverb8.getallparameters GetAllParameters / SetAllParameters GetAllParameters HRESULT IDirectSoundFXWavesReverb::GetAllParameters([Out] DSFXWavesReverb* pDsFxWavesReverb) The SetAllParameters method sets the music reverberation parameters of a buffer.
Address of a structure that specifies the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxwavesreverb8.idirectsoundfxwavesreverb8.setallparameters HRESULT IDirectSoundFXWavesReverb::SetAllParameters([In] const DSFXWavesReverb* pcDsFxWavesReverb) IDirectSoundFXWavesReverb::SetAllParameters The GetAllParameters method retrieves the music reverberation parameters of a buffer.
Address of a structure that receives the effect parameters.

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be DSERR_INVALIDPARAM.

 microsoft.directx_sdk.idirectsoundfxwavesreverb8.idirectsoundfxwavesreverb8.getallparameters HRESULT IDirectSoundFXWavesReverb::GetAllParameters([Out] DSFXWavesReverb* pDsFxWavesReverb) IDirectSoundFXWavesReverb::GetAllParameters Default high-frequency reverb time ratio. Maximum high-frequency reverb time ratio. Minimum high-frequency reverb time ratio. Default input gain of signal, in decibels (dB). Maximum input gain of signal, in decibels (dB). Minimum input gain of signal, in decibels (dB). Default reverb mix, in dB. Maximum reverb mix, in dB. Minimum reverb mix, in dB. Default reverb time, in milliseconds. Maximum reverb time, in milliseconds. Minimum reverb time, in milliseconds. The structure contains parameters for acoustic echo cancellation in a capture buffer.

The dwMode member is ignored when this structure is passed to IDirectSoundCaptureFXAec8::SetAllParameters.

Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.reference.dscfxaec DSCFXAec DSCFXAec
Boolean value that specifies whether the effect is enabled.
microsoft.directx_sdk.reference.dscfxaec BOOL fEnable BOOL fEnable
Boolean value that specifies whether to enable background comfort noise, which makes the capture signal sound more natural by preventing periods of dead silence. By default, background comfort noise is not enabled.
microsoft.directx_sdk.reference.dscfxaec BOOL fNoiseFill BOOL fNoiseFill
Operation mode. This member contains one of the following values.
Value Description
The effect is passing capture and render data through without modifying it.
The effect is running in half duplex mode. Not presently supported.
The effect is running in full duplex mode.
microsoft.directx_sdk.reference.dscfxaec DSCFX_AEC_MODE dwMode DSCFX_AEC_MODE dwMode No documentation. DSBCAPS DSBCAPS No documentation. unsigned int dwSize unsigned int dwSize No documentation. DSBCAPS_FLAGS dwFlags DSBCAPS_FLAGS dwFlags No documentation. unsigned int dwBufferBytes unsigned int dwBufferBytes No documentation. unsigned int dwUnlockTransferRate unsigned int dwUnlockTransferRate No documentation. unsigned int dwPlayCpuOverhead unsigned int dwPlayCpuOverhead Initializes a new instance of the class. The structure contains parameters for a chorus effect. microsoft.directx_sdk.reference.dsfxchorus DSFXChorus DSFXChorus
Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXCHORUS_WETDRYMIX_MIN through DSFXCHORUS_WETDRYMIX_MAX (all wet). The default value is 50.
microsoft.directx_sdk.reference.dsfxchorus float fWetDryMix float fWetDryMix
Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Must be in the range from DSFXCHORUS_DEPTH_MIN through DSFXCHORUS_DEPTH_MAX. The default value is 10.
microsoft.directx_sdk.reference.dsfxchorus float fDepth float fDepth
Percentage of output signal to feed back into the effect's input, in the range from DSFXCHORUS_FEEDBACK_MIN to DSFXCHORUS_FEEDBACK_MAX. The default value is 25.
microsoft.directx_sdk.reference.dsfxchorus float fFeedback float fFeedback
Frequency of the LFO, in the range from DSFXCHORUS_FREQUENCY_MIN to DSFXCHORUS_FREQUENCY_MAX. The default value is 1.1.
microsoft.directx_sdk.reference.dsfxchorus float fFrequency float fFrequency
Waveform shape of the LFO. Defined values are DSFXCHORUS_WAVE_TRIANGLE and DSFXCHORUS_WAVE_SIN. By default, the waveform is a sine.
microsoft.directx_sdk.reference.dsfxchorus int lWaveform int lWaveform
Number of milliseconds the input is delayed before it is played back, in the range from DSFXCHORUS_DELAY_MIN to DSFXCHORUS_DELAY_MAX. The default value is 16 ms.
microsoft.directx_sdk.reference.dsfxchorus float fDelay float fDelay
Phase differential between left and right LFOs, in the range from DSFXCHORUS_PHASE_MIN through DSFXCHORUS_PHASE_MAX. Possible values are defined as follows.
Value
DSFXCHORUS_PHASE_NEG_180
DSFXCHORUS_PHASE_NEG_90
DSFXCHORUS_PHASE_ZERO
DSFXCHORUS_PHASE_90
DSFXCHORUS_PHASE_180

The default value is DSFXCHORUS_PHASE_90.

 microsoft.directx_sdk.reference.dsfxchorus int lPhase int lPhase The structure contains parameters for a compression effect. microsoft.directx_sdk.reference.dsfxcompressor DSFXCompressor DSFXCompressor
Output gain of signal after compression, in the range from DSFXCOMPRESSOR_GAIN_MIN to DSFXCOMPRESSOR_GAIN_MAX. The default value is 0 dB.
microsoft.directx_sdk.reference.dsfxcompressor float fGain float fGain
Time before compression reaches its full value, in the range from DSFXCOMPRESSOR_ATTACK_MIN to DSFXCOMPRESSOR_ATTACK_MAX. The default value is 10 ms.
microsoft.directx_sdk.reference.dsfxcompressor float fAttack float fAttack
Speed at which compression is stopped after input drops below fThreshold, in the range from DSFXCOMPRESSOR_RELEASE_MIN to DSFXCOMPRESSOR_RELEASE_MAX. The default value is 200 ms.
microsoft.directx_sdk.reference.dsfxcompressor float fRelease float fRelease
Point at which compression begins, in decibels, in the range from DSFXCOMPRESSOR_THRESHOLD_MIN to DSFXCOMPRESSOR_THRESHOLD_MAX. The default value is -20 dB.
microsoft.directx_sdk.reference.dsfxcompressor float fThreshold float fThreshold
Compression ratio, in the range from DSFXCOMPRESSOR_RATIO_MIN to DSFXCOMPRESSOR_RATIO_MAX. The default value is 3, which means 3:1 compression.
microsoft.directx_sdk.reference.dsfxcompressor float fRatio float fRatio
Time after lThreshold is reached before attack phase is started, in milliseconds, in the range from DSFXCOMPRESSOR_PREDELAY_MIN to DSFXCOMPRESSOR_PREDELAY_MAX. The default value is 4 ms.
microsoft.directx_sdk.reference.dsfxcompressor float fPredelay float fPredelay The structure contains parameters for a distortion effect.

The values in fPostEQBandwidth, fPostEQCenterFrequency, and fPreLowpassCutoff cannot exceed one-third of the frequency of the buffer. If an attempt is made to set a value greater than this, but within the range of accepted values, the parameter is set to the nearest supported value and S_FALSE is returned by IDirectSoundFXDistortion8::SetAllParameters.

 microsoft.directx_sdk.reference.dsfxdistortion DSFXDistortion DSFXDistortion
Amount of signal change after distortion, in the range from DSFXDISTORTION_GAIN_MIN through DSFXDISTORTION_GAIN_MAX. The default value is -18 dB.
microsoft.directx_sdk.reference.dsfxdistortion float fGain float fGain
Percentage of distortion intensity, in the range in the range from DSFXDISTORTION_EDGE_MIN through DSFXDISTORTION_EDGE_MAX. The default value is 15 percent.
microsoft.directx_sdk.reference.dsfxdistortion float fEdge float fEdge
Center frequency of harmonic content addition, in the range from DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN through DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX. The default value is 2400 Hz.
microsoft.directx_sdk.reference.dsfxdistortion float fPostEQCenterFrequency float fPostEQCenterFrequency
Width of frequency band that determines range of harmonic content addition, in the range from DSFXDISTORTION_POSTEQBANDWIDTH_MIN through DSFXDISTORTION_POSTEQBANDWIDTH_MAX. The default value is 2400 Hz.
microsoft.directx_sdk.reference.dsfxdistortion float fPostEQBandwidth float fPostEQBandwidth
Filter cutoff for high-frequency harmonics attenuation, in the range from DSFXDISTORTION_PRELOWPASSCUTOFF_MIN through DSFXDISTORTION_PRELOWPASSCUTOFF_MAX. The default value is 8000 Hz.
microsoft.directx_sdk.reference.dsfxdistortion float fPreLowpassCutoff float fPreLowpassCutoff The structure contains parameters for an echo effect. microsoft.directx_sdk.reference.dsfxecho DSFXEcho DSFXEcho
Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXECHO_WETDRYMIX_MIN through DSFXECHO_WETDRYMIX_MAX (all wet). The default value is 50.
microsoft.directx_sdk.reference.dsfxecho float fWetDryMix float fWetDryMix
Percentage of output fed back into input, in the range from DSFXECHO_FEEDBACK_MIN through DSFXECHO_FEEDBACK_MAX. The default value is 50.
microsoft.directx_sdk.reference.dsfxecho float fFeedback float fFeedback
Delay for left channel, in milliseconds, in the range from DSFXECHO_LEFTDELAY_MIN through DSFXECHO_LEFTDELAY_MAX. The default value is 500 ms.
microsoft.directx_sdk.reference.dsfxecho float fLeftDelay float fLeftDelay
Delay for right channel, in milliseconds, in the range from DSFXECHO_RIGHTDELAY_MIN through DSFXECHO_RIGHTDELAY_MAX. The default value is 500 ms.
microsoft.directx_sdk.reference.dsfxecho float fRightDelay float fRightDelay
Value that specifies whether to swap left and right delays with each successive echo. The default value is zero, meaning no swap. Possible values are defined as DSFXECHO_PANDELAY_MIN (equivalent to ) and DSFXECHO_PANDELAY_MAX (equivalent to TRUE).
microsoft.directx_sdk.reference.dsfxecho int lPanDelay int lPanDelay The structure contains parameters for a flange effect. microsoft.directx_sdk.reference.dsfxflanger DSFXFlanger DSFXFlanger
Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXFLANGER_WETDRYMIX_MIN through DSFXFLANGER_WETDRYMIX_MAX (all wet). The default value is 50.
microsoft.directx_sdk.reference.dsfxflanger float fWetDryMix float fWetDryMix
Percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Must be in the range from DSFXFLANGER_DEPTH_MIN through DSFXFLANGER_DEPTH_MAX. The default value is 100.
microsoft.directx_sdk.reference.dsfxflanger float fDepth float fDepth
Percentage of output signal to feed back into the effect's input, in the range from DSFXFLANGER_FEEDBACK_MIN to DSFXFLANGER_FEEDBACK_MAX. The default value is -50.
microsoft.directx_sdk.reference.dsfxflanger float fFeedback float fFeedback
Frequency of the LFO, in the range from DSFXFLANGER_FREQUENCY_MIN to DSFXFLANGER_FREQUENCY_MAX. The default value is 0.25.
microsoft.directx_sdk.reference.dsfxflanger float fFrequency float fFrequency
Waveform shape of the LFO. By default, the waveform is a sine. Possible values are defined in the following table.
Value Description
DSFXFLANGER_WAVE_TRIANGLE Triangle.
DSFXFLANGER_WAVE_SIN Sine.
microsoft.directx_sdk.reference.dsfxflanger int lWaveform int lWaveform
Number of milliseconds the input is delayed before it is played back, in the range from DSFXFLANGER_DELAY_MIN to DSFXFLANGER_DELAY_MAX. The default value is 2 ms.
microsoft.directx_sdk.reference.dsfxflanger float fDelay float fDelay
Phase differential between left and right LFOs, in the range from DSFXFLANGER_PHASE_MIN through DSFXFLANGER_PHASE_MAX. Possible values are defined in the following table.
Value
DSFXFLANGER_PHASE_NEG_180
DSFXFLANGER_PHASE_NEG_90
DSFXFLANGER_PHASE_ZERO
DSFXFLANGER_PHASE_90
DSFXFLANGER_PHASE_180

The default value is DSFXFLANGER_PHASE_ZERO.

 microsoft.directx_sdk.reference.dsfxflanger int lPhase int lPhase The structure contains parameters for an amplitude modulation effect. microsoft.directx_sdk.reference.dsfxgargle DSFXGargle DSFXGargle
Rate of modulation, in Hertz. Must be in the range from DSFXGARGLE_RATEHZ_MIN through DSFXGARGLE_RATEHZ_MAX. The default value is 20.
microsoft.directx_sdk.reference.dsfxgargle unsigned int dwRateHz unsigned int dwRateHz
Shape of the modulation waveform. The following values are defined.
Value Description
DSFXGARGLE_WAVE_TRIANGLE Triangular waveform.
DSFXGARGLE_WAVE_SQUARE Square waveform.

The default value is DSFXGARGLE_WAVE_TRIANGLE.

 microsoft.directx_sdk.reference.dsfxgargle unsigned int dwWaveShape unsigned int dwWaveShape The structure contains parameters for an I3DL2 (Interactive 3D Audio Level 2) reverberation effect. microsoft.directx_sdk.reference.dsfxi3dl2reverb DSFXI3DL2Reverb DSFXI3DL2Reverb
Attenuation of the room effect, in millibels (mB), in the range from DSFX_I3DL2REVERB_ROOM_MIN to DSFX_I3DL2REVERB_ROOM_MAX. The default value is DSFX_I3DL2REVERB_ROOM_DEFAULT, or -1000 mB.
microsoft.directx_sdk.reference.dsfxi3dl2reverb int lRoom int lRoom
Attenuation of the room high-frequency effect, in mB, in the range from DSFX_I3DL2REVERB_ROOMHF_MIN to DSFX_I3DL2REVERB_ROOMHF_MAX. The default value is DSFX_I3DL2REVERB_ROOMHF_DEFAULT, or -100 mB.
microsoft.directx_sdk.reference.dsfxi3dl2reverb int lRoomHF int lRoomHF
Rolloff factor for the reflected signals, in the range from DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN to DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX. The default value is DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT, or 0.0. The rolloff factor for the direct path is controlled by the DirectSound listener.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flRoomRolloffFactor float flRoomRolloffFactor
Decay time, in seconds, in the range from DSFX_I3DL2REVERB_DECAYTIME_MIN to DSFX_I3DL2REVERB_DECAYTIME_MAX. The default value is DSFX_I3DL2REVERB_DECAYTIME_DEFAULT, or 1.49 second.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flDecayTime float flDecayTime
Ratio of the decay time at high frequencies to the decay time at low frequencies, in the range from DSFX_I3DL2REVERB_DECAYHFRATIO_MIN to DSFX_I3DL2REVERB_DECAYHFRATIO_MAX. The default value is DSFX_I3DL2REVERB_DECAYHFRATIO_DEFAULT, or 0.83.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flDecayHFRatio float flDecayHFRatio
Attenuation of early reflections relative to lRoom, in mB, in the range from DSFX_I3DL2REVERB_REFLECTIONS_MIN to DSFX_I3DL2REVERB_REFLECTIONS_MAX. The default value is DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT, or -2602 mB.
microsoft.directx_sdk.reference.dsfxi3dl2reverb int lReflections int lReflections
Delay time of the first reflection relative to the direct path, in seconds, in the range from DSFX_I3DL2REVERB_REFLECTIONSDELAY_MIN to DSFX_I3DL2REVERB_REFLECTIONSDELAY_DEFAULT. The default value is 0.007 seconds.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flReflectionsDelay float flReflectionsDelay
Attenuation of late reverberation relative to lRoom, in mB, in the range -from DSFX_I3DL2REVERB_REVERB_MIN to DSFX_I3DL2REVERB_REVERB_MAX. The default value is DSFX_I3DL2REVERB_REVERB_DEFAULT, or 200 mB.
microsoft.directx_sdk.reference.dsfxi3dl2reverb int lReverb int lReverb
Time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds, in the range from DSFX_I3DL2REVERB_REVERBDELAY_MIN to DSFX_I3DL2REVERB_REVERBDELAY_MAX. The default value is DSFX_I3DL2REVERB_REVERBDELAY_DEFAULT, or 0.011 seconds.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flReverbDelay float flReverbDelay
Echo density in the late reverberation decay, in percent, in the range from DSFX_I3DL2REVERB_DIFFUSION_MIN to DSFX_I3DL2REVERB_DIFFUSION_MAX. The default value is DSFX_I3DL2REVERB_DIFFUSION_DEFAULT, or 100.0 percent.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flDiffusion float flDiffusion
Modal density in the late reverberation decay, in percent, in the range from DSFX_I3DL2REVERB_DENSITY_MIN to DSFX_I3DL2REVERB_DENSITY_MAX. The default value is DSFX_I3DL2REVERB_DENSITY_DEFAULT, or 100.0 percent.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flDensity float flDensity
Reference high frequency, in hertz, in the range from DSFX_I3DL2REVERB_HFREFERENCE_MIN to DSFX_I3DL2REVERB_HFREFERENCE_MAX. The default value is DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT, or 5000.0 Hz.
microsoft.directx_sdk.reference.dsfxi3dl2reverb float flHFReference float flHFReference The structure describes the 3D world parameters and the position of the listener. This structure is used with theIDirectSound3DListener8::GetAllParametersandIDirectSound3DListener8::SetAllParametersmethods. microsoft.directx_sdk.reference.ds3dlistener DS3DLISTENER DS3DLISTENER No documentation. microsoft.directx_sdk.reference.ds3dlistener unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.ds3dlistener D3DVECTOR vPosition D3DVECTOR vPosition No documentation. microsoft.directx_sdk.reference.ds3dlistener D3DVECTOR vVelocity D3DVECTOR vVelocity No documentation. microsoft.directx_sdk.reference.ds3dlistener D3DVECTOR vOrientFront D3DVECTOR vOrientFront No documentation. microsoft.directx_sdk.reference.ds3dlistener D3DVECTOR vOrientTop D3DVECTOR vOrientTop No documentation. microsoft.directx_sdk.reference.ds3dlistener float flDistanceFactor float flDistanceFactor No documentation. microsoft.directx_sdk.reference.ds3dlistener float flRolloffFactor float flRolloffFactor No documentation. microsoft.directx_sdk.reference.ds3dlistener float flDopplerFactor float flDopplerFactor Initializes a new instance of the class. The structure contains parameters for noise suppression in a capture buffer.
Windows

Important Note for Windows Vista

Existing applications that access Windows XP Acoustic Echo Cancellation (AEC) features via the DirectSound API will no longer obtain AEC when running on Windows Vista. These applications will still run, but their calls to AEC-specific DirectSound API calls will have no effect on the captured audio.

To learn how to obtain AEC in Windows Vista, See the Windows Vista AEC topics in the Windows SDK.

 microsoft.directx_sdk.reference.dscfxnoisesuppress DSCFXNoiseSuppress DSCFXNoiseSuppress
Boolean value that specifies whether the effect is enabled.
microsoft.directx_sdk.reference.dscfxnoisesuppress BOOL fEnable BOOL fEnable No documentation. DSBPOSITIONNOTIFY DSBPOSITIONNOTIFY No documentation. unsigned int dwOffset unsigned int dwOffset No documentation. void* hEventNotify void hEventNotify Gets or sets the wait handle. The wait handle. The structure contains parameters for a parametric equalizer effect.

The value in fCenter cannot exceed one-third of the sampling frequency of the buffer. If an attempt is made to set a value greater than this, but within the range of accepted values, the parameter is set to the nearest supported value and S_FALSE is returned by IDirectSoundFXParamEq8::SetAllParameters.

 microsoft.directx_sdk.reference.dsfxparameq DSFXParamEq DSFXParamEq
Center frequency, in hertz, in the range from DSFXPARAMEQ_CENTER_MIN to DSFXPARAMEQ_CENTER_MAX. The default value is 8000.
microsoft.directx_sdk.reference.dsfxparameq float fCenter float fCenter
Bandwidth, in semitones, in the range from DSFXPARAMEQ_BANDWIDTH_MIN to DSFXPARAMEQ_BANDWIDTH_MAX. The default value is 12.
microsoft.directx_sdk.reference.dsfxparameq float fBandwidth float fBandwidth
Gain, in the range from DSFXPARAMEQ_GAIN_MIN to DSFXPARAMEQ_GAIN_MAX. The default value is 0.
microsoft.directx_sdk.reference.dsfxparameq float fGain float fGain The structure describes the characteristics of a new buffer object. It is used by theIDirectSound8::CreateSoundBuffermethod and by theDirectSoundFullDuplexCreate8function.

An earlier version of this structure, DSBUFFERDESC1, is maintained in Dsound.h for compatibility with DirectX 7 and earlier.

When creating a primary buffer, applications must set the dwBufferBytes member to zero. DirectSound will determine the best buffer size for the particular sound device in use. To determine the size of a created primary buffer, call IDirectSoundBuffer8::GetCaps.

The DSBCAPS_CTRLDEFAULT flag is no longer supported. This flag was defined as | | . By specifying only the flags you need, you cut down on unnecessary resource usage.

On VXD drivers, a sound buffer created with is always a software buffer, because the VXD driver model does not support notifications. With WDM drivers, a notification-enabled buffer can be in hardware, if hardware resources are available.

The and flags are optional and mutually exclusive. forces the buffer to reside in hardware, meaning that it will be mixed by the sound card. forces the buffer to reside in software, where it is mixed by the CPU. These flags are also defined for the dwFlags member .

The 3D 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, is treated as a special case. If no free 3D hardware voices are available, the buffer is then treated as a 2D buffer, but with 3D control. Specifically, when a sound buffer is created with , or when the buffer is played if the buffer was created with DSBPLAY_LOCDEFER, the following procedure is followed:

  1. If a free hardware 3D voice is available, that 3D hardware voice is used.

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

  3. If no free 2D or 3D hardware voices are available, the voice will be played in software using the algorithm.

If a speaker configuration other than or 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), a success code, DS_NO_VIRTUALIZATION, is returned. The sound buffer created will use instead. For this reason, applications should use the SUCCEEDED or FAILED macros rather than checking explicitly for DS_OK when calling CreateSoundBuffer.

 microsoft.directx_sdk.reference.dsbufferdesc DSBUFFERDESC DSBUFFERDESC No documentation. microsoft.directx_sdk.reference.dsbufferdesc unsigned int dwSize unsigned int dwSize No documentation. microsoft.directx_sdk.reference.dsbufferdesc DSBCAPS_FLAGS dwFlags DSBCAPS_FLAGS dwFlags No documentation. microsoft.directx_sdk.reference.dsbufferdesc unsigned int dwBufferBytes unsigned int dwBufferBytes No documentation. microsoft.directx_sdk.reference.dsbufferdesc unsigned int dwReserved unsigned int dwReserved No documentation. microsoft.directx_sdk.reference.dsbufferdesc WAVEFORMATEX* lpwfxFormat WAVEFORMATEX lpwfxFormat No documentation. microsoft.directx_sdk.reference.dsbufferdesc GUID guid3DAlgorithm GUID guid3DAlgorithm Initializes a new instance of the class. WaveFormat of this sound buffer description The structure describes an effect associated with a buffer.

Custom effects can be implemented as DMOs. Effect DMOs must implement the and interfaces.

If dwFlags is zero, the effect is placed in hardware if possible. If the hardware does not support the effect (always the case since DirectX 9.0), software is used. If the effect is not available at all, the call to SetFX fails.

 microsoft.directx_sdk.reference.dseffectdesc DSEFFECTDESC DSEFFECTDESC
Size of the structure, in bytes.
microsoft.directx_sdk.reference.dseffectdesc unsigned int dwSize unsigned int dwSize
Flags. Can be zero or one of the following values.
Value Description
DSFX_LOCHARDWARE Effect must be in hardware. If the effect is not available in hardware, raises an error. Since DirectX 9.0, DirectX does not support hardware acceleration of effects, so this flag should not be used.
DSFX_LOCSOFTWARE Effect must be in software, even if the hardware supports acceleration of guidDSFXClass. If the effect is not available in software, SetFX raises an error. Since DirectX 9.0, all effects are in software regardless of whether this flag is set.
microsoft.directx_sdk.reference.dseffectdesc unsigned int dwFlags unsigned int dwFlags
Class identifier of the effect. The following standard effect classes are defined.
Value Description
Chorus
Compressor
Distortion
Echo
Flanger
Gargle
Interactive 3D Level 2 reverb
Parametric equalizer
Waves reverb
microsoft.directx_sdk.reference.dseffectdesc GUID guidDSFXClass GUID guidDSFXClass
Reserved for future use.
microsoft.directx_sdk.reference.dseffectdesc ULONG_PTR dwReserved1 ULONG_PTR dwReserved1
Reserved for future use.
microsoft.directx_sdk.reference.dseffectdesc ULONG_PTR dwReserved2 ULONG_PTR dwReserved2 Initializes a new instance of the class. The structure contains parameters for a Waves reverberation effect. microsoft.directx_sdk.reference.dsfxwavesreverb DSFXWavesReverb DSFXWavesReverb
Input gain of signal, in decibels (dB), in the range from DSFX_WAVESREVERB_INGAIN_MIN through DSFX_WAVESREVERB_INGAIN_MAX. The default value is DSFX_WAVESREVERB_INGAIN_DEFAULT, or 0 dB.
microsoft.directx_sdk.reference.dsfxwavesreverb float fInGain float fInGain
Reverb mix, in dB, in the range from DSFX_WAVESREVERB_REVERBMIX_MIN through DSFX_WAVESREVERB_REVERBMIX_MAX. The default value is DSFX_WAVESREVERB_REVERBMIX_DEFAULT, or 0 dB.
microsoft.directx_sdk.reference.dsfxwavesreverb float fReverbMix float fReverbMix
Reverb time, in milliseconds, in the range from DSFX_WAVESREVERB_REVERBTIME_MIN through DSFX_WAVESREVERB_REVERBTIME_MAX. The default value is DSFX_WAVESREVERB_REVERBTIME_DEFAULT, or 1000.
microsoft.directx_sdk.reference.dsfxwavesreverb float fReverbTime float fReverbTime
High-frequency reverb time ratio, in the range from DSFX_WAVESREVERB_HIGHFREQRTRATIO_MIN through DSFX_WAVESREVERB_HIGHFREQRTRATIO_MAX. The default value is DSFX_WAVESREVERB_HIGHFREQRTRATIO_DEFAULT, or 0.001.
microsoft.directx_sdk.reference.dsfxwavesreverb float fHighFreqRTRatio float fHighFreqRTRatio The namespace provides a managed DirectSound API. ee416960 DirectSound DirectSound A Primary DirectSound Buffer. Initializes a new instance of the class. The base PTR. Initializes a new instance of the class. an instance of the The buffer description.