diff --git a/doc/changelog.dox b/doc/changelog.dox index b2698790c..02ead06db 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -57,6 +57,10 @@ See also: @subsection changelog-latest-changes Changes and improvements +@subsubsection changelog-latest-changes-audio Audio library + +- Ability to specify initial source direction using @ref Audio::Playable::Playable(SceneGraph::AbstractObject&, const VectorTypeFor&, PlayableGroup*) + @subsubsection changelog-latest-changes-gl GL library - To prevent nothing being rendered by accident, @ref GL::Mesh::setCount() @@ -110,6 +114,12 @@ See also: @ref Trade::MeshData2D / @ref Trade::MeshData3D and directly returning a @ref GL::Mesh instead +@subsection changelog-latest-compatibility Potential compatibility breakages, removed APIs + +- @ref Audio::Playable is now by default omnidirectional instead of having + source in direction of negative Z axis (the direction has effect only when + setting inner and outer cone properties of @ref Audio::Source). + @section changelog-2018-04 2018.04 Released 2018-05-01, tagged as diff --git a/src/Magnum/Audio/Playable.cpp b/src/Magnum/Audio/Playable.cpp index 38337c4bc..57cd6c285 100644 --- a/src/Magnum/Audio/Playable.cpp +++ b/src/Magnum/Audio/Playable.cpp @@ -32,9 +32,8 @@ namespace Magnum { namespace Audio { -template Playable::Playable(SceneGraph::AbstractObject& object, PlayableGroup* group): SceneGraph::AbstractGroupedFeature, Float>(object, group), _fwd{}, _gain{1.0f} { +template Playable::Playable(SceneGraph::AbstractObject& object, const VectorTypeFor& direction, PlayableGroup* group): SceneGraph::AbstractGroupedFeature, Float>(object, group), _direction{direction}, _gain{1.0f} { SceneGraph::AbstractFeature::setCachedTransformations(SceneGraph::CachedTransformation::Absolute); - _fwd[dimensions - 1] = -1; } template Playable::~Playable() = default; @@ -51,7 +50,7 @@ template void Playable::clean(const MatrixTy position = playables()->soundTransformation().transformVector(position); _source.setPosition(position); - _source.setDirection(Vector3::pad(absoluteTransformationMatrix.rotation()*_fwd)); + _source.setDirection(Vector3::pad(absoluteTransformationMatrix.rotation()*_direction)); /** @todo velocity */ } diff --git a/src/Magnum/Audio/Playable.h b/src/Magnum/Audio/Playable.h index ff14f0a9f..52af36d91 100644 --- a/src/Magnum/Audio/Playable.h +++ b/src/Magnum/Audio/Playable.h @@ -47,27 +47,57 @@ an @ref SceneGraph::Object. 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 @ref PlayableGroup, which is periodically -updated from a currently active @link Listener @endlink: +updated from a currently active @ref Listener using @ref Listener::update(): @snippet MagnumAudio-scenegraph.cpp Playable-usage -@see @ref Playable2D, @ref Playable3D, @ref Source +Note that @ref Source::setPosition(), @ref Source::setDirection() and +@ref Source::setGain() called on @ref source() will be overwritten on next call +to @ref Listener::update() / @ref PlayableGroup::setGain() / @ref setGain() and +you have to use other means to update them: + +- Transformation of the source is inherited from the scene. If you want to + transform it, transform the @ref SceneGraph::Object the playable is + attached to. It's also possible to affect the global listener + and group transformation using @ref Listener::setSoundTransformation() and + @ref PlayableGroup::setSoundTransformation() +- The source is by default omnidirectional (i.e., passing a zero vector to + @ref Source::setDirection()). You can set the initial direction using the + @ref Playable(SceneGraph::AbstractObject&, const VectorTypeFor&, PlayableGroup*) + constructor, the direction will be automatically rotated based on playable + transformation. +- Source gain is set as a combination of @ref PlayableGroup gain and + @ref Playable gain and updated on every call to @ref setGain() or + @ref PlayableGroup::setGain(). + +@see @ref Playable2D, @ref Playable3D */ template class Playable: public SceneGraph::AbstractGroupedFeature, Float> { public: /** - * @brief Constructor + * @brief Construct a playable with omnidirectional source. * @param object Object this playable belongs to * @param group Group this playable belongs to * - * Creates playable with a source and a forward vector of - * @cpp {0.0f, -1.0f} @ce for 2D and @cpp {0.0f, 0.0f, -1.0f} @ce for - * 3D scenes. This forward vector cannot be changed, the sources - * orientation and translation can be instead affected by @p object or - * via @ref PlayableGroup::setSoundTransformation(). + * Creates a source with a zero direction vector. See + * @ref Playable(SceneGraph::AbstractObject&, const VectorTypeFor&, PlayableGroup*) + * for an alternative. * @see @ref setGain(), @ref PlayableGroup::add() */ - explicit Playable(SceneGraph::AbstractObject& object, PlayableGroup* group = nullptr); + explicit Playable(SceneGraph::AbstractObject& object, PlayableGroup* group = nullptr): Playable{object, {}, group} {} + + /** + * @brief Construct a playable with directional source. + * @param object Object this playable belongs to + * @param direction Source direction + * @param group Group this playable belongs to + * + * Uses @p direction as a base for @ref Source::setDirection(). Passing + * a zero vector is equivalent to calling + * @ref Playable(SceneGraph::AbstractObject&, PlayableGroup*). + * @see @ref setGain(), @ref PlayableGroup::add() + */ + explicit Playable(SceneGraph::AbstractObject& object, const VectorTypeFor& direction, PlayableGroup* group = nullptr); ~Playable(); @@ -81,8 +111,8 @@ template class Playable: public SceneGraph::AbstractGrou * @brief Set gain of the playable and source respecting the PlayableGroups gain * @return Reference to self (for method chaining) * - * The sources gain is computed as @cpp sourceGain = playableGain*groupGain @ce. - * Default for the playables gain is @cpp 1.0f @ce. + * The source gain is calculated as + * @cpp sourceGain = playableGain*groupGain @ce. Default is @cpp 1.0f @ce. * @see @ref PlayableGroup::setGain(), @ref Source::setGain() */ Playable& setGain(const Float gain); @@ -106,7 +136,7 @@ template class Playable: public SceneGraph::AbstractGrou PlayableGroup::setGain() */ MAGNUM_AUDIO_LOCAL void cleanGain(); - VectorTypeFor _fwd; + VectorTypeFor _direction; Float _gain; Source _source; };