Purpose: This object is used to retrieve and set
parameters that describe a listener's position, orientation, and listening
environment 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:
CommitDeferredSettings
Declaration: HRESULT C3DListener::CommitDeferredSettings()
Purpose:
Commits any deferred settings made since the last call to this method
Parameters: none
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetAllListenerParameters
Declaration: HRESULT C3DListener::GetAllListenerParameters(LPDS3DLISTENER pListener)
Purpose: Retrieves all 3-D
parameters of the sound environment and the listener
Parameters:
pListener [out]: Address of a DS3DLISTENER structure that receives the state of the 3-D world and listener
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetDistanceFactor
Declaration: HRESULT C3DListener::GetDistanceFactor(D3DVALUE *pflDistanceFactor)
Purpose: Retrieves the distance
factor, which is the number of meters in a vector unit
Parameters:
pflDistanceFactor [out]: Address of a variable that receives the distance factor value. D3DVALUE is defined as float
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetDopplerFactor
Declaration: HRESULT C3DListener::GetDopplerFactor(D3DVALUE *pflDopplerFactor)
Purpose:
Retrieves the multiplier for the Doppler effect
Parameters:
pflDopplerFactor [out]: Address of a variable that receives the Doppler factor value. D3DVALUE is defined as float
Remarks: 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).
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetListenerPosition
Declaration: HRESULT C3DListener::GetListenerPosition(D3DVECTOR *pvPosition)
Purpose:
Retrieves the listener's position
Parameters:
pvPosition [out]: Address of a D3DVECTOR structure that receives the listener's position vector
Remarks: By default, measurement units are meters, but this can be
changed by calling 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:
GetOrientation
Declaration: HRESULT C3DListener::GetOrientation(D3DVECTOR *pvOrientFront,D3DVECTOR *pvOrientTop)
Purpose:
Retrieves the orientation of the listener's head
Parameters:
pvOrientFront [out]: Address of a D3DVECTOR structure that receives the listener's front orientation vector
pvOrientTop [out]: Address of a D3DVECTOR structure that receives the listener's top orientation vector
Remarks:
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
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetRolloffFactor
Declaration: HRESULT C3DListener::GetRolloffFactor(D3DVALUE *pflRolloffFactor)
Purpose:
Retrieves the rolloff factor, which determines the rate of attenuation over
distance
Parameters:
pfRolloffFactor [out]: Address of a variable that receives the rolloff factor. D3DVALUE is defined as float
Remarks: 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).
Returns:
| 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 C3DListener::GetVelocity(D3DVECTOR *pvVelocity)
Purpose:
Retrieves the listener's velocity
Parameters:
pvVelocity [out]: Address of a D3DVECTOR structure that receives the listener's velocity
Remarks: Velocity is used only for
calculating Doppler effect. It does not change the listener's position. To move
the listener, use the C3DListener::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 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:
ReleaseListener
Declaration: HRESULT C3DListener::ReleaseListener()
Purpose:
Releases the internal listener interface
Parameters: none
Returns:
| S_FALSE | Error |
| S_OK |
Succeeds |
Function:
SetAllListenerParameters
Declaration: HRESULT C3DListener::SetAllListenerParameters(LPCDS3DLISTENER pcListener,DWORD dwApply)
Purpose:
Sets all 3-D parameters of the sound environment and the listener
Parameters:
pcListener [in]: Address of a DS3DLISTENER structure that contains information describing all 3-D listener parameters
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:
SetDistanceFactor
Declaration: HRESULT C3DListener::SetDistanceFactor(D3DVALUE flDistanceFactor,DWORD dwApply)
Purpose:
Sets the distance factor
Parameters:
flDistanceFactor [in]: Distance factor. 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 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.
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetDopplerFactor
Declaration: HRESULT C3DListener::SetDopplerFactor(D3DVALUE flDopplerFactor,DWORD dwApply)
Purpose:
Sets the multiplier for the Doppler effect
Parameters:
flDopplerFactor [in]: Doppler factor. 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 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).
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetListenerPosition
Declaration: HRESULT C3DListener::SetListenerPosition(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose:
Sets the listener's position
Parameters:
x,y,z [in]: Values that specify the coordinates of the listener's position vector. Note that 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: By default, measurement units are meters, but this can be changed by calling the CListener::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:
SetOrientation
Declaration: HRESULT C3DListener::SetOrientation(D3DVALUE xFront,D3DVALUE yFront,D3DVALUE zFront,D3DVALUE xTop,
D3DVALUE yTop,D3DVALUE zTop,DWORD dwApply)
Purpose:
Sets the orientation of the listener's head
Parameters:
xFront,yFront,zFront
[in]: Values that specify the coordinates of the front orientation vector. D3DVALUE
is
defined as float
xTop,yTop,zTop [in]: Values that specify the coordinates of the top
orientation vector
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 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.
Returns:
| S_OK |
Succeeds |
Throws:
| DSERR_INVALIDPARAM | An invalid parameter was passed to the returning function |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetRolloffFactor
Declaration: HRESULT C3DListener::SetRolloffFactor(D3DVALUE flRolloffFactor,DWORD dwApply)
Purpose:
Sets the rolloff factor
Parameters:
flRolloffFactor [in]: Sets the rolloff factor, which determines the rate of attenuation over distance
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 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)
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 C3DListener::SetVelocity(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose: Sets
the listener's velocity
Parameters:
x,y,z [in]: Values that specify the coordinates of the listener's velocity 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: Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use the C3DListener::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 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 |