Skip to content

Listener

class Listener

A object which can render sound sources.

The Listener class is a lightweight reference to a ListenerInternalState which is managed by the Engine. Multiple Listener objects may point to the same underlying data.

Functions

Name Description
Listener Construct an uninitialized Listener.
Listener Creates a wrapper instance over the provided state.
Clear Uninitializes this Listener.
Valid Checks whether this Listener has been initialized.
GetId Gets the ID of this Listener.
GetVelocity Gets the velocity of the Listener.
GetLocation Gets the location of this Listener.
SetLocation Sets the location of this Listener.
GetDirection Gets the direction vector of the Listener.
GetUp Gets the up vector of the Listener.
SetOrientation Sets the location, direction and up vector of this Listener.
GetOrientation Gets the orientation of the Listener.
SetDirectivity Sets the directivity and sharpness of Listener. This affects how sounds are perceived * by the Listener.
GetDirectivity Gets the directivity of sounds played by this Listener.
GetDirectivitySharpness Gets the directivity sharpness of sounds played by this Listener.
GetInverseMatrix Gets the inverse matrix of the Listener.
Update Update the state of this Listener.
GetState Returns the internal state of this Listener.

Function Details

Clear

void Clear()

Uninitializes this Listener.

Note that this does not destroy the internal state it references, it just removes this reference to it.

To completely destroy the Listener, use RemoveListener() method of the Engine instance. 

amEngine->RemoveListener(1234); // You should provide the listener ID

GetDirection

[[nodiscard]] AmVec3 GetDirection() const

Gets the direction vector of the Listener.

Return
The direction vector.

GetDirectivity

[[nodiscard]] AmReal32 GetDirectivity() const

Gets the directivity of sounds played by this Listener.

Return
The directivity of sound sources.

GetDirectivitySharpness

[[nodiscard]] AmReal32 GetDirectivitySharpness() const

Gets the directivity sharpness of sounds played by this Listener.

Return
The directivity sharpness of sounds played by this Listener.

GetId

[[nodiscard]] AmListenerID GetId() const

Gets the ID of this Listener.

Return
The Listener ID.

GetInverseMatrix

[[nodiscard]] const AmMat4& GetInverseMatrix() const

Gets the inverse matrix of the Listener.

You can use this matrix to convert locations from global space to Listener space.

GetLocation

[[nodiscard]] const AmVec3& GetLocation() const

Gets the location of this Listener.

Return
The location of this Listener.

GetOrientation

[[nodiscard]] Orientation GetOrientation() const

Gets the orientation of the Listener.

Return
The orientation of this Listener.

GetState

[[nodiscard]] ListenerInternalState* GetState() const

Returns the internal state of this Listener.

Return
The Listener internal state.

Warning

This method is for internal usage only.

GetUp

[[nodiscard]] AmVec3 GetUp() const

Gets the up vector of the Listener.

Return
The up vector.

GetVelocity

[[nodiscard]] const AmVec3& GetVelocity() const

Gets the velocity of the Listener.

Return
The listener's velocity.

Listener

Listener()

Construct an uninitialized Listener.

An uninitialized Listener cannot have its location set or queried, nor render sound sources.

To create an initialized Listener, use the AddListener() method of the Engine instance. 

amEngine->AddListener(1234); // You should provide an unique ID

explicit Listener(ListenerInternalState* state)

Creates a wrapper instance over the provided state.

Parameter state
The internal state to wrap.

Warning

This constructor is for internal usage only.

SetDirectivity

void SetDirectivity(AmReal32 directivity, AmReal32 sharpness) const

Sets the directivity and sharpness of Listener. This affects how sounds are perceived * by the Listener.

Parameter directivity
The directivity of the listener, in the range [0, 1].
Parameter sharpness
The directivity sharpness of the listener, in the range [1, +INF]. Increasing this value increases the directivity towards the front of the listener.

SetLocation

void SetLocation(const AmVec3& location) const

Sets the location of this Listener.

Parameter location
The new location of this Listener.

SetOrientation

void SetOrientation(const Orientation& orientation) const

Sets the location, direction and up vector of this Listener.

Parameter orientation
The new orientation of this Listener.

Update

void Update() const

Update the state of this Listener.

This method is called automatically by the Engine on each frames to update the internal state of the Listener

Warning

This method is for internal usage only.

Valid

[[nodiscard]] bool Valid() const

Checks whether this Listener has been initialized.

Return
true if this Listener is initialized, false otherwise.