Edit Animations - macOS

import Foundation
import IMGLYEngine

@MainActor
func editAnimations(engine: Engine) async throws {
  let scene = try engine.scene.createVideo()

  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 800)
  try engine.block.setHeight(page, value: 600)
  try engine.block.appendChild(to: scene, child: page)

  try await engine.scene.zoom(to: page, paddingLeft: 40, paddingTop: 40, paddingRight: 40, paddingBottom: 40)

  let block = try engine.block.create(.graphic)
  try engine.block.setShape(block, shape: engine.block.createShape(.rect))
  try engine.block.setPositionX(block, value: 100)
  try engine.block.setPositionY(block, value: 50)
  try engine.block.setWidth(block, value: 300)
  try engine.block.setHeight(block, value: 300)
  try engine.block.appendChild(to: page, child: block)
  let fill = try engine.block.createFill(.image)
  try engine.block.setString(
    fill,
    property: "fill/image/imageFileURI",
    value: "https://img.ly/static/ubq_samples/sample_1.jpg",
  )
  try engine.block.setFill(block, fill: fill)

  let slideAnimation = try engine.block.createAnimation(.slide)
  try engine.block.setInAnimation(block, animation: slideAnimation)
  try engine.block.setDuration(slideAnimation, duration: 1.0)

  let fadeOutAnimation = try engine.block.createAnimation(.fade)
  try engine.block.setOutAnimation(block, animation: fadeOutAnimation)

  let breathingLoop = try engine.block.createAnimation(.breathingLoop)
  try engine.block.setLoopAnimation(block, animation: breathingLoop)

  let inAnimation = try engine.block.getInAnimation(block)
  let outAnimation = try engine.block.getOutAnimation(block)
  let loopAnimation = try engine.block.getLoopAnimation(block)
  let inType = try engine.block.getType(inAnimation)
  let outType = try engine.block.getType(outAnimation)

  let currentDuration = try engine.block.getDuration(inAnimation)
  let currentEasing = try engine.block.getEnum(inAnimation, property: "animationEasing")
  let allProperties = try engine.block.findAllProperties(inAnimation)

  try engine.block.setDuration(inAnimation, duration: 0.8)
  try engine.block.setDuration(loopAnimation, duration: 2.0)

  try engine.block.setEnum(inAnimation, property: "animationEasing", value: "EaseOut")
  let easingOptions = try engine.block.getEnumValues(ofProperty: "animationEasing")

  try engine.block.setFloat(
    inAnimation,
    property: "animation/slide/direction",
    value: .pi,
  )
  let direction = try engine.block.getFloat(inAnimation, property: "animation/slide/direction")

  let currentIn = try engine.block.getInAnimation(block)
  try engine.block.destroy(currentIn)
  let zoomAnimation = try engine.block.createAnimation(.zoom)
  try engine.block.setInAnimation(block, animation: zoomAnimation)
  try engine.block.setDuration(zoomAnimation, duration: 0.6)
  try engine.block.setEnum(zoomAnimation, property: "animationEasing", value: "EaseInOut")

  let currentLoop = try engine.block.getLoopAnimation(block)
  try engine.block.destroy(currentLoop)
  // Destroying a design block also destroys all its attached animations
  // try engine.block.destroy(block)
}

Modify existing animations by reading properties, changing duration and easing, and replacing or removing animations from blocks.

5 mins

estimated time

GitHub

Editing animations in CE.SDK involves retrieving existing animations from blocks and modifying their properties. This guide assumes you’ve already created and attached animations to blocks as covered in the Base Animations guide.

This guide covers retrieving animations, reading and modifying properties, changing easing functions, adjusting animation-specific settings, and replacing or removing animations.

Retrieving Animations#

Before modifying an animation, retrieve it from the block using getInAnimation, getOutAnimation, or getLoopAnimation. We use getType to identify the animation type.

let inAnimation = try engine.block.getInAnimation(block)
let outAnimation = try engine.block.getOutAnimation(block)
let loopAnimation = try engine.block.getLoopAnimation(block)
let inType = try engine.block.getType(inAnimation)
let outType = try engine.block.getType(outAnimation)

Reading Animation Properties#

Inspect current animation settings using property getters. getDuration returns the animation length in seconds, while getEnum retrieves values like easing functions. Use findAllProperties to discover all configurable properties for an animation.

let currentDuration = try engine.block.getDuration(inAnimation)
let currentEasing = try engine.block.getEnum(inAnimation, property: "animationEasing")
let allProperties = try engine.block.findAllProperties(inAnimation)

Different animation types expose different properties — slide animations have direction, while loop animations may have intensity or scale properties.

Modifying Animation Duration#

Change animation timing with setDuration. The duration is specified in seconds.

try engine.block.setDuration(inAnimation, duration: 0.8)
try engine.block.setDuration(loopAnimation, duration: 2.0)

When modifying In or Out animation durations, CE.SDK automatically adjusts the paired animation to prevent overlap. For loop animations, the duration defines the cycle length.

Changing Easing Functions#

Easing controls animation acceleration. We use setEnum with the "animationEasing" property to change it.

try engine.block.setEnum(inAnimation, property: "animationEasing", value: "EaseOut")
let easingOptions = try engine.block.getEnumValues(ofProperty: "animationEasing")

Use getEnumValues(ofProperty: "animationEasing") to discover available options:

Easing	Description
`Linear`	Constant speed throughout
`EaseIn`	Starts slow, accelerates toward the end
`EaseOut`	Starts fast, decelerates toward the end
`EaseInOut`	Starts slow, speeds up, then slows down again

Adjusting Animation-Specific Properties#

Each animation type has unique configurable properties. For slide animations, we can change the entry direction using setFloat.

try engine.block.setFloat(
  inAnimation,
  property: "animation/slide/direction",
  value: .pi,
)
let direction = try engine.block.getFloat(inAnimation, property: "animation/slide/direction")

For a full list of direction values and other animation-specific properties, see Supported Animation Types.

Replacing Animations#

To swap an animation type, destroy the existing animation before setting a new one. This prevents memory leaks from orphaned animation objects.

let currentIn = try engine.block.getInAnimation(block)
try engine.block.destroy(currentIn)
let zoomAnimation = try engine.block.createAnimation(.zoom)
try engine.block.setInAnimation(block, animation: zoomAnimation)
try engine.block.setDuration(zoomAnimation, duration: 0.6)
try engine.block.setEnum(zoomAnimation, property: "animationEasing", value: "EaseInOut")

Removing Animations#

Remove an animation by destroying it with destroy.

let currentLoop = try engine.block.getLoopAnimation(block)
try engine.block.destroy(currentLoop)
// Destroying a design block also destroys all its attached animations
// try engine.block.destroy(block)

Destroying a design block automatically destroys all its attached animations. However, detached animations must be destroyed manually to free memory.

API Reference#

Method	Description
`engine.block.getInAnimation(block)`	Get entrance animation ID
`engine.block.getOutAnimation(block)`	Get exit animation ID
`engine.block.getLoopAnimation(block)`	Get loop animation ID
`engine.block.getType(anim)`	Get animation type string
`engine.block.getDuration(anim)`	Get animation duration in seconds
`engine.block.setDuration(anim, duration:)`	Set animation duration
`engine.block.getEnum(anim, property:)`	Get enum property value
`engine.block.setEnum(anim, property:, value:)`	Set enum property value
`engine.block.getFloat(anim, property:)`	Get float property value
`engine.block.setFloat(anim, property:, value:)`	Set float property value
`engine.block.findAllProperties(anim)`	Get all available properties
`engine.block.getEnumValues(ofProperty:)`	Get available values for enum property
`engine.block.destroy(anim)`	Destroy animation and free memory

Next Steps#

Base Animations — Create entrance, exit, and loop animations
Text Animations — Animate text with writing styles and character control
Animation Overview — Understand animation concepts and capabilities