C3DListener


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

Top    Index

Function: GetAllListenerParameters
Declaration: HRESULT C3DListener::GetAllListenerParameters(LPDS3DLISTENER pListener)
Purpose:  Retrieves all 3-D parameters of the sound environment and the listener
Parameters:    


Returns:  

S_OK

Succeeds

Throws:

DSERR_INVALIDPARAM An invalid parameter was passed to the returning function
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetDistanceFactor
Declaration: HRESULT C3DListener::GetDistanceFactor(D3DVALUE *pflDistanceFactor)
Purpose:  Retrieves the distance factor, which is the number of meters in a vector unit
Parameters:   


Returns:  

S_OK

Succeeds

Throws:

DSERR_INVALIDPARAM An invalid parameter was passed to the returning function
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetDopplerFactor
Declaration: HRESULT C3DListener::GetDopplerFactor(D3DVALUE *pflDopplerFactor)
Purpose:  Retrieves the multiplier for the Doppler effect
Parameters:    


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

Top    Index

Function: GetListenerPosition
Declaration: HRESULT C3DListener::GetListenerPosition(D3DVECTOR *pvPosition)
Purpose:  Retrieves the listener's position
Parameters:    


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

Top    Index

Function: GetOrientation
Declaration: HRESULT C3DListener::GetOrientation(D3DVECTOR *pvOrientFront,D3DVECTOR *pvOrientTop)
Purpose:  Retrieves the orientation of the listener's head
Parameters:   


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

Top    Index

Function: GetRolloffFactor
Declaration: HRESULT C3DListener::GetRolloffFactor(D3DVALUE *pflRolloffFactor)
Purpose:  Retrieves the rolloff factor, which determines the rate of attenuation over distance
Parameters:   


                    
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

Top    Index

Function: GetVelocity
Declaration: HRESULT C3DListener::GetVelocity(D3DVECTOR *pvVelocity)
Purpose:  Retrieves the listener's velocity
Parameters:    


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

Top    Index

Function: ReleaseListener
Declaration: HRESULT C3DListener::ReleaseListener()
Purpose:  Releases the internal listener interface
Parameters:    none 

Returns:
 

S_FALSE Error
S_OK

Succeeds

Top    Index

Function: SetAllListenerParameters
Declaration: HRESULT C3DListener::SetAllListenerParameters(LPCDS3DLISTENER pcListener,DWORD dwApply)
Purpose:  Sets all 3-D parameters of the sound environment and the listener
Parameters:   

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

Top    Index

Function: SetDistanceFactor
Declaration: HRESULT C3DListener::SetDistanceFactor(D3DVALUE flDistanceFactor,DWORD dwApply)
Purpose:  Sets the distance factor
Parameters:    

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

Top    Index

Function: SetDopplerFactor
Declaration: HRESULT C3DListener::SetDopplerFactor(D3DVALUE flDopplerFactor,DWORD dwApply)
Purpose:  Sets the multiplier for the Doppler effect
Parameters:    

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

Top    Index

Function: SetListenerPosition
Declaration: HRESULT C3DListener::SetListenerPosition(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose:  Sets the listener's position
Parameters:    

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

Top    Index

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:    

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

Top    Index

Function: SetRolloffFactor
Declaration: HRESULT C3DListener::SetRolloffFactor(D3DVALUE flRolloffFactor,DWORD dwApply)
Purpose:  Sets the rolloff factor
Parameters:    

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

Top    Index

Function: SetVelocity
Declaration: HRESULT C3DListener::SetVelocity(D3DVALUE x,D3DVALUE y,D3DVALUE z,DWORD dwApply)
Purpose: Sets the listener's velocity
Parameters:   

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

Top    Index