Animation

Layer Animation

Introduction

When updating a layer, you can optionally choose to animate the update to the new value. This is currently supported for:

• width
• height
• x
• y
• opacity
• scale
• rotation

When updating a layer, you can include the requestAnimation property, which is an array of animations that will apply for this update only. You can choose to animate different properties for different amounts of time. All animations are applied at the same time, however delayMs can be used to offset specific property changes.

import { ApiStream } from '@api.stream/sdk';
const api = new ApiStream();

await api.LayoutApi().layer.updateLayer({
    layer: {
        x: 100,
        y: 100,
        opacity: 1,
        requestAnimation: [
            {
                properties: ["x", "y"],
                durationMs: 1000
            },
            {
                properties: ["opacity"],
                durationMs: 500,
                delayMs: 500
            }
        ]
    },
    layerId: 1,
    layoutId: A_LAYOUT_ID,
});

Wildcards

If you want to target an animation to any change to the layer, you can use a wildcard as the property:

note

When multiple request animations are defined and properties overlap, the final matching animation will be used. For example if the first animation targets ['*'] but the second targets ['x'], only the second animation applied for x.

{
    /* normal layer */
    "x": 100,
    "y": 100,
    "opacity": 1,
    "requestAnimation": [
        {
            "properties": ["*"], // this will target x, y and opacity
            "durationMs": 1000
        }
        {
            "properties": ["opacity"], // since opacity is defined last, the wildcard will be ignored for opacity.
            "durationMs": 500
        }
    ]
}

Batching animations

Animations can also be used in a batch request to make multiple updates that are synchronized. Within animations you can also delay the animation, allowing you to interact with multiple layers in sequence. All animations are queued from the time the request is received by the compositor.

import { ApiStream } from '@api.stream/sdk';
const api = new ApiStream();

const layer = await api.LayoutApi().layer.batch({
    layers: [
        // Create the a base layer using a web page.
        { 
            update: { 
                id: 1, // Animate the first layers opacity out.
                opacity: 0,
                requestAnimation: [{
                    properties: ["*"],
                    durationMs: 1000
                }],
            }
        },
        { 
            update: { 
                id: 2, // Animate the second layers opacity in after 1 second.
                opacity: 1, 
                requestAnimation: [{
                    properties: ["*"],
                    durationMs: 1000,
                    delayMs: 1000, // the delay!
                }],
            }
        },
    ],
    layoutId: A_LAYOUT_ID,
});