Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.IListener

The IListener graph node interface.

A listener represents a node positioned in world space that is "listening" to any sound sources (e.g. IAudioSequence nodes) within its hearing range. All captured sources are attenuated according to their distance and given parameters, and mixed together afterwards.

See sceneGraphStatesSlotsUnits for an overview of state handling during scene graph traversal.
See Graph::IListenerTransform for setting a listener's position and orientation. See Graph::IListenerState for activating a listener for rendering.

Gain calculation formula:
REFERENCE_DISTANCE = referenceDistance attribute from IPlayable
ROLLOFF_FACTOR = rolloffFactor attribute from IPlayable
MAX_DISTANCE = maxDistance attribute from IPlayable

  • distanceModel="INVERSE"
    gain = REFERENCE_DISTANCE / (REFERENCE_DISTANCE + ROLLOFF_FACTOR * (distance – REFERENCE_DISTANCE))
  • distanceModel="INVERSE_CLAMPED"
    distance = max(distance, REFERENCE_DISTANCE)
    distance = min(distance, MAX_DISTANCE)
    gain = REFERENCE_DISTANCE / (REFERENCE_DISTANCE + ROLLOFF_FACTOR * (distance – REFERENCE_DISTANCE))
  • distanceModel="LINEAR"
    distance = min(distance, MAX_DISTANCE) // avoid negative gain
    gain = (1 – ROLLOFF_FACTOR * (distance – REFERENCE_DISTANCE) / (MAX_DISTANCE – REFERENCE_DISTANCE))
  • distanceModel="LINEAR_CLAMPED"
    distance = max(distance, REFERENCE_DISTANCE)
    distance = min(distance, MAX_DISTANCE)
    gain = (1 – ROLLOFF_FACTOR * (distance – REFERENCE_DISTANCE) / (MAX_DISTANCE – REFERENCE_DISTANCE))
  • distanceModel="EXPONENT"
    gain = (distance / REFERENCE_DISTANCE) ^ (- ROLLOFF_FACTOR)
  • distanceModel="EXPONENT_CLAMPED"
    distance = max(distance, REFERENCE_DISTANCE)
    distance = min(distance, MAX_DISTANCE)
    gain = (distance / REFERENCE_DISTANCE) ^ (- ROLLOFF_FACTOR)


Table members

Inherited


Murl.Graph.IStateSlot

Methods


GetNodeInterface()

Get the constant INode interface. This method returns a constant pointer to the node's INode interface, to be able to query common node properties such as active state, visibility or ID.

Murl.Graph.INode GetNodeInterface()

Returns
Murl.Graph.INode The constant INode interface, or null if not available

GetSubjectInterface()

Get the constant ISubject interface. This method returns a constant pointer to the node's ISubject interface, to be able to query subject properties such as world transform, viewing matrix, projection matrix etc.

Murl.Graph.ISubject GetSubjectInterface()

Returns
Murl.Graph.ISubject The mutable ISubject interface, or null if not available

GetViewNodeTarget()

Get the constant IViewNodeTarget container. This method returns a constant pointer to the node's IViewNodeTarget container, which allows to query the view object the listener is attached to.

Murl.Graph.IGenericNodeTarget.GraphIView GetViewNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphIView The constant IViewNodeTarget container, or null if not available

SetVolume(volume)

Set the listener's volume (gain).

Boolean SetVolume(Number volume)

Parameters
volumeThe overall volume.
Returns
Boolean true if successful.

GetVolume()

Get the listener's volume (gain).

Number GetVolume()

Returns
Number The overall volume.

SetMaxDistance(maxDistance)

Set the maximum hearing distance.

Boolean SetMaxDistance(Number maxDistance)

Parameters
maxDistanceThe maximum distance.
Returns
Boolean true if successful.

GetMaxDistance()

Get the maximum hearing distance.

Number GetMaxDistance()

Returns
Number The maximum distance.

SetDistanceModel(distanceModel)

Set the listener's distance model used for attenuation calculation.

Boolean SetDistanceModel(Murl.IEnums.DistanceModel distanceModel)

Parameters
distanceModelThe distance model to use.
Returns
Boolean true if successful.

GetDistanceModel()

Get the listener's distance model used for attenuation calculation.

Murl.IEnums.DistanceModel GetDistanceModel()

Returns
Murl.IEnums.DistanceModel The distance model used.

GetNumberOfStages()

Get the listener's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.