Drawing API basics

This reference covers the small set of Motion Lab APIs used in the looping animation tutorial. It is not a complete API catalog.

The motion object is supplied by the code-layer runtime. These examples belong in Motion Lab's code editor.

Frame callback#

motion.onFrame(callback) registers a synchronous function that runs for a rendered frame. Read timeline values and issue drawing commands inside this function.

motion.onFrame(() => {
  motion.draw.clear();
  motion.draw.setBackground("#090d1a");
  motion.draw.circle(0.5, 0.5, 0.02, {
    color: "#65e7ff",
    fillOnly: true,
  });
});

Keep one frame callback for this example. Replace the previous source when trying a new example instead of appending another callback.

Timeline values#

• motion.time: current timeline time in seconds.
• motion.duration: composition duration in seconds.
• motion.progress: timeline time divided by duration, clamped to the range from zero to one.

Read these values during the callback so they reflect the current frame. For the reasoning behind time-based drawing, see Timeline time and loops.

Clear and background#

motion.draw.clear() clears the drawing canvas.

motion.draw.setBackground(color) fills the canvas with the supplied paint. The tutorial uses a hexadecimal color string.

Call these before drawing the shapes for the current frame when you want each frame to replace the previous one.

Draw a circle#

motion.draw.circle(x, y, radius, options) draws a circle with normalized coordinates.

• x is relative to the frame width; 0.5 is the horizontal center.
• y is relative to the frame height; 0.5 is the vertical center.
• radius is relative to the shorter frame dimension.
• options.color sets the paint color used in this example.
• options.fillOnly: true draws a filled shape without a stroke.

The top-left corner is (0, 0) and the bottom-right corner is (1, 1).

Equal changes in normalized x and y represent different pixel distances on a rectangular frame. Use a square frame for the circular orbit in the tutorial, or account for aspect ratio in your position calculations.