#include <Magnum/Audio/Listener.h>
template<UnsignedInt dimensions>
Magnum::Audio::Listener class

Listener.

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

Usage

The listener will be commonly used together with a bunch of Playable features, managed in one or more PlayableGroup instances. In order to reflect transformation changes affecting the scene, you need to call update() after each change (or simply every frame):

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

// ...

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

For two-dimensional scenes simply replace all 3D with 2D. See Playable for more info about how to set up and group audio sources.

Active listener

There can only be at 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.

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<dimensions, Float>
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<Containers::Reference<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.

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 default orientation (i.e., forward vector is {0.0f, 0.0f, -1.0f} and up vector of {0.0f, 1.0f, 0.0f}). You can change this orientation by transforming the object this listener is attached to or via Listener::setSoundTransformation().

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

Set sound transformation.

Returns Reference to self (for method chaining)

Global transformation for transforming from world to listener space.

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

Update the listener.

Parameters
groups Groups to update

Makes this instance the active listener and calls SceneGraph::AbstractObject::setClean() on its parent object and all objects of the Playables in the group to reflect transformation changes to spatial audio behavior. Also updates listener-related configuration for Renderer (position, orientation, gain).

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

Set listener gain.

Returns Reference to self (for method chaining)

Default is 1.0f (i.e., not affecting the global gain in any way).