template<UnsignedInt dimensions>
Magnum::Audio::Listener class

Listener.

Contents

Feature which manages the position, orientation and gain of the OpenAL listener for an SceneGraph::Object.

Usage

Minimal scene setup for a Listener3D will require the following code:

Scene3D scene;
Object3D object{&scene};
Listener3D listener{object};

// ... every frame, update the listener to changes in object transformation:
listener.update({});

For two dimensional scenes simply replace all 3D with 2D.

Using Listener with PlayableGroup

When using PlayableGroup, you can update the listener and groups as follows:

// ...
Listener3D listener{object};
PlayableGroup3D group1, group2;

// ... and every frame:
listener.update({group1, group2});

Active listener

There can only be at the most one active listener at a given time, i.e. the one on which Listener::update() was called last. This is because OpenAL only supports notion of one listener. Having multiple Listener2D or Listener3D instances can still be useful for conveniently switching between them for cinematics for example.

AbstractObject::setClean() will not affect inactive listeners.

Sound transformation

Listener::setSoundTransformation() enables you to set a transformation matrix which is applied to the listeners orientation and position before passed onto OpenAL. This can be used for rotating two dimensional scenes as planes into the three dimensional audio space or even scaling the audio scene to match a certain world scale. In the later case you might want to instead consider Renderer::setSpeedOfSound().

Base classes

template<UnsignedInt dimensions, class T>
class Magnum::SceneGraph::AbstractFeature
Base for object features.

Constructors, destructors, conversion operators

Listener(SceneGraph::AbstractObject<dimensions, Float>& object) explicit
Constructor.

Public functions

auto soundTransformation() const -> const Matrix4&
Sound transformation.
auto setSoundTransformation(const Matrix4& soundTransformation) -> Listener<dimensions>&
Set sound transformation.
void update(std::initializer_list<std::reference_wrapper<PlayableGroup<dimensions>>> groups)
Update the listener.
auto gain() const -> Float
Listener gain.
auto setGain(Float gain) -> Listener<dimensions>&
Set listener gain.
auto isActive() const -> bool
Whether this listener is the active listener.

Private functions

void clean(const MatrixTypeFor<dimensions, Float>& absoluteTransformationMatrix) override virtual
Clean data based on absolute transformation.

Function documentation

template<UnsignedInt dimensions>
Magnum::Audio::Listener<dimensions>::Listener(SceneGraph::AbstractObject<dimensions, Float>& object) explicit

Constructor.

Parameters
object Object this listener belongs to

Creates a listener with a forward vector of {0.0f, 0.0f, -1.0f} and up vector of {0.0f, 1.0f, 0.0f}. These vectors cannot be changed, the listeners orientation and translation can be instead affected by object or via Listener::setSoundTransformation().

template<UnsignedInt dimensions>
Listener<dimensions>& Magnum::Audio::Listener<dimensions>::setSoundTransformation(const Matrix4& soundTransformation)

Set sound transformation.

Parameters
soundTransformation Transformation for transforming from world to listener space
Returns Reference to self (for method chaining)

template<UnsignedInt dimensions>
void Magnum::Audio::Listener<dimensions>::update(std::initializer_list<std::reference_wrapper<PlayableGroup<dimensions>>> groups)

Update the listener.

Parameters
groups Groups to update

Makes this Listener the active listener and calls SceneGraph::AbstractObject::setClean() on its parent object and all objects of the Playable s in the group. Updates listene related configuration for Renderer (position, orientation, gain).

template<UnsignedInt dimensions>
Listener<dimensions>& Magnum::Audio::Listener<dimensions>::setGain(Float gain)

Set listener gain.

Parameters
gain Gain
Returns Reference to self (for method chaining)

template<UnsignedInt dimensions>
void Magnum::Audio::Listener<dimensions>::clean(const MatrixTypeFor<dimensions, Float>& absoluteTransformationMatrix) override virtual private

Clean data based on absolute transformation.

When object is cleaned and CachedTransformation::Absolute is enabled in setCachedTransformations(), this function is called to recalculate data based on absolute object transformation.

Default implementation does nothing.