Purpose: This object is used to retrieve and
set parameters that describe the position, orientation, and environment of a
sound buffer in 3-D space
Remark: The returns values are based on the DirectX9
constants except DM_FAILED
The functions raise a CDMusicException
exception type with the error
data.
Member functions:
Function:
GetAllBufferParameters
Declaration: HRESULT C3DBuffer::GetAllBufferParameters(LPDS3DBUFFER pDs3dBuffer)
Purpose:
This method retrieves the 3-D properties of the sound buffer
Parameters:
pDs3dBuffer [out]: Address of a DS3DBUFFER structure that receives the information describing the 3-D characteristics of the sound buffer
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetBufferPosition
Declaration: HRESULT C3DBuffer::GetBufferPosition(D3DVECTOR *pvPosition)
Purpose: Retrieves the position of
the sound source
Parameters:
pvPosition [out]: Address of a D3DVECTOR structure that receives the position of the sound buffer
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetConeAngles
Declaration: HRESULT C3DBuffer::GetConeAngles(LPDWORD pdwInsideConeAngle,LPDWORD pdwOutsideConeAngle)
Purpose: Retrieves the inside and
outside angles of the sound projection cone
Parameters:
pdwInsideConeAngle [out]: 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
pdwOutsideConeAngle [out]: 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
Remarks: The minimum, maximum, and
default cone angles are defined in Dsound.h as DS3D_MINCONEANGLE,
DS3D_MAXCONEANGLE, and DS3D_DEFAULTCONEANGLE.
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetConeOrientation
Declaration: HRESULT C3DBuffer::GetConeOrientation(D3DVECTOR *pvOrientation)
Purpose: Retrieves the orientation
of the sound projection cone
Parameters:
pvOrientation [out]: Address of a D3DVECTOR structure that receives the orientation of the sound projection cone. The vector information represents the center of the sound cone
Remarks: 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
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetConeOutsideVolume
Declaration: HRESULT C3DBuffer::GetConeOutsideVolume(LPLONG plConeOutsideVolume)
Purpose:
Retrieves the volume of the sound outside the outside angle of the sound
projection cone
Parameters:
plConeOutsideVolume [out]: Address of a variable that receives the cone outside volume for this buffer
Remarks: Volume levels are expressed
as attenuation, in hundredths of a decibel. Allowable values are between
DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). The default value is
DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation). These values are defined in
Dsound.h. DirectSound does not support amplification.
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetMaxDistance
Declaration: HRESULT C3DBuffer::GetMaxDistance(D3DVALUE *pflMaxDistance)
Purpose:
Retrieves the maximum distance, which is the distance from the listener beyond
which sounds in this buffer are no longer attenuated
Parameters:
pflMaxDistance [out]: Address of a variable that receives the maximum distance, in meters by default. D3DVALUE is defined as float
Remarks: The default maximum
distance, defined as DS3D_DEFAULTMAXDISTANCE, is effectively infinite
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetMinDistance
Declaration: HRESULT C3DBuffer::GetMinDistance(D3DVALUE *pflMinDistance)
Purpose:
Retrieves retrieves the minimum distance, which is the distance from the
listener at which sounds in this buffer begin to be attenuated
Parameters:
pflMinDistance [out]: Address of a variable that receives the minimum distance, in meters by default. D3DVALUE is defined as float
Remarks: 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).
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetMode
Declaration: HRESULT C3DBuffer::GetMode(LPDWORD pdwMode)
Purpose:
Retrieves the operation mode for 3-D sound processing
Parameters:
pdwMode [out]: Address of a variable that receives the mode setting. This value will be one of those in the following table.
| Value | Description |
| DS3DMODE_DISABLE | Processing of 3-D sound is disabled. The sound seems to originate from the center of the listener's head. |
| DS3DMODE_HEADRELATIVE | 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. |
| DS3DMODE_NORMAL | Normal processing. This is the default mode. |
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetVelocity
Declaration: HRESULT C3DBuffer::GetVelocity(D3DVECTOR *pvVelocity)
Purpose:
Retrieves the velocity of the sound source
Parameters:
pvVelocity
[out]: Address of a D3DVECTOR structure that receives the sound
buffer's velocity, in meters per second by default
Remarks: Velocity is used for
Doppler effects only. It does not actually move the buffer
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
ReleaseBuffer
Declaration: HRESULT C3DBuffer::ReleaseBuffer()
Purpose:
Releases the internal buffer interface
Parameters: none
Returns:
| S_FALSE | Error |
| S_OK |
Succeeds |
Function:
SetAllBufferParameters
Declaration: HRESULT C3DBuffer::SetAllBufferParameters(LPCDS3DBUFFER pcDs3dBuffer,DWORD dwApply)
Purpose:
Sets all 3-D properties of the sound buffer
Parameters:
pcDs3dBuffer [in]: Address of a DS3DBUFFER structure that describes the 3-D characteristics of the sound buffer
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetBufferPosition
Declaration: HRESULT C3DBuffer::SetBufferPosition(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose:
Sets the position of the sound source
Parameters:
x,y,z [in]: Values that specify the coordinates of the position vector. DirectSound may adjust these values to prevent floating-point overflow. D3DVALUE is defined as float
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Remarks: The default unit of measurement is meters, but this can be changed by using the C3DListener::SetDistanceFactor method
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetConeAngles
Declaration: HRESULT C3DBuffer::SetConeAngles(DWORD dwInsideConeAngle,DWORD dwOutsideConeAngle,DWORD dwApply)
Purpose:
Sets the inside and outside angles of the sound projection cone
Parameters:
dwInsideConeAngle [in]: Inside cone angle, in degrees. This is the angle within which the sound is at its normal volume
dwOutsideConeAngle [in]: Outside cone angle, in degrees. This is the angle outside of which the sound is at its outside volume
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Remarks: 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
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetConeOrientation
Declaration: HRESULT C3DBuffer::SetConeOrientation(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose: Sets
the orientation of the sound projection cone
Parameters:
x, y, z [in]: Values that specify the coordinates of the sound cone orientation vector. D3DVALUE is defined as float
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetConeOutsideVolume
Declaration: HRESULT C3DBuffer::SetConeOutsideVolume(LONG lConeOutsideVolume,DWORD dwApply)
Purpose: Sets
the volume of the sound outside the outside angle of the sound projection cone
Parameters:
lConeOutsideVolume [in]: Cone outside volume, in hundredths of a decibel
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Remarks
Volume levels are represented by attenuation. Allowable values are between DSBVOLUME_MAX (no attenuation) and DSBVOLUME_MIN (silence). The default value is DS3D_DEFAULTCONEOUTSIDEVOLUME (no attenuation). These values are defined in Dsound.h. DirectSound does not support amplification
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetMaxDistance
Declaration: HRESULT C3DBuffer::SetMaxDistance(D3DVALUE flMaxDistance,DWORD dwApply)
Purpose: Sets
the maximum distance
Parameters:
flMaxDistance [in]: Maximum distance, in meters by default. D3DVALUE is defined as float
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Remarks: 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 C3DListener::SetDistanceFactor
method
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetMinDistance
Declaration: HRESULT C3DBuffer::SetMinDistance(D3DVALUE flMinDistance,DWORD dwApply)
Purpose: Sets
the minimum distance
Parameters:
flMinDistance [in]: Minimum distance, in meters by default. D3DVALUE is defined as float
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Remarks: 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 C3DListener::SetDistanceFactor method
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetMode
Declaration: HRESULT C3DBuffer::SetMode(DWORD dwMode,DWORD dwApply)
Purpose: Sets
the operation mode for 3-D sound processing
Parameters:
dwMode [in]: Flag specifying the 3-D sound processing mode to be set. The following flags are defined:
| Value | Description |
| DS3DMODE_DISABLE | Processing of 3-D sound is disabled. The sound seems to originate from the center of the listener's head. |
| DS3DMODE_HEADRELATIVE | 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. |
| DS3DMODE_NORMAL | Normal processing. This is the default mode. |
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetVelocity
Declaration: HRESULT C3DBuffer::SetVelocity(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose: Sets
the velocity of the sound source
Parameters:
x,y,z [in]: Values that specify the coordinates 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
dwApply [in]: Value that specifies when the setting should be applied. This value must be one of the following:
| Value | Description |
| DS3D_DEFERRED | Settings are not applied until the application calls the C3DListener::CommitDeferredSettings method. This allows the application to change several settings and generate a single recalculation. |
| DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3-D coordinates for all 3-D sound buffers. |
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |