Motion Blur - Mac Catalyst

import Foundation
import IMGLYEngine

@MainActor
func motionBlur(engine: Engine) async throws {
  let scene = try engine.scene.create()
  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 1920)
  try engine.block.setHeight(page, value: 1080)
  try engine.block.appendChild(to: scene, child: page)
  try engine.block.setDuration(page, duration: 2)

  // A square that crosses the page in one second. Motion blur needs motion.
  let block = try engine.block.create(.graphic)
  try engine.block.setShape(block, shape: engine.block.createShape(.rect))
  let fill = try engine.block.createFill(.color)
  try engine.block.setColor(fill, property: "fill/color/value", color: .rgba(r: 0.9, g: 0.2, b: 0.4, a: 1))
  try engine.block.setFill(block, fill: fill)
  try engine.block.setWidth(block, value: 300)
  try engine.block.setHeight(block, value: 300)
  try engine.block.setPositionY(block, value: 390)
  try engine.block.appendChild(to: page, child: block)
  try engine.block.setDuration(block, duration: 2)

  try engine.block.setKeyframes(block, property: "position/x", keyframes: [
    Keyframe(time: 0, value: .float(100)),
    Keyframe(time: 0.5, value: .float(1520)),
    Keyframe(time: 1, value: .float(100)),
  ])

  // Blur the block while it moves
  try engine.block.setBool(block, property: "motionBlur/enabled", value: true)
  print(try engine.block.getBool(block, property: "motionBlur/enabled")) // true

  // Graphic, text and caption blocks have the property. Pages do not.
  let blockHasMotionBlur = try engine.block.findAllProperties(block).contains("motionBlur/enabled")
  let pageHasMotionBlur = try engine.block.findAllProperties(page).contains("motionBlur/enabled")
  print(blockHasMotionBlur, pageHasMotionBlur) // true false

  // The scene holds the shutter for all blocks with motion blur.
  // 360 degrees keeps the shutter open for one full frame.
  try engine.block.setFloat(scene, property: "motionBlur/shutterAngle", value: 360)
  // -180 degrees, half the angle, centers the shutter on the frame time
  try engine.block.setFloat(scene, property: "motionBlur/shutterPhase", value: -180)

  // More samples give a smoother trail and take longer to render
  try engine.block.setInt(scene, property: "motionBlur/samples", value: 32)
  print(try engine.block.getInt(scene, property: "motionBlur/samples")) // 32

  // One frame of the scene frame rate is the span the shutter angle refers to
  try engine.block.setFloat(scene, property: "scene/frameRate", value: 30)

  // The preview draws the motion blur by default.
  // Set the value to false to show the blocks sharp while editing.
  try engine.editor.setSettingBool("features/previewMotionBlurEnabled", value: false)
  print(try engine.editor.getSettingBool("features/previewMotionBlurEnabled")) // false

  do {
    try engine.block.setInt(scene, property: "motionBlur/samples", value: 100)
  } catch let error as EngineError {
    print(error.catalogCode == .blockMotionBlurValueOutOfRange) // true
  }

  // Image export draws no motion blur. Export a video to see it in a file.
  let stream = try await engine.block.exportVideo(page, mimeType: .mp4)
  for try await event in stream {
    if case let .finished(video: video) = event {
      try video.write(to: FileManager.default.temporaryDirectory.appendingPathComponent("motion-blur.mp4"))
    }
  }
}

Blur moving blocks in exported videos and in the preview, as a camera shutter does.

6 mins

estimated time

GitHub

Motion blur smears a moving block along its path during one frame. A block with motion blur draws the average of several samples over the time that the shutter stays open. The blur renders in video export and in the preview. The editor has no motion blur control, so you set it with the block API.

This guide covers how to turn motion blur on for a block, how to tune the shutter and the samples of the scene, how the frame rate sets the length of the blur, the preview blur and its setting, and video export.

Animating the Block#

Motion blur needs motion. A block blurs only while something moves it during the shutter: keyframes, a preset animation, the motion of its group, or a Lottie animation in its video fill. A block that stands still draws unchanged.

We move a square across the page in 1 second with position/x keyframes, and back. For keyframes, see Keyframes.

// A square that crosses the page in one second. Motion blur needs motion.
let block = try engine.block.create(.graphic)
try engine.block.setShape(block, shape: engine.block.createShape(.rect))
let fill = try engine.block.createFill(.color)
try engine.block.setColor(fill, property: "fill/color/value", color: .rgba(r: 0.9, g: 0.2, b: 0.4, a: 1))
try engine.block.setFill(block, fill: fill)
try engine.block.setWidth(block, value: 300)
try engine.block.setHeight(block, value: 300)
try engine.block.setPositionY(block, value: 390)
try engine.block.appendChild(to: page, child: block)
try engine.block.setDuration(block, duration: 2)

try engine.block.setKeyframes(block, property: "position/x", keyframes: [
  Keyframe(time: 0, value: .float(100)),
  Keyframe(time: 0.5, value: .float(1520)),
  Keyframe(time: 1, value: .float(100)),
])

Turning Motion Blur On#

The block property motionBlur/enabled turns motion blur on for one block. It is false by default. The setter needs the appearance/animation scope.

// Blur the block while it moves
try engine.block.setBool(block, property: "motionBlur/enabled", value: true)
print(try engine.block.getBool(block, property: "motionBlur/enabled")) // true

Graphic, text and caption blocks have the property. Pages, scenes, groups and fills do not, and setting it on them throws. Use findAllProperties(_:) to check a block.

// Graphic, text and caption blocks have the property. Pages do not.
let blockHasMotionBlur = try engine.block.findAllProperties(block).contains("motionBlur/enabled")
let pageHasMotionBlur = try engine.block.findAllProperties(page).contains("motionBlur/enabled")
print(blockHasMotionBlur, pageHasMotionBlur) // true false

A group does not blur as a whole. Turn motion blur on for its children, and they blur when the group moves.

Shutter Angle and Phase#

The scene holds one shutter for all blocks with motion blur. Both values are in degrees of one frame.

motionBlur/shutterAngle sets how long the shutter stays open. The default is 180, which is half a frame. The range is 0 to 720. A larger angle draws a longer trail, and 0 draws no blur.
motionBlur/shutterPhase sets where the shutter opens, relative to the frame time. The default is 0, so the trail lies ahead of the block. The range is -360 to 360. A phase of minus half the angle centers the blur on the frame time. A phase of minus the angle puts the trail behind the block.

// The scene holds the shutter for all blocks with motion blur.
// 360 degrees keeps the shutter open for one full frame.
try engine.block.setFloat(scene, property: "motionBlur/shutterAngle", value: 360)
// -180 degrees, half the angle, centers the shutter on the frame time
try engine.block.setFloat(scene, property: "motionBlur/shutterPhase", value: -180)

Samples#

motionBlur/samples sets how many samples one frame averages. The default is 16 and the range is 1 to 64. More samples give a smoother trail and take longer to render. With 1 sample, no blur is drawn.

// More samples give a smoother trail and take longer to render
try engine.block.setInt(scene, property: "motionBlur/samples", value: 32)
print(try engine.block.getInt(scene, property: "motionBlur/samples")) // 32

Frame Rate#

The shutter angle refers to one frame of the video export. A video export without a frame rate option uses the scene property scene/frameRate, which is 30 by default. The preview uses the same frame. The framerate option of VideoExportOptions changes the length of one frame, so a higher frame rate draws a shorter trail.

// One frame of the scene frame rate is the span the shutter angle refers to
try engine.block.setFloat(scene, property: "scene/frameRate", value: 30)

Preview Motion Blur#

The preview draws the same blur as the video export. While the preview plays or changes, it draws fewer samples, at least 4, and smaller blur images to keep up. On a display that refreshes slower than the scene frame rate, it keeps up at the refresh rate of the display. It draws all samples once it settles. A block in crop or text editing draws sharp, so the edit shows.

The features/previewMotionBlurEnabled setting is true by default. Set it to false to show the blocks sharp while editing. The video export ignores this setting, and the scene does not save it. See Settings for the other editor settings.

// The preview draws the motion blur by default.
// Set the value to false to show the blocks sharp while editing.
try engine.editor.setSettingBool("features/previewMotionBlurEnabled", value: false)
print(try engine.editor.getSettingBool("features/previewMotionBlurEnabled")) // false

Handling Errors#

A shutter or samples value outside its range throws an EngineError whose catalogCode is .blockMotionBlurValueOutOfRange. The scene keeps the old value.

do {
  try engine.block.setInt(scene, property: "motionBlur/samples", value: 100)
} catch let error as EngineError {
  print(error.catalogCode == .blockMotionBlurValueOutOfRange) // true
}

Exporting a Video#

exportVideo(_:mimeType:options:onPreExport:uriResolver:) draws the motion blur into every frame. An image export with export(_:mimeType:) draws the blocks sharp, so a single frame never shows the blur.

// Image export draws no motion blur. Export a video to see it in a file.
let stream = try await engine.block.exportVideo(page, mimeType: .mp4)
for try await event in stream {
  if case let .finished(video: video) = event {
    try video.write(to: FileManager.default.temporaryDirectory.appendingPathComponent("motion-blur.mp4"))
  }
}

Motion Blur and Other Operations#

Saving and loading a scene keeps the block flag and the shutter values.
Older scenes load with motion blur off and the default shutter.
Loaded values outside their range are clamped to the range.
Undo and redo restore the block flag and the shutter values.

Troubleshooting#

The block does not blur: check that something moves the block during the shutter, that motionBlur/samples is greater than 1 and that motionBlur/shutterAngle is greater than 0.
An exported image is sharp: image export draws no motion blur. Export a video.
The trail is too short: raise motionBlur/shutterAngle, or export with a lower frame rate.
The trail looks like separate copies: raise motionBlur/samples.
A value is out of range (.blockMotionBlurValueOutOfRange): keep the angle from 0 to 720, the phase from -360 to 360 and the samples from 1 to 64.
A value is not a number (.editorValueNotFinite): pass a finite shutter angle and phase.
The video export fails (.encodeVideoBlockHasError): the trail of a block is too large to render on this device. Make the block or its motion smaller, or lower the export size.
Setting the flag throws: the block is not a graphic, text or caption block, or the appearance/animation scope is off.

API Reference#

Method	Description
`engine.block.setBool(_:property:value:)`	Turn `motionBlur/enabled` on or off for a block
`engine.block.getBool(_:property:)`	Check whether a block has motion blur
`engine.block.findAllProperties(_:)`	List the properties of a block, to check for `motionBlur/enabled`
`engine.block.setFloat(_:property:value:)`	Set `motionBlur/shutterAngle`, `motionBlur/shutterPhase` or `scene/frameRate`
`engine.block.setInt(_:property:value:)`	Set `motionBlur/samples`
`engine.block.getInt(_:property:)`	Read the samples
`engine.editor.setSettingBool(_:value:)`	Turn the preview motion blur on or off
`engine.editor.getSettingBool(_:)`	Read the preview motion blur setting
`engine.block.setKeyframes(_:property:keyframes:mode:)`	Move the block
`engine.block.exportVideo(_:mimeType:options:onPreExport:uriResolver:)`	Export a video with motion blur

Next Steps#

Keyframes: move blocks with keyframe tracks.
Create Animations: add preset animations that move blocks.
Settings: change other editor settings.