Magnum::Ui::BaseLayerStyleAnimator class new in Git master

#include <Magnum/Ui/BaseLayerAnimator.h>

Setting up an animator instance

The animator doesn't have any shared state or configuration, so it's just about constructing it from a fresh AbstractUserInterface::createAnimator() handle and passing it to setStyleAnimatorInstance().

Ui::BaseLayerStyleAnimator& animator = ui.setStyleAnimatorInstance(
    Containers::pointer<Ui::BaseLayerStyleAnimator>(ui.createAnimator()));

After that, the animator has to be registered with a concrete layer instance. The animations make use of dynamic styles, so the base layer is expected to have at least one dynamic style enabled with BaseLayer::Shared::Configuration::setDynamicStyleCount(). The more dynamic styles are enabled, the more style animations can be running for given layer at the same time, but also more data need to get uploaded to the GPU every frame. Finally, call BaseLayer::assignAnimator(BaseLayerStyleAnimator&) to assign the animator to the layer instance. Then, assuming AbstractUserInterface::advanceAnimations() is called in an appropriate place, the animator is ready to use.

Ui::BaseLayerGL::Shared baseLayerShared{
    Ui::BaseLayer::Shared::Configuration{…}
        …
        .setDynamicStyleCount(10) /* adjust as needed */
};
Ui::BaseLayer& baseLayer = ui.setLayerInstance(
    Containers::pointer<Ui::BaseLayerGL>(ui.createLayer(), baseLayerShared));

…

baseLayer.assignAnimator(animator);

Unlike builtin layers or layouters, the default UserInterface implementation doesn't implicitly provide a BaseLayerStyleAnimator instance.

Creating animations

Assuming an enum is used to index the styles defined in BaseLayer::Shared of the associated layer instance, an animation is created by calling create() with the source and target style indices, an easing function from Animation::Easing or a custom one, time at which it's meant to be played, its duration, and a DataHandle which the style animation should affect. Here, for example, to fade out a button hover style over half a second:

enum class BaseLayerStyle {
    …
    Button,
    ButtonHover,
    …
};

Ui::DataHandle buttonBackground = …;

animator.create(BaseLayerStyle::ButtonHover, BaseLayerStyle::Button,
    Animation::Easing::cubicOut, now, 0.5_sec, buttonBackground);

Internally, once the animation starts playing, the animator allocates a new dynamic style index using BaseLayer::allocateDynamicStyle() and switches the style index of given DataHandle to the allocated dynamic style with BaseLayer::setStyle(). During the animation the style data are updated to corresponding interpolation between the source and target styles, equivalent to calling BaseLayer::setDynamicStyle(). When the animation stops, the data style index is switched to the target ID specified in create() and the dynamic style index is recycled with BaseLayer::recycleDynamicStyle() is called for the dynamic style.

If the animator runs out of dynamic styles, newly played animations are left at the source style index until another dynamic style is recycled. If no dynamic style gets recycled until the animation ends, the data gets switched directly to the target style without animating.

The animation interpolates all properties of BaseLayerStyleUniform including outline width and corner radius, as well as the style padding value. At the moment, only animation between predefined styles is possible.

Animation lifetime and data attachment

As with all other animations, they're implicitly removed once they're played. Pass AnimationFlag::KeepOncePlayed to create() or addFlags() to disable this behavior.

Style animations are associated with data they animate, and thus as soon as the data or node the data is attached to is removed, the animation gets removed as well. If you want to preserve the animation when the data is removed, call attach(AnimationHandle, DataHandle) with DataHandle::Null to detach it from the data before removing.

If you call create() with DataHandle::Null, the animation will still allocate and interpolate a dynamic style, but the style won't be used anywhere. You can then retrieve the dynamic style index with dynamicStyle() and use it for example to make the same style animation on multiple different data. Note that in this case you're also responsible also for switching to the target style once the animation finishes — once the dynamic style is recycled, the same index may get used for arbitrary other style either by this animator or any other code, causing visual bugs.

Base classes

class AbstractVisualLayerStyleAnimator new in Git master

Base for AbstractVisualLayer style animators.

Constructors, destructors, conversion operators

BaseLayerStyleAnimator(AnimatorHandle handle) explicit

Constructor.

BaseLayerStyleAnimator(const AbstractStyleAnimator&) deleted

Copying is not allowed.

BaseLayerStyleAnimator(BaseLayerStyleAnimator&&) noexcept

Move constructor.

Public functions

auto operator=(const BaseLayerStyleAnimator&) -> BaseLayerStyleAnimator& deleted

Copying is not allowed.

auto operator=(BaseLayerStyleAnimator&&) -> BaseLayerStyleAnimator& noexcept

Move assignment.

auto create(UnsignedInt sourceStyle, UnsignedInt targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, DataHandle data, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle

Create an animation.

template<class StyleIndex>

auto create(StyleIndex sourceStyle, StyleIndex targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, DataHandle data, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle

Create an animation with a style index in a concrete enum type.

auto create(UnsignedInt sourceStyle, UnsignedInt targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, DataHandle data, AnimationFlags flags) -> AnimationHandle

Create an animation.

template<class StyleIndex>

auto create(StyleIndex sourceStyle, StyleIndex targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, DataHandle data, AnimationFlags flags) -> AnimationHandle

Create an animation with a style index in a concrete enum type.

auto create(UnsignedInt sourceStyle, UnsignedInt targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, LayerDataHandle data, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle

Create an animation assuming the data it's attached to belongs to the layer the animator is registered with.

template<class StyleIndex>

auto create(StyleIndex sourceStyle, StyleIndex targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, LayerDataHandle data, UnsignedInt repeatCount = 1, AnimationFlags flags = {}) -> AnimationHandle

Create an animation with a style index in a concrete enum type assuming the data it's attached to belongs to the layer the animator is registered with.

auto create(UnsignedInt sourceStyle, UnsignedInt targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, LayerDataHandle data, AnimationFlags flags) -> AnimationHandle

Create an animation assuming the data it's attached to belongs to the layer the animator is registered with.

template<class StyleIndex>

auto create(StyleIndex sourceStyle, StyleIndex targetStyle, Float(*)(Float) easing, Nanoseconds played, Nanoseconds duration, LayerDataHandle data, AnimationFlags flags) -> AnimationHandle

Create an animation with a style index in a concrete enum type assuming the data it's attached to belongs to the layer the animator is registered with.

void remove(AnimationHandle handle)

Remove an animation.

void remove(AnimatorDataHandle handle)

Remove an animation assuming it belongs to this animator.

auto easing(AnimationHandle handle) -> auto

Animation easing function.

auto easing(AnimatorDataHandle handle) -> auto

Animation easing function assuming it belongs to this animator.

auto uniforms(AnimationHandle handle) const -> Containers::Pair<BaseLayerStyleUniform, BaseLayerStyleUniform>

Animation source and target uniforms.

auto uniforms(AnimatorDataHandle handle) const -> Containers::Pair<BaseLayerStyleUniform, BaseLayerStyleUniform>

Animation source and target uniforms assuming it belongs to this animator.

auto paddings(AnimationHandle handle) const -> Containers::Pair<Vector4, Vector4>

Animation source and target paddings.

auto paddings(AnimatorDataHandle handle) const -> Containers::Pair<Vector4, Vector4>

Animation source and target paddings assuming it belongs to this animator.

auto advance(Containers::BitArrayView active, const Containers::StridedArrayView1D<const Float>& factors, Containers::BitArrayView remove, Containers::ArrayView<BaseLayerStyleUniform> dynamicStyleUniforms, const Containers::StridedArrayView1D<Vector4>& dynamicStylePaddings, const Containers::StridedArrayView1D<UnsignedInt>& dataStyles) -> BaseLayerStyleAnimations

Advance the animations.

Function documentation