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

Playable.

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

Usage

Attach the instance to an existing object and set a filled buffer to it. In order to reflect transformation changes from the scene in the spatial audio, the playable should be added to some PlayableGroup, which is periodically updated from a currently active Listener using Listener::update():

Scene3D scene;
Object3D object{&scene};
Audio::Buffer buffer;

// ...
Audio::Listener3D listener{scene};
Audio::PlayableGroup3D group;

/* Attach the playable to an object and configure its source */
Audio::Playable3D playable{object, &group};
playable.source()
    .setBuffer(&buffer)
    .setLooping(true)
    .play();

// ...

// every frame, adapt the listener and all playables to changes in scene
// transformation
listener.update({group, someOtherGroup});

Note that Source::setPosition(), Source::setDirection() and Source::setGain() called on source() will be overwritten on next call to Listener::update() / PlayableGroup::setGain() / setGain() and you have to use other means to update them:

Base classes

template<UnsignedInt dimensions, class Derived, class T>
class Magnum::SceneGraph::AbstractGroupedFeature
Base for grouped features.

Constructors, destructors, conversion operators

Playable(SceneGraph::AbstractObject<dimensions, Float>& object, PlayableGroup<dimensions>* group = nullptr) explicit
Construct a playable with omnidirectional source.
Playable(SceneGraph::AbstractObject<dimensions, Float>& object, const VectorTypeFor<dimensions, Float>& direction, PlayableGroup<dimensions>* group = nullptr) explicit
Construct a playable with directional source.

Public functions

auto source() -> Source&
Source which is managed by this feature.
auto gain() const -> Float
Gain.
auto setGain(const Float gain) -> Playable&
Set gain of the playable and source respecting the PlayableGroups gain.
auto playables() -> PlayableGroup<dimensions>*
Group containing this playable.
auto playables() const -> const PlayableGroup<dimensions>*

Private functions

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

Function documentation

template<UnsignedInt dimensions>
Magnum::Audio::Playable<dimensions>::Playable(SceneGraph::AbstractObject<dimensions, Float>& object, PlayableGroup<dimensions>* group = nullptr) explicit

Construct a playable with omnidirectional source.

Parameters
object Object this playable belongs to
group Group this playable belongs to

Creates a source with a zero direction vector. See Playable(SceneGraph::AbstractObject<dimensions, Float>&, const VectorTypeFor<dimensions, Float>&, PlayableGroup<dimensions>*) for an alternative.

template<UnsignedInt dimensions>
Magnum::Audio::Playable<dimensions>::Playable(SceneGraph::AbstractObject<dimensions, Float>& object, const VectorTypeFor<dimensions, Float>& direction, PlayableGroup<dimensions>* group = nullptr) explicit

Construct a playable with directional source.

Parameters
object Object this playable belongs to
direction Source direction
group Group this playable belongs to

Uses direction as a base for Source::setDirection(). Passing a zero vector is equivalent to calling Playable(SceneGraph::AbstractObject<dimensions, Float>&, PlayableGroup<dimensions>*).

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

Set gain of the playable and source respecting the PlayableGroups gain.

Returns Reference to self (for method chaining)

The source gain is calculated as sourceGain = playableGain*groupGain. Default is 1.0f.

template<UnsignedInt dimensions>
PlayableGroup<dimensions>* Magnum::Audio::Playable<dimensions>::playables()

Group containing this playable.

If the playable doesn't belong to any group, returns nullptr.

template<UnsignedInt dimensions>
const PlayableGroup<dimensions>* Magnum::Audio::Playable<dimensions>::playables() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions>
void Magnum::Audio::Playable<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.