@px-petals/roku.motion-web 0.0.0-stage → 1.1.0

package/mixer/mixer.js

@@ -0,0 +1,307 @@
+/**
+ * The pose mixer: draws several animations of one artboard at once, each at
+ * its own time and weight, as one picture.
+ *
+ * rive2lottie writes every animation of an artboard as a Lottie with the
+ * same layers and shapes, and tags each property with `rid`, the Rive object
+ * and property it came from, and `ky` when that animation keys it. The mixer
+ * takes one of them (the longest) as the picture's structure, and gives each
+ * keyed property a mixing evaluator in place of its keyframes. For a set of
+ * poses, `{ animation, time, weight }`, that evaluator reads the property in
+ * each pose's animation at the pose's time and blends the values in order,
+ * as Rive applies animations: each lerps the value so far toward its own by
+ * its weight. A pose whose animation doesn't key the property leaves it
+ * alone. The value so far starts from what the property held after the
+ * previous frame, as Rive's artboard keeps what it last applied: a property
+ * no active animation keys stays where it was, and a blend whose weights
+ * don't add up to one settles over a few frames. A pair of axes (position)
+ * keyed on one axis only is mixed on that axis only. What isn't tagged (a nested artboard's own animation) follows the
+ * first pose's time; text overlays are mixed by the player (`mixOverlays`).
+ */
+
+import { createAnimation } from '../lottie/lottie.js'
+import { evaluator } from '../lottie/lottie.props.js'
+import { mixValues } from './mixer.mix.js'
+
+/** @import { Animation } from '../lottie/lottie.js' */
+/** @import { Evaluator } from '../lottie/lottie.props.js' */
+/** @import { Matrix } from '../lottie/lottie.paths.js' */
+
+/**
+ * One animation shown at a time, with a weight.
+ * @typedef {object} Pose
+ * @property {string} animation an animation id
+ * @property {number} time      seconds into it
+ * @property {number} weight    0 to 1
+ */
+
+/** What an animation does to one property: its value at a frame, whether it keys the property, and, for a pair of axes with one keyed, which; `picks` for a Solo option's visibility, which an animation sets whole, never blends */
+/** @typedef {{ at: Evaluator, keyed: boolean, axes: number[] | null, picks: boolean }} Source */
+
+/** The `rid` of a Solo option's visibility: `<object id>.solo` */
+const SOLO = /\.solo$/
+
+/** A pose, prepared for the evaluators: where its animation's sources are, and how far its frame is from the drawn one */
+/** @typedef {{ animation: string, sources: Record<string, Source>, offset: number, weight: number }} Prepared */
+
+/**
+ * What the mixing evaluators share: the poses of the draw, and each property's value after the previous frame.
+ * @typedef {object} Current
+ * @property {Prepared[]}          poses
+ * @property {Record<string, any>} last   by `rid`, what each held after the previous frame
+ * @property {Record<string, any>} next   by `rid`, what each holds in this one
+ * @property {number}              frame  the frame `next` belongs to
+ * @property {number}              passes how many times a draw applies the poses
+ */
+
+/** No slots: a source reads its keyframes, and the drawn animation's own slots go over the result */
+const NO_SLOTS = {}
+
+/**
+ * @typedef {object} Mixer
+ * @property {Animation}                                                                                               animation the mixed picture; its `slots` are live
+ * @property {string}                                                                                                  carrier   the animation whose structure it has
+ * @property {(ctx: CanvasRenderingContext2D, poses: Pose[], matrix: Matrix, frame?: number, passes?: number) => void} draw      `frame` counts the stage's steps: drawing the same frame again leaves each property where it was; `passes` applies the poses that many times, for a stage that has stopped but must settle
+ * @property {(read: (animation: string) => any, base: any) => Evaluator}                                          mixed     a value each animation gives on its own (a slot the player fills, such as a skin's path), mixed over the poses being drawn: each pose whose animation gives one lerps toward it by its weight
+ */
+
+/**
+ * @param   {Record<string, any>}          lotties            parsed Lottie JSON by animation id; the longest is changed in place
+ * @param   {object}                       [options]
+ * @param   {string}                       [options.base]     where images resolve from
+ * @param   {() => Record<string, string>} [options.families] the bundle's fonts by name, as registered
+ * @returns {Mixer}
+ */
+export function createMixer(lotties, options) {
+  const carrier = longest(lotties)
+  /** @type {Record<string, Record<string, Source>>} */
+  const sources = {}
+  for (const id in lotties) sources[id] = collect(lotties[id])
+
+  /** @type {Current} */
+  const current = { poses: [], last: {}, next: {}, frame: -1, passes: 1 }
+  install(lotties[carrier], sources, carrier, current)
+  const animation = createAnimation(lotties[carrier], options)
+
+  return {
+    animation,
+    carrier,
+    draw(ctx, poses, matrix, frame, passes) {
+      current.passes = passes || 1
+      // a new frame: what the last one left is where this one starts
+      if (frame === undefined || frame !== current.frame) {
+        for (const rid in current.next) current.last[rid] = current.next[rid]
+        current.next = {}
+        current.frame = frame === undefined ? -1 : frame
+      }
+      animation.draw(ctx, prepare(lotties, sources, poses, current, carrier), matrix)
+    },
+    mixed(read, base) {
+      return (frame) => {
+        let value = typeof base === 'function' ? base(frame) : base
+        for (let n = 0; n < current.poses.length; n++) {
+          const pose = current.poses[n]
+          const own = read(pose.animation)
+          if (own === undefined) continue
+          value = mixValues(value, typeof own === 'function' ? own(frame + pose.offset) : own, pose.weight)
+        }
+        return value
+      }
+    },
+  }
+}
+
+/**
+ * The animation with the longest timeline, in seconds: any pose's time fits it.
+ *
+ * @param   {Record<string, any>} lotties
+ * @returns {string}
+ */
+function longest(lotties) {
+  let best = ''
+  let bestSeconds = -1
+  for (const id in lotties) {
+    const lottie = lotties[id]
+    const seconds = ((lottie.op || 0) - (lottie.ip || 0)) / (lottie.fr || 30)
+    if (seconds > bestSeconds) {
+      best = id
+      bestSeconds = seconds
+    }
+  }
+  return best
+}
+
+/**
+ * Every tagged property of a Lottie, by its `rid`; the first of a repeated one wins.
+ *
+ * @param   {any}                    lottie
+ * @returns {Record<string, Source>}
+ */
+function collect(lottie) {
+  /** @type {Record<string, Source>} */
+  const found = {}
+  visit(lottie, (property) => {
+    if (found[property.rid]) return
+    found[property.rid] = { at: evaluator(property, NO_SLOTS), keyed: property.ky === 1, axes: Array.isArray(property.kc) ? property.kc : null, picks: SOLO.test(property.rid) }
+  })
+  return found
+}
+
+/**
+ * Calls back for every tagged property under a node, in assets as in layers.
+ *
+ * @param {any}                     node
+ * @param {(property: any) => void} found
+ */
+function visit(node, found) {
+  if (node === null || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (let n = 0; n < node.length; n++) visit(node[n], found)
+    return
+  }
+  if (typeof node.rid === 'string' && 'k' in node) found(node)
+  // a property's `k` holds its values; a gradient's `g.k` is a property itself
+  const isProperty = 'a' in node || typeof node.rid === 'string'
+  for (const key in node) {
+    if ((key === 'k' && isProperty) || key === 'rid') continue
+    visit(node[key], found)
+  }
+}
+
+/**
+ * Gives the carrier's keyed properties their mixing evaluators.
+ *
+ * @param {any}                                    lottie
+ * @param {Record<string, Record<string, Source>>} sources
+ * @param {string}                                 carrier
+ * @param {Current}                                current
+ */
+function install(lottie, sources, carrier, current) {
+  /** @type {Record<string, any>} */
+  const bases = {}
+  /** @type {Record<string, boolean>} */
+  const isKeyed = {}
+  for (const id in sources) {
+    for (const rid in sources[id]) {
+      if (sources[id][rid].keyed) isKeyed[rid] = true
+    }
+  }
+  for (const rid in isKeyed) bases[rid] = baseOf(rid, sources, carrier, lottie)
+
+  visit(lottie, (property) => {
+    if (isKeyed[property.rid]) property.mx = mixing(property.rid, bases[property.rid], current)
+  })
+}
+
+/**
+ * A property's value with no animation on it: where one animation holds it
+ * still, that value; where all key it, the carrier's first. A pair of axes
+ * takes each axis from an animation that holds that axis still.
+ *
+ * @param   {string}                                 rid
+ * @param   {Record<string, Record<string, Source>>} sources
+ * @param   {string}                                 carrier
+ * @param   {any}                                    lottie
+ * @returns {any}
+ */
+function baseOf(rid, sources, carrier, lottie) {
+  for (const id in sources) {
+    const source = sources[id][rid]
+    if (source && !source.keyed) return source.at(0)
+  }
+  // a property the carrier does not tag starts from the first animation that does
+  let own = sources[carrier][rid]
+  for (const id in sources) if (!own) own = sources[id][rid]
+  const first = own.at(lottie.ip || 0)
+  if (!Array.isArray(first)) return first
+
+  const result = first.slice()
+  for (let axis = 0; axis < result.length; axis++) {
+    for (const id in sources) {
+      const source = sources[id][rid]
+      if (!source || !source.axes || source.axes[axis]) continue
+      const still = source.at(0)
+      if (Array.isArray(still) && typeof still[axis] === 'number') result[axis] = still[axis]
+      break
+    }
+  }
+  return result
+}
+
+/**
+ * Mixes only the keyed axes of a vector.
+ *
+ * @param   {any}      a    the value so far
+ * @param   {any}      b    the value being mixed in
+ * @param   {number}   t    b's weight
+ * @param   {number[]} axes 1 for each axis b moves
+ * @returns {any}
+ */
+function mixAxes(a, b, t, axes) {
+  if (t <= 0 || !Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return mixValues(a, b, t)
+  const result = a.slice()
+  for (let n = 0; n < result.length; n++) {
+    if (axes[n] && typeof a[n] === 'number' && typeof b[n] === 'number') result[n] = a[n] + (b[n] - a[n]) * Math.min(1, t)
+  }
+  return result
+}
+
+/**
+ * @param   {string}    rid
+ * @param   {any}       base
+ * @param   {Current}   current
+ * @returns {Evaluator}
+ */
+function mixing(rid, base, current) {
+  return (frame) => {
+    const poses = current.poses
+    let value = rid in current.last ? current.last[rid] : base
+    for (let pass = 0; pass < current.passes; pass++) {
+      for (let n = 0; n < poses.length; n++) {
+        const pose = poses[n]
+        const source = pose.sources[rid]
+        if (!source || !source.keyed) continue
+
+        const sample = source.at(frame + pose.offset)
+        // a Solo's choice is an id, which Rive sets from any animation applying it, the last one winning
+        if (source.picks) value = pose.weight > 0 ? sample : value
+        else value = source.axes ? mixAxes(value, sample, pose.weight, source.axes) : mixValues(value, sample, pose.weight)
+      }
+    }
+    current.next[rid] = value
+    return value
+  }
+}
+
+/**
+ * Readies the poses for a draw.
+ *
+ * @param   {Record<string, any>}                    lotties
+ * @param   {Record<string, Record<string, Source>>} sources
+ * @param   {Pose[]}                                 poses
+ * @param   {Current}                                current
+ * @param   {string}                                 carrier
+ * @returns {number}                                         the carrier's frame to draw
+ */
+function prepare(lotties, sources, poses, current, carrier) {
+  const structure = lotties[carrier]
+  const first = structure.ip || 0
+  const last = (structure.op || 0) - 0.001
+  current.poses = []
+  let drawn = first
+  let isFirst = true
+  for (let n = 0; n < poses.length; n++) {
+    const pose = poses[n]
+    const lottie = lotties[pose.animation]
+    if (!lottie) continue
+
+    if (isFirst) {
+      // the first pose sets the frame that what isn't tagged follows
+      drawn = Math.min(Math.max(first + pose.time * (structure.fr || 30), first), last)
+      isFirst = false
+    }
+    const frame = (lottie.ip || 0) + pose.time * (lottie.fr || 30)
+    current.poses.push({ animation: pose.animation, sources: sources[pose.animation], offset: frame - drawn, weight: pose.weight })
+  }
+  return drawn
+}

package/mixer/mixer.mix.js

@@ -0,0 +1,107 @@
+/**
+ * Mixing two values of one Lottie property: numbers and vectors (positions,
+ * scales, colours) blend component by component, and paths blend vertex by
+ * vertex when they have the same vertices. Anything else can't be blended,
+ * so the heavier of the two wins.
+ */
+
+/**
+ * @param   {any}    a the value so far
+ * @param   {any}    b the value being mixed in
+ * @param   {number} t b's weight, 0 to 1: 0 is all `a`, 1 is all `b`
+ * @returns {any}
+ */
+export function mixValues(a, b, t) {
+  if (t <= 0 || b === undefined) return a
+  if (t >= 1 || a === undefined) return b
+
+  if (typeof a === 'number' && typeof b === 'number') return a + (b - a) * t
+
+  // keyed values arrive as [v], static ones as v: a number and a one-element vector mix as a vector
+  const left = typeof a === 'number' ? [ a ] : a
+  const right = typeof b === 'number' ? [ b ] : b
+  if (isVector(left) && isVector(right) && left.length === right.length) return mixVectors(left, right, t)
+
+  const leftPath = pathOf(a)
+  const rightPath = pathOf(b)
+  if (leftPath && rightPath && sameVertices(leftPath, rightPath)) {
+    const mixed = mixPaths(leftPath, rightPath, t)
+    return Array.isArray(a) || Array.isArray(b) ? [ mixed ] : mixed
+  }
+
+  return t >= 0.5 ? b : a
+}
+
+/** @param {any} value */
+function isVector(value) {
+  if (!Array.isArray(value)) return false
+  for (let n = 0; n < value.length; n++) if (typeof value[n] !== 'number') return false
+  return true
+}
+
+/**
+ * @param {number[]} a
+ * @param {number[]} b
+ * @param {number}   t
+ */
+function mixVectors(a, b, t) {
+  const result = []
+  for (let n = 0; n < a.length; n++) result.push(a[n] + (b[n] - a[n]) * t)
+  return result
+}
+
+/**
+ * A path value is `{ c, v, i, o }`, or that in a one-element array.
+ *
+ * @param   {any} value
+ * @returns {any}       the path, or null
+ */
+function pathOf(value) {
+  const path = Array.isArray(value) ? value[0] : value
+  return path && typeof path === 'object' && Array.isArray(path.v) ? path : null
+}
+
+/**
+ * @param {any} a
+ * @param {any} b
+ */
+function sameVertices(a, b) {
+  return a.c === b.c && a.v.length === b.v.length && a.i.length === b.i.length && a.o.length === b.o.length
+}
+
+/**
+ * @param {any}    a
+ * @param {any}    b
+ * @param {number} t
+ */
+function mixPaths(a, b, t) {
+  return { c: a.c, v: mixPoints(a.v, b.v, t), i: mixPoints(a.i, b.i, t), o: mixPoints(a.o, b.o, t) }
+}
+
+/**
+ * @param {number[][]} a
+ * @param {number[][]} b
+ * @param {number}     t
+ */
+function mixPoints(a, b, t) {
+  const points = []
+  for (let n = 0; n < a.length; n++) points.push(mixVectors(a[n], b[n], t))
+  return points
+}
+
+/**
+ * How much a pose counts in the value the poses settle on: its weight, times
+ * what each pose after it that keys the value too leaves of it.
+ *
+ * @param   {Array<{ start: number, weight: number }>} poses
+ * @param   {number}                                  at     the pose's index
+ * @param   {number[]}                                keying the segments that key the value
+ * @returns {number}
+ */
+export function settledWeight(poses, at, keying) {
+  let weight = poses[at].weight
+  for (let n = at + 1; n < poses.length && weight > 0; n++) {
+    if (keying.indexOf(poses[n].start) >= 0) weight *= 1 - Math.min(1, poses[n].weight)
+  }
+  return weight
+}