@px-petals/roku.motion-web 1.0.0 → 1.1.0

package/skin/skin.ik.js

@@ -0,0 +1,260 @@
+/**
+ * Inverse kinematics for a skin's bone chain, from rive-runtime's
+ * `IKConstraint` (src/constraints/ik_constraint.cpp): one bone points at the
+ * target, two are solved by the law of cosines, a longer chain solves each
+ * bone against the tip in turn, and strength blends the solved angles with
+ * the angles the chain had. The converter solves the same way
+ * (rive/transformer/constraint/constraint.ik.js).
+ *
+ * It runs whenever a bound value moves a skin, so it allocates nothing: the
+ * caller fills `LOCALS` and `PARENT`, `solve` works in preallocated buffers,
+ * and the solved worlds are in `WORLDS`.
+ */
+
+/** The most bones in a chain; a longer one is left as the bones' own values pose it */
+export const MAX_CHAIN = 32
+
+/** The chain's local matrices before the solve, six numbers a bone */
+export const LOCALS = new Float64Array(MAX_CHAIN * 6)
+/** The world matrix of the top bone's parent */
+export const PARENT = new Float64Array(6)
+/** The solved world matrices, six numbers a bone; the first six are the parent's, so a bone's parent is the slot before it */
+export const WORLDS = new Float64Array((MAX_CHAIN + 1) * 6)
+
+// what the solve starts from: each bone's own x, y, scale, skew and rotation, and its parent's world, inverted
+const COMPONENTS = new Float64Array(MAX_CHAIN * 6)
+const INVERSES = new Float64Array(MAX_CHAIN * 6)
+const ANGLES = new Float64Array(MAX_CHAIN)
+
+const TAU = Math.PI * 2
+
+/**
+ * `world[slot] = world[parent] × local`, the matrices six numbers each.
+ *
+ * @param {number} bone the bone's place in the chain
+ */
+function compose(bone) {
+  const p = bone * 6
+  const q = bone * 6
+  const o = (bone + 1) * 6
+  const a0 = WORLDS[p], a1 = WORLDS[p + 1], a2 = WORLDS[p + 2], a3 = WORLDS[p + 3], a4 = WORLDS[p + 4], a5 = WORLDS[p + 5]
+  const b0 = LOCALS[q], b1 = LOCALS[q + 1], b2 = LOCALS[q + 2], b3 = LOCALS[q + 3], b4 = LOCALS[q + 4], b5 = LOCALS[q + 5]
+  WORLDS[o] = a0 * b0 + a2 * b1
+  WORLDS[o + 1] = a1 * b0 + a3 * b1
+  WORLDS[o + 2] = a0 * b2 + a2 * b3
+  WORLDS[o + 3] = a1 * b2 + a3 * b3
+  WORLDS[o + 4] = a0 * b4 + a2 * b5 + a4
+  WORLDS[o + 5] = a1 * b4 + a3 * b5 + a5
+}
+
+/**
+ * The bone's parent's world, inverted (the identity where it has no inverse).
+ *
+ * @param {number} bone
+ */
+function invertParent(bone) {
+  const p = bone * 6
+  const o = bone * 6
+  const a = WORLDS[p], b = WORLDS[p + 1], c = WORLDS[p + 2], d = WORLDS[p + 3], tx = WORLDS[p + 4], ty = WORLDS[p + 5]
+  let det = a * d - b * c
+  if (det === 0) {
+    INVERSES[o] = 1
+    INVERSES[o + 1] = 0
+    INVERSES[o + 2] = 0
+    INVERSES[o + 3] = 1
+    INVERSES[o + 4] = 0
+    INVERSES[o + 5] = 0
+    return
+  }
+  det = 1 / det
+  INVERSES[o] = d * det
+  INVERSES[o + 1] = -b * det
+  INVERSES[o + 2] = -c * det
+  INVERSES[o + 3] = a * det
+  INVERSES[o + 4] = (c * ty - d * tx) * det
+  INVERSES[o + 5] = (b * tx - a * ty) * det
+}
+
+/**
+ * The bone's local matrix at a rotation, its position, scale and skew as it began.
+ *
+ * @param {number} bone
+ * @param {number} rotation
+ */
+function turn(bone, rotation) {
+  const c = bone * 6
+  const cos = rotation === 0 ? 1 : Math.cos(rotation)
+  const sin = rotation === 0 ? 0 : Math.sin(rotation)
+  const a = cos * COMPONENTS[c + 2]
+  const b = sin * COMPONENTS[c + 2]
+  let m2 = -sin * COMPONENTS[c + 3]
+  let m3 = cos * COMPONENTS[c + 3]
+  const skew = COMPONENTS[c + 4]
+  if (skew !== 0) {
+    m2 = a * skew + m2
+    m3 = b * skew + m3
+  }
+  LOCALS[c] = a
+  LOCALS[c + 1] = b
+  LOCALS[c + 2] = m2
+  LOCALS[c + 3] = m3
+  LOCALS[c + 4] = COMPONENTS[c]
+  LOCALS[c + 5] = COMPONENTS[c + 1]
+  compose(bone)
+}
+
+/**
+ * `std::max(-1, std::min(1, x))`, which sends NaN to 1 as the C++ library does.
+ *
+ * @param {number} x
+ */
+function clamp(x) {
+  const low = x < 1 ? x : 1
+  return -1 < low ? low : -1
+}
+
+/**
+ * The shorter turn from one angle to another, each first taken modulo a full turn.
+ *
+ * @param {number} from
+ * @param {number} to
+ */
+function difference(from, to) {
+  let diff = (to % TAU) - (from % TAU)
+  if (diff > Math.PI) diff -= TAU
+  else if (diff < -Math.PI) diff += TAU
+  return diff
+}
+
+/**
+ * @param {number} bone
+ * @returns {number} the x of the bone's world translation
+ */
+const worldX = (bone) => WORLDS[(bone + 1) * 6 + 4]
+/** @param {number} bone */
+const worldY = (bone) => WORLDS[(bone + 1) * 6 + 5]
+
+/**
+ * A point through the matrix of a bone's parent's inverse, as x or y.
+ *
+ * @param {number} bone
+ * @param {number} x
+ * @param {number} y
+ * @param {boolean} wantY
+ */
+function parentSpace(bone, x, y, wantY) {
+  const i = bone * 6
+  return wantY ? INVERSES[i + 1] * x + INVERSES[i + 3] * y + INVERSES[i + 5] : INVERSES[i] * x + INVERSES[i + 2] * y + INVERSES[i + 4]
+}
+
+/**
+ * Solves the chain in `LOCALS` against a target, leaving the worlds in `WORLDS`.
+ *
+ * @param {number}  count      bones in the chain, the top one first
+ * @param {number}  tipLength  the last bone's length
+ * @param {number}  tx         the target's world x
+ * @param {number}  ty         the target's world y
+ * @param {boolean} invert
+ * @param {number}  strength   0..1
+ */
+export function solve(count, tipLength, tx, ty, invert, strength) {
+  for (let k = 0; k < 6; k++) WORLDS[k] = PARENT[k]
+  for (let n = 0; n < count; n++) {
+    const c = n * 6
+    // Mat2D::decompose of the bone's own matrix
+    const m0 = LOCALS[c], m1 = LOCALS[c + 1], m2 = LOCALS[c + 2], m3 = LOCALS[c + 3]
+    const denom = m0 * m0 + m1 * m1
+    const scaleX = Math.sqrt(denom)
+    COMPONENTS[c] = LOCALS[c + 4]
+    COMPONENTS[c + 1] = LOCALS[c + 5]
+    COMPONENTS[c + 2] = scaleX
+    COMPONENTS[c + 3] = scaleX === 0 ? 0 : (m0 * m3 - m2 * m1) / scaleX
+    COMPONENTS[c + 4] = Math.atan2(m0 * m2 + m1 * m3, denom)
+    COMPONENTS[c + 5] = Math.atan2(m1, m0)
+    ANGLES[n] = COMPONENTS[c + 5]
+    compose(n)
+  }
+  for (let n = 0; n < count; n++) invertParent(n)
+
+  if (count === 1) {
+    solveOne(tx, ty)
+  } else if (count === 2) {
+    solveTwo(0, 1, tipLength, tx, ty, invert)
+  } else {
+    const last = count - 1
+    for (let n = 0; n < last; n++) {
+      solveTwo(n, last, tipLength, tx, ty, invert)
+      for (let j = n + 1; j < last; j++) invertParent(j)
+    }
+  }
+
+  if (strength !== 1) {
+    for (let n = 0; n < count; n++) {
+      const from = COMPONENTS[n * 6 + 5] % TAU
+      turn(n, from + difference(from, ANGLES[n]) * strength)
+    }
+  }
+}
+
+/**
+ * @param {number} tx
+ * @param {number} ty
+ */
+function solveOne(tx, ty) {
+  const x = INVERSES[0] * (tx - worldX(0)) + INVERSES[2] * (ty - worldY(0))
+  const y = INVERSES[1] * (tx - worldX(0)) + INVERSES[3] * (ty - worldY(0))
+  const r = Math.atan2(y, x)
+  turn(0, r)
+  ANGLES[0] = r
+}
+
+/**
+ * @param {number}  first     the bone solved against the target
+ * @param {number}  last      the tip, which the solve brings to the target
+ * @param {number}  tipLength
+ * @param {number}  tx
+ * @param {number}  ty
+ * @param {boolean} invert
+ */
+function solveTwo(first, last, tipLength, tx, ty, invert) {
+  const child = first + 1
+  const aX = parentSpace(first, worldX(first), worldY(first), false)
+  const aY = parentSpace(first, worldX(first), worldY(first), true)
+  const cX = parentSpace(first, worldX(child), worldY(child), false)
+  const cY = parentSpace(first, worldX(child), worldY(child), true)
+  const lw = (last + 1) * 6
+  const tipX = WORLDS[lw] * tipLength + WORLDS[lw + 4]
+  const tipY = WORLDS[lw + 1] * tipLength + WORLDS[lw + 5]
+  const bX = parentSpace(first, tipX, tipY, false)
+  const bY = parentSpace(first, tipX, tipY, true)
+  const tX = parentSpace(first, tx, ty, false)
+  const tY = parentSpace(first, tx, ty, true)
+
+  const a = Math.sqrt((bX - cX) * (bX - cX) + (bY - cY) * (bY - cY))
+  const b = Math.sqrt((cX - aX) * (cX - aX) + (cY - aY) * (cY - aY))
+  const cvX = tX - aX
+  const cvY = tY - aY
+  const c = Math.sqrt(cvX * cvX + cvY * cvY)
+
+  const A = Math.acos(clamp((-a * a + b * b + c * c) / (2 * b * c)))
+  const C = Math.acos(clamp((a * a + b * b - c * c) / (2 * a * b)))
+
+  let correction = 0
+  if (last !== child) {
+    // the tip is further down: the bone after the child turns the correction
+    const dx = tipX - worldX(child)
+    const dy = tipY - worldY(child)
+    const lx = INVERSES[(first + 2) * 6] * dx + INVERSES[(first + 2) * 6 + 2] * dy
+    const ly = INVERSES[(first + 2) * 6 + 1] * dx + INVERSES[(first + 2) * 6 + 3] * dy
+    correction = -Math.atan2(ly, lx)
+  }
+  const toTarget = Math.atan2(cvY, cvX)
+  const r1 = invert ? toTarget - A : A + toTarget
+  const r2 = (invert ? -C + Math.PI : C - Math.PI) + correction
+
+  turn(first, r1)
+  turn(child, r2)
+  if (child !== last) compose(last)
+  ANGLES[first] = r1
+  ANGLES[child] = r2
+}

package/skin/skin.js

@@ -0,0 +1,297 @@
+/**
+ * Skins: the paths a bundle's `skins` deform from the values data binds set.
+ * A bind's source is a slot's source (a view-model path and a converter),
+ * read by the caller's `read`; each time one of a skin's bound values changes
+ * the skin's path is recomputed, to be written into the slot `sid` as any slot
+ * value.
+ *
+ * A skin may also hold IK constraints over its bones (`ik`), whose strength
+ * and target position data can bind as well: they are solved, one chain each,
+ * before the bones deform the path.
+ *
+ * Under the bound values play what an animation keys in the rig (`keys`),
+ * as Rive applies animations first and binds after: a bound channel overrides
+ * the keyed one, and the rest keep following the animation. A skin an
+ * animation keys is written as a function of the frame, for the player to ask
+ * as it draws; any other as the path itself. In a nested machine that plays
+ * several animations at once, each channel is mixed toward each pose that
+ * keys it by the pose's weight, as Rive applies them, before the bones deform
+ * the path; the player passes the poses of the machine the path is drawn in.
+ *
+ * Nothing is allocated once a skin is made: its values, the scratch it
+ * deforms in and the paths it writes are made up front and reused.
+ */
+
+import { BONE_CHANNELS, createPath, createRig, deformRig, IK_CHANNELS, NODE_CHANNELS, VERTEX_CHANNELS } from './skin.deform.js'
+import { settledWeight } from '../mixer/mixer.mix.js'
+
+/**
+ * @typedef {import('./skin.deform.js').Skin}       Skin
+ * @typedef {import('./skin.deform.js').LottiePath} LottiePath
+ * @typedef {import('./skin.deform.js').Rig}        Rig
+ *
+ * @typedef {object} State
+ * @property {Skin}          skin
+ * @property {Rig}           rig
+ * @property {number[]}      at      where in `rig.now` each bind's value goes
+ * @property {any[]}         sources each bind's source
+ * @property {Float64Array}  values  each bind's value
+ * @property {Uint8Array}    has     whether each bind has one
+ * @property {number}        version counts the changes of the bound values
+ * @property {number}        done    the version the static path was made for
+ * @property {LottiePath}    path    the path while no animation keys the skin
+ * @property {Record<string, Played | null>} played what an animation keys, by animation id
+ *
+ * @typedef {object} Played
+ * @property {number[]}   at       where in `rig.now` each track's value goes
+ * @property {number[][]} keys     each track's `[frame, value, ...]`
+ * @property {Array<number[] | null>} segments each track's keying segments on a nested machine's stitched timeline, null outside one
+ * @property {LottiePath} path
+ * @property {number}     frame    the frame the path was made for
+ * @property {number}     done     the version of the bound values it was made for
+ * @property {any}        poses    the poses it was made for
+ * @property {(frame: number, poses?: Pose[] | null) => LottiePath} fn
+ *
+ * @typedef {{ start: number, frame: number, weight: number }} Pose a nested machine's animation playing: its segment's first frame, how far in it is, and its weight
+ *
+ * @typedef {object} Skins
+ * @property {number}                                                       count   skins held
+ * @property {(read: (source: any) => any) => void}                         update  reads every bound value; a skin whose values have not changed keeps its path
+ * @property {(animation?: string) => Record<string, any>}                  table   by slot id, the value of each skin with a bound value, for the animation with that id
+ * @property {(read: (source: any) => any, animation?: string) => Record<string, any>} evaluate  `update`, then `table`
+ * @property {(sid: string, animation: string) => any}                    keyedBy the skin's value in an animation that keys it, else undefined: a pose that does not key a skin leaves it alone
+ */
+
+/**
+ * @param   {Skin[] | undefined} list a bundle's `skins`
+ * @returns {Skins}
+ */
+export function createSkins(list) {
+  /** @type {State[]} */
+  const states = []
+  for (let n = 0; n < (list || []).length; n++) states.push(makeState(/** @type {Skin[]} */ (list)[n]))
+  /** @type {Record<string, Record<string, any>>} */
+  const tables = {}
+
+  /** @param {string} [animation] */
+  function table(animation) {
+    const key = animation || ''
+    const found = tables[key] || (tables[key] = {})
+    for (let n = 0; n < states.length; n++) {
+      const state = states[n]
+      if (isBound(state)) found[state.skin.sid] = valueOf(state, key)
+      else delete found[state.skin.sid]
+    }
+    return found
+  }
+
+  /** @param {(source: any) => any} read */
+  function update(read) {
+    for (let n = 0; n < states.length; n++) read1(states[n], read)
+  }
+
+  /** @param {string} sid @param {string} animation */
+  function keyedBy(sid, animation) {
+    for (let n = 0; n < states.length; n++) {
+      const state = states[n]
+      const keys = state.skin.keys
+      if (state.skin.sid !== sid || !keys || !keys[animation] || !isBound(state)) continue
+      return valueOf(state, animation)
+    }
+    return undefined
+  }
+
+  return {
+    count: states.length,
+    update,
+    table,
+    keyedBy,
+    evaluate(read, animation) {
+      update(read)
+      return table(animation)
+    },
+  }
+}
+
+/**
+ * @param   {Skin} skin
+ * @returns {State}
+ */
+function makeState(skin) {
+  const rig = createRig(skin)
+  /** @type {number[]} */
+  const at = []
+  /** @type {any[]} */
+  const sources = []
+  /** @param {any[]} list @param {Record<string, number>} channels @param {number} first @param {number} width */
+  const collect = (list, channels, first, width) => {
+    for (let n = 0; n < list.length; n++) {
+      const binds = list[n].binds || {}
+      for (const name in binds) {
+        if (channels[name] === undefined || !binds[name] || !binds[name].source) continue
+        at.push(first + n * width + channels[name])
+        sources.push(binds[name].source)
+      }
+    }
+  }
+  collect(skin.bones, BONE_CHANNELS, 0, 6)
+  collect(skin.nodes || [], NODE_CHANNELS, rig.nodeAt, 5)
+  collect(skin.ik || [], IK_CHANNELS, rig.ikAt, 3)
+  return { skin, rig, at, sources, values: new Float64Array(at.length), has: new Uint8Array(at.length), version: 0, done: -1, path: createPath(skin), played: {} }
+}
+
+/**
+ * Reads what each bind holds now: a number, else nothing.
+ *
+ * @param {State}                state
+ * @param {(source: any) => any} read
+ */
+function read1(state, read) {
+  let changed = false
+  for (let n = 0; n < state.sources.length; n++) {
+    const value = read(state.sources[n])
+    const number = typeof value === 'number' ? value : parseFloat(value)
+    const has = isFinite(number) ? 1 : 0
+    if (has !== state.has[n] || (has && number !== state.values[n])) changed = true
+    state.has[n] = has
+    state.values[n] = has ? number : 0
+  }
+  if (changed) state.version++
+}
+
+/**
+ * Whether any of a skin's binds has a value: until one does the slot keeps the setup deform the bundle carries.
+ *
+ * @param   {State} state
+ * @returns {boolean}
+ */
+function isBound(state) {
+  for (let n = 0; n < state.has.length; n++) if (state.has[n]) return true
+  return false
+}
+
+/**
+ * The value of a bound skin's slot in an animation.
+ *
+ * @param   {State}  state
+ * @param   {string} animation
+ * @returns {LottiePath | ((frame: number) => LottiePath)}
+ */
+function valueOf(state, animation) {
+  let played = state.played[animation]
+  if (played === undefined) {
+    const all = state.skin.keys
+    const keys = (all && (all[animation] || all['*'])) || []
+    if (keys.length) {
+      const at = []
+      const k = []
+      const segments = []
+      for (let n = 0; n < keys.length; n++) {
+        at.push(channelAt(state.rig, keys[n]))
+        k.push(keys[n].k)
+        segments.push(keys[n].s || null)
+      }
+      /** @type {Played} */
+      const own = { at, keys: k, segments, path: createPath(state.skin), frame: NaN, done: -1, poses: null, fn: /** @type {any} */ (null) }
+      own.fn = (frame, given) => {
+        // a machine writes its poses as a new list each time they change
+        const poses = given || null
+        if (own.frame !== frame || own.done !== state.version || own.poses !== poses) {
+          own.frame = frame
+          own.done = state.version
+          own.poses = poses
+          setValues(state, own, frame, poses)
+          deformRig(state.rig, own.path)
+        }
+        return own.path
+      }
+      played = own
+    } else {
+      played = null
+    }
+    state.played[animation] = played
+  }
+  if (played) return played.fn
+
+  if (state.done !== state.version) {
+    state.done = state.version
+    setValues(state, null, 0, null)
+    deformRig(state.rig, state.path)
+  }
+  return state.path
+}
+
+/**
+ * The value a track moves, as an index into `rig.now`.
+ *
+ * @param   {Rig}                                         rig
+ * @param   {{ o: string, i: number, c: string }}         track
+ * @returns {number}
+ */
+function channelAt(rig, track) {
+  if (track.o === 'n') return rig.nodeAt + track.i * 5 + NODE_CHANNELS[/** @type {keyof typeof NODE_CHANNELS} */ (track.c)]
+  if (track.o === 'v') return rig.vertexAt + track.i * 7 + VERTEX_CHANNELS[/** @type {keyof typeof VERTEX_CHANNELS} */ (track.c)]
+  return track.i * 6 + BONE_CHANNELS[/** @type {keyof typeof BONE_CHANNELS} */ (track.c)]
+}
+
+/**
+ * Puts the values a deform uses in `rig.now`: the setup, what the animation
+ * keys at the frame, mixed toward each pose that keys a track, then what
+ * binds hold.
+ *
+ * @param {State}         state
+ * @param {Played | null} played
+ * @param {number}        frame
+ * @param {Pose[] | null} poses
+ */
+function setValues(state, played, frame, poses) {
+  const now = state.rig.now
+  now.set(state.rig.base)
+  if (played) {
+    for (let n = 0; n < played.at.length; n++) now[played.at[n]] = posedValue(played.keys[n], played.segments[n], frame, poses)
+  }
+  for (let n = 0; n < state.at.length; n++) if (state.has[n]) now[state.at[n]] = state.values[n]
+}
+
+/**
+ * A track's value in the poses whose segments key it, each counting as much
+ * as it does in the value Rive settles on (`settledWeight`); with none keying
+ * it, its value at the frame.
+ *
+ * @param   {number[]}        k
+ * @param   {number[] | null} segments
+ * @param   {number}          frame
+ * @param   {Pose[] | null}   poses
+ * @returns {number}
+ */
+function posedValue(k, segments, frame, poses) {
+  let value = valueAt(k, frame)
+  if (!poses || !segments) return value
+
+  let total = 0
+  for (let n = 0; n < poses.length; n++) {
+    const pose = poses[n]
+    const weight = segments.indexOf(pose.start) < 0 ? 0 : settledWeight(poses, n, segments)
+    if (weight <= 0) continue
+    total += weight
+    value += (valueAt(k, pose.start + pose.frame) - value) * (weight / total)
+  }
+  return value
+}
+
+/**
+ * A track's value at a frame: `[frame, value, ...]` blended linearly, held
+ * before the first and after the last.
+ *
+ * @param   {number[]} k
+ * @param   {number}   frame
+ * @returns {number}
+ */
+function valueAt(k, frame) {
+  if (frame <= k[0]) return k[1]
+  for (let n = 2; n < k.length; n += 2) {
+    if (frame > k[n]) continue
+    return k[n - 1] + (k[n + 1] - k[n - 1]) * ((frame - k[n - 2]) / (k[n] - k[n - 2]))
+  }
+  return k[k.length - 1]
+}