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

package/skin/skin.deform.js

@@ -0,0 +1,514 @@
+/**
+ * Rive's skin deform: bone world transforms, tendon matrices and the weighted
+ * sum per vertex (rive-runtime `bones/skin.cpp`, `weight.cpp`, `bone.cpp`,
+ * `transform_component.cpp`), then the corner rounding of `shapes/path.cpp`.
+ *
+ * A rig is made once per skin: it holds the skin's setup values, the scratch
+ * the deform works in and the Lottie path it writes, all allocated up front,
+ * so a deform allocates nothing. The values a deform reads are `rig.now`,
+ * laid out as each bone's `x, y, rotation, scaleX, scaleY, length`, then
+ * each node's `x, y, rotation, scaleX, scaleY`, then each vertex's `x, y,
+ * ix, iy, ox, oy, r` (its handles are offsets from it); the caller sets what
+ * differs from `rig.base`, the setup. After the vertices come each IK
+ * constraint's `strength, x, y`.
+ *
+ * The bones an IK constraint bends are solved against its target once every
+ * bone is posed (`skin.ik.js`), and the bones below the chain follow it.
+ */
+
+import { LOCALS, MAX_CHAIN, PARENT, solve, WORLDS } from './skin.ik.js'
+
+/**
+ * @typedef {number[]} Matrix  `[a, b, c, d, tx, ty]`, Rive's `Mat2D` order (the x axis is `a, b`)
+ * @typedef {{ rid?: number, parent: number, x?: number, y?: number, rotation?: number, scaleX?: number, scaleY?: number, length?: number, parentWorld?: Matrix, node?: number, binds?: Record<string, any> }} Bone
+ * @typedef {{ parent: number, x?: number, y?: number, rotation?: number, scaleX?: number, scaleY?: number, parentWorld?: Matrix, binds?: Record<string, any> }} Node
+ * @typedef {{ tip: number, count: number, invert?: boolean, strength?: number, target: number[], space?: Matrix, binds?: Record<string, any> }} Ik  an IK constraint over `count` bones ending at `tip`, aimed at `target` (x, y in `space`)
+ * @typedef {{ v: number[], i?: number[], o?: number[], r?: number, w?: number[][], iw?: number[][], ow?: number[][] }} Vertex
+ * @typedef {{ o: string, i: number, c: string, k: number[], s?: number[] }} Track
+ * @typedef {{ sid: string, closed?: boolean, space?: Matrix, spaceNode?: number, bones: Bone[], nodes?: Node[], parentWorld?: Matrix, skin?: Matrix, tendons: { bone: number, bind: Matrix }[], vertices: Vertex[], ik?: Ik[], keys?: Record<string, Track[]> }} Skin
+ * @typedef {{ v: number[][], i: number[][], o: number[][], c: boolean }} LottiePath
+ *
+ * @typedef {object} Rig
+ * @property {Skin}          skin
+ * @property {Float64Array}  base    the setup values
+ * @property {Float64Array}  now     the values to deform with
+ * @property {number}        nodeAt  where the nodes' values start in `now`
+ * @property {number}        vertexAt where the vertices' values start
+ * @property {number}        ikAt    where the IK constraints' values start
+ * @property {Float64Array}  locals  scratch: each bone's local matrix
+ * @property {Uint8Array}    moved   scratch: whether a bone's world was solved, or follows one that was
+ * @property {LottiePath}    path    what `deformRig` writes
+ * @property {Float64Array}  worlds  scratch: the matrices of the nodes, then the bones
+ * @property {Float64Array}  tendons scratch: the tendons' matrices
+ * @property {Float64Array}  local   scratch: a local transform
+ * @property {Float64Array}  space   scratch: the space
+ * @property {Float64Array}  world   scratch: each vertex and its handles, deformed
+ * @property {Float64Array}  point   scratch: a point
+ */
+
+/** The channels of a bone, a node, a vertex, in the order `rig.now` holds them. */
+export const BONE_CHANNELS = { x: 0, y: 1, rotation: 2, scaleX: 3, scaleY: 4, length: 5 }
+export const NODE_CHANNELS = { x: 0, y: 1, rotation: 2, scaleX: 3, scaleY: 4 }
+export const VERTEX_CHANNELS = { x: 0, y: 1, ix: 2, iy: 3, ox: 4, oy: 5, r: 6 }
+export const IK_CHANNELS = { strength: 0, x: 1, y: 2 }
+
+const IDENTITY = [ 1, 0, 0, 1, 0, 0 ]
+
+/** @param {number | undefined} value @param {number} fallback */
+const number = (value, fallback) => (typeof value === 'number' ? value : fallback)
+
+/**
+ * An empty path with a skin's number of points: one per vertex, two for a
+ * vertex of a closed path that has a radius.
+ *
+ * @param   {Skin} skin
+ * @returns {LottiePath}
+ */
+export function createPath(skin) {
+  /** @type {LottiePath} */
+  const path = { v: [], i: [], o: [], c: !!skin.closed }
+  for (let n = 0; n < skin.vertices.length; n++) {
+    const count = skin.closed && skin.vertices[n].r !== undefined ? 2 : 1
+    for (let k = 0; k < count; k++) {
+      path.v.push([ 0, 0 ])
+      path.i.push([ 0, 0 ])
+      path.o.push([ 0, 0 ])
+    }
+  }
+  return path
+}
+
+/**
+ * Makes a skin's rig: its setup values and everything a deform works in.
+ *
+ * @param   {Skin} skin
+ * @returns {Rig}
+ */
+export function createRig(skin) {
+  const nodes = skin.nodes || []
+  const nodeAt = skin.bones.length * 6
+  const vertexAt = nodeAt + nodes.length * 5
+  const links = skin.ik || []
+  const ikAt = vertexAt + skin.vertices.length * 7
+  const base = new Float64Array(ikAt + links.length * 3)
+  for (let n = 0; n < skin.bones.length; n++) {
+    const bone = skin.bones[n]
+    base.set([ number(bone.x, 0), number(bone.y, 0), number(bone.rotation, 0), number(bone.scaleX, 1), number(bone.scaleY, 1), number(bone.length, 0) ], n * 6)
+  }
+  for (let n = 0; n < nodes.length; n++) {
+    const node = nodes[n]
+    base.set([ number(node.x, 0), number(node.y, 0), number(node.rotation, 0), number(node.scaleX, 1), number(node.scaleY, 1) ], nodeAt + n * 5)
+  }
+  for (let n = 0; n < skin.vertices.length; n++) {
+    const vertex = skin.vertices[n]
+    const i = vertex.i || [ 0, 0 ]
+    const o = vertex.o || [ 0, 0 ]
+    base.set([ vertex.v[0], vertex.v[1], i[0], i[1], o[0], o[1], number(vertex.r, 0) ], vertexAt + n * 7)
+  }
+
+  for (let n = 0; n < links.length; n++) base.set([ number(links[n].strength, 1), links[n].target[0], links[n].target[1] ], ikAt + n * 3)
+  return {
+    skin,
+    base,
+    now: new Float64Array(base),
+    nodeAt,
+    vertexAt,
+    ikAt,
+    locals: new Float64Array(skin.bones.length * 6),
+    moved: new Uint8Array(skin.bones.length),
+    path: createPath(skin),
+    worlds: new Float64Array((nodes.length + skin.bones.length) * 6),
+    tendons: new Float64Array(skin.tendons.length * 6),
+    local: new Float64Array(6),
+    space: new Float64Array(6),
+    world: new Float64Array(skin.vertices.length * 6),
+    point: new Float64Array(2),
+  }
+}
+
+/**
+ * `out = p × q`, writing the six numbers at `o`; `out` may be `p` or `q`.
+ *
+ * @param {Float64Array}      out
+ * @param {number}            o
+ * @param {ArrayLike<number>} p
+ * @param {number}            po
+ * @param {ArrayLike<number>} q
+ * @param {number}            qo
+ */
+function multiply(out, o, p, po, q, qo) {
+  const p0 = p[po], p1 = p[po + 1], p2 = p[po + 2], p3 = p[po + 3], p4 = p[po + 4], p5 = p[po + 5]
+  const q0 = q[qo], q1 = q[qo + 1], q2 = q[qo + 2], q3 = q[qo + 3], q4 = q[qo + 4], q5 = q[qo + 5]
+  out[o] = p0 * q0 + p2 * q1
+  out[o + 1] = p1 * q0 + p3 * q1
+  out[o + 2] = p0 * q2 + p2 * q3
+  out[o + 3] = p1 * q2 + p3 * q3
+  out[o + 4] = p0 * q4 + p2 * q5 + p4
+  out[o + 5] = p1 * q4 + p3 * q5 + p5
+}
+
+/**
+ * A local transform: translate, rotate, then scale, as `TransformComponent`
+ * composes it.
+ *
+ * @param {Float64Array} local
+ * @param {number}       x
+ * @param {number}       y
+ * @param {number}       rotation radians
+ * @param {number}       scaleX
+ * @param {number}       scaleY
+ */
+function compose(local, x, y, rotation, scaleX, scaleY) {
+  const cos = Math.cos(rotation)
+  const sin = Math.sin(rotation)
+  local[0] = cos * scaleX
+  local[1] = sin * scaleX
+  local[2] = -sin * scaleY
+  local[3] = cos * scaleY
+  local[4] = x
+  local[5] = y
+}
+
+/**
+ * Every node's and bone's world matrix, into `rig.worlds`: the nodes first,
+ * then the bones. A root bone sits at its own x and y in its parent's world
+ * (a node's, else its own `parentWorld`, else the skin's); a child bone sits
+ * at its parent's tip, `length` along the parent's x axis, whatever x and y it
+ * holds (`Bone::x`, `Bone::y`).
+ *
+ * @param {Rig} rig
+ */
+function computeWorlds(rig) {
+  const { skin, now, worlds, local } = rig
+  const nodes = skin.nodes || []
+  const parentWorld = skin.parentWorld || IDENTITY
+  for (let n = 0; n < nodes.length; n++) {
+    const at = rig.nodeAt + n * 5
+    compose(local, now[at], now[at + 1], now[at + 2], now[at + 3], now[at + 4])
+    const node = nodes[n]
+    if (node.parent < 0) multiply(worlds, n * 6, node.parentWorld || parentWorld, 0, local, 0)
+    else multiply(worlds, n * 6, worlds, node.parent * 6, local, 0)
+  }
+  const first = nodes.length * 6
+  for (let n = 0; n < skin.bones.length; n++) {
+    const bone = skin.bones[n]
+    const at = n * 6
+    if (bone.parent < 0) {
+      compose(local, now[at], now[at + 1], now[at + 2], now[at + 3], now[at + 4])
+      rig.locals.set(local, at)
+      if (bone.node !== undefined && bone.node >= 0) multiply(worlds, first + at, worlds, bone.node * 6, local, 0)
+      else multiply(worlds, first + at, bone.parentWorld || parentWorld, 0, local, 0)
+    } else {
+      compose(local, now[bone.parent * 6 + 5], 0, now[at + 2], now[at + 3], now[at + 4])
+      rig.locals.set(local, at)
+      multiply(worlds, first + at, worlds, first + bone.parent * 6, local, 0)
+    }
+  }
+  if (skin.ik && skin.ik.length) bend(rig, first)
+}
+
+/** @type {number[]} The bones of the chain being solved, the top one first */
+const CHAIN = []
+
+/**
+ * The world a root bone sits in, into `PARENT`.
+ *
+ * @param {Rig}    rig
+ * @param {number} index the root bone
+ */
+function rootWorld(rig, index) {
+  const bone = rig.skin.bones[index]
+  if (bone.node !== undefined && bone.node >= 0) {
+    for (let m = 0; m < 6; m++) PARENT[m] = rig.worlds[bone.node * 6 + m]
+    return
+  }
+  const world = bone.parentWorld || rig.skin.parentWorld || IDENTITY
+  for (let m = 0; m < 6; m++) PARENT[m] = world[m]
+}
+
+/**
+ * Solves the IK constraints over bones already posed, and moves the bones
+ * below each chain with it. A chain longer than the solver holds keeps the
+ * pose the bones' own values give it.
+ *
+ * @param {Rig}    rig
+ * @param {number} first where the bones' worlds start in `rig.worlds`
+ */
+function bend(rig, first) {
+  const { skin, now, worlds, locals, moved } = rig
+  const bones = skin.bones
+  const links = /** @type {Ik[]} */ (skin.ik)
+  for (let n = 0; n < bones.length; n++) moved[n] = 0
+  for (let k = 0; k < links.length; k++) {
+    const link = links[k]
+    let length = 1
+    let top = link.tip
+    while (length < link.count && bones[top].parent >= 0) {
+      top = bones[top].parent
+      length++
+    }
+    if (length > MAX_CHAIN) continue
+    for (let at = length - 1, bone = link.tip; at >= 0; at--, bone = bones[bone].parent) {
+      CHAIN[at] = bone
+      for (let m = 0; m < 6; m++) LOCALS[at * 6 + m] = locals[bone * 6 + m]
+    }
+    if (bones[top].parent >= 0) for (let m = 0; m < 6; m++) PARENT[m] = worlds[first + bones[top].parent * 6 + m]
+    else rootWorld(rig, top)
+
+    const own = rig.ikAt + k * 3
+    const space = link.space || IDENTITY
+    const x = now[own + 1]
+    const y = now[own + 2]
+    solve(length, now[link.tip * 6 + 5], space[0] * x + space[2] * y + space[4], space[1] * x + space[3] * y + space[5], !!link.invert, now[own])
+    for (let at = 0; at < length; at++) {
+      for (let m = 0; m < 6; m++) worlds[first + CHAIN[at] * 6 + m] = WORLDS[(at + 1) * 6 + m]
+      moved[CHAIN[at]] = 1
+    }
+  }
+  for (let n = 0; n < bones.length; n++) {
+    const parent = bones[n].parent
+    if (moved[n] || parent < 0 || !moved[parent]) continue
+    multiply(worlds, first + n * 6, worlds, first + parent * 6, locals, n * 6)
+    moved[n] = 1
+  }
+}
+
+/**
+ * Where a point goes: the skin transform first, then the weighted sum of its
+ * tendons' matrices (`Weight::deform`). The result is `rig.point`.
+ *
+ * @param {Rig}        rig
+ * @param {number[][]} weights `[tendonIndex, weight]` pairs
+ * @param {number}     x
+ * @param {number}     y
+ */
+function place(rig, weights, x, y) {
+  const skin = rig.skin.skin || IDENTITY
+  const px = skin[0] * x + skin[2] * y + skin[4]
+  const py = skin[1] * x + skin[3] * y + skin[5]
+  const tendons = rig.tendons
+  const count = rig.skin.tendons.length
+  let rx = 0
+  let ry = 0
+  for (let n = 0; n < weights.length; n++) {
+    const tendon = weights[n][0]
+    const weight = weights[n][1]
+    // -1, or an index past the tendons, is Rive's tendon 0: the identity
+    if (tendon < 0 || tendon >= count) {
+      rx += px * weight
+      ry += py * weight
+    } else {
+      const at = tendon * 6
+      rx += (tendons[at] * px + tendons[at + 2] * py + tendons[at + 4]) * weight
+      ry += (tendons[at + 1] * px + tendons[at + 3] * py + tendons[at + 5]) * weight
+    }
+  }
+  rig.point[0] = rx
+  rig.point[1] = ry
+}
+
+/**
+ * Natural rounding's control point distance for a corner (`Path::computeIdealControlPointDistance`).
+ *
+ * @param {number} cross
+ * @param {number} dot
+ * @param {number} radius
+ */
+function idealDistance(cross, dot, radius) {
+  const angle = Math.abs(Math.atan2(cross, dot))
+  const factor = angle < Math.PI / 2 ? 1 + Math.cos(angle) : 2 - Math.sin(angle)
+  return Math.min(radius, (4 / 3) * Math.tan(angle / 4) * radius * factor)
+}
+
+/**
+ * Deforms the skin with the values in `rig.now`, into a path (`rig.path`
+ * unless one made by `createPath` is given): each vertex
+ * is moved in world space, the corners of vertices with a radius are rounded
+ * there (Rive rounds the vertices' render positions, which the skin has
+ * moved), and the space takes the result to the Lottie group.
+ *
+ * @param   {Rig}        rig
+ * @param   {LottiePath} [path]
+ * @returns {LottiePath}
+ */
+export function deformRig(rig, path = rig.path) {
+  const { skin, now, world, space } = rig
+  const count = skin.vertices.length
+  computeWorlds(rig)
+  const first = (skin.nodes || []).length * 6
+  for (let n = 0; n < skin.tendons.length; n++) {
+    const tendon = skin.tendons[n]
+    if (tendon.bone >= 0 && tendon.bone < skin.bones.length) multiply(rig.tendons, n * 6, rig.worlds, first + tendon.bone * 6, tendon.bind || IDENTITY, 0)
+    else rig.tendons.set(IDENTITY, n * 6)
+  }
+
+  // the space: the skin's, or the inverse of the live world of the node the group sits in
+  if (skin.spaceNode !== undefined && skin.spaceNode >= 0) {
+    const at = skin.spaceNode * 6
+    const w = rig.worlds
+    const det = w[at] * w[at + 3] - w[at + 2] * w[at + 1]
+    const inverse = det === 0 ? 0 : 1 / det
+    space[0] = w[at + 3] * inverse
+    space[1] = -w[at + 1] * inverse
+    space[2] = -w[at + 2] * inverse
+    space[3] = w[at] * inverse
+    space[4] = (w[at + 2] * w[at + 5] - w[at + 3] * w[at + 4]) * inverse
+    space[5] = (w[at + 1] * w[at + 4] - w[at] * w[at + 5]) * inverse
+  } else {
+    space.set(skin.space || IDENTITY)
+  }
+
+  // each vertex, and its handles as offsets from it, in world space
+  for (let n = 0; n < count; n++) {
+    const vertex = skin.vertices[n]
+    const at = rig.vertexAt + n * 7
+    const to = n * 6
+    const w = vertex.w
+    if (!w || !w.length) {
+      // a vertex with no weight is drawn where it is, in world space
+      for (let k = 0; k < 6; k++) world[to + k] = now[at + k]
+      continue
+    }
+    place(rig, w, now[at], now[at + 1])
+    const vx = rig.point[0]
+    const vy = rig.point[1]
+    world[to] = vx
+    world[to + 1] = vy
+    // a handle is deformed as the point vertex + offset, with its own weights, and offset again from the deformed vertex
+    place(rig, vertex.iw || w, now[at] + now[at + 2], now[at + 1] + now[at + 3])
+    world[to + 2] = rig.point[0] - vx
+    world[to + 3] = rig.point[1] - vy
+    place(rig, vertex.ow || w, now[at] + now[at + 4], now[at + 1] + now[at + 5])
+    world[to + 4] = rig.point[0] - vx
+    world[to + 5] = rig.point[1] - vy
+  }
+
+  let k = 0
+  for (let n = 0; n < count; n++) {
+    const to = n * 6
+    if (skin.closed && skin.vertices[n].r !== undefined) {
+      k = round(rig, path, n, now[rig.vertexAt + n * 7 + 6], k)
+      continue
+    }
+    emit(path, k++, space, world[to], world[to + 1], world[to + 2], world[to + 3], world[to + 4], world[to + 5])
+  }
+  return path
+}
+
+/**
+ * Writes a point with its handles (offsets) through the space.
+ *
+ * @param {LottiePath}   path
+ * @param {number}       k
+ * @param {Float64Array} space
+ * @param {number}       x
+ * @param {number}       y
+ * @param {number}       ix
+ * @param {number}       iy
+ * @param {number}       ox
+ * @param {number}       oy
+ */
+function emit(path, k, space, x, y, ix, iy, ox, oy) {
+  const v = path.v[k]
+  const i = path.i[k]
+  const o = path.o[k]
+  v[0] = space[0] * x + space[2] * y + space[4]
+  v[1] = space[1] * x + space[3] * y + space[5]
+  i[0] = space[0] * ix + space[2] * iy
+  i[1] = space[1] * ix + space[3] * iy
+  o[0] = space[0] * ox + space[2] * oy
+  o[1] = space[1] * ox + space[3] * oy
+}
+
+/**
+ * Rounds the corner at vertex `n` into two points, as `Path::buildPath`
+ * does: the corner is rounded against the points the neighbouring curves
+ * leave from (the previous vertex's out handle, the next vertex's in handle),
+ * by at most half of each side. A negative radius turns the fillet inside out.
+ * Both points are always written, so a path keeps its number of points
+ * whatever the radius is.
+ *
+ * @param   {Rig}        rig
+ * @param   {LottiePath} path
+ * @param   {number}     n
+ * @param   {number}     radius
+ * @param   {number}     k      the first point of the output to write
+ * @returns {number}            the next point
+ */
+function round(rig, path, n, radius, k) {
+  const { world, space } = rig
+  const count = rig.skin.vertices.length
+  const pos = n * 6
+  const prev = ((n + count - 1) % count) * 6
+  const next = ((n + 1) % count) * 6
+  const x = world[pos]
+  const y = world[pos + 1]
+  const prevX = world[prev] + world[prev + 4] - x
+  const prevY = world[prev + 1] + world[prev + 5] - y
+  const nextX = world[next] + world[next + 2] - x
+  const nextY = world[next + 1] + world[next + 3] - y
+  const prevLength = Math.sqrt(prevX * prevX + prevY * prevY)
+  const nextLength = Math.sqrt(nextX * nextX + nextY * nextY)
+  // a side of no length rounds by nothing, as Rive's zero-length normalize leaves it
+  const ux = prevLength === 0 ? 0 : prevX / prevLength
+  const uy = prevLength === 0 ? 0 : prevY / prevLength
+  const vx = nextLength === 0 ? 0 : nextX / nextLength
+  const vy = nextLength === 0 ? 0 : nextY / nextLength
+  const rendered = Math.min(prevLength / 2, nextLength / 2, Math.abs(radius))
+  const ideal = idealDistance(ux * vy - uy * vx, ux * vx + uy * vy, rendered)
+  const reach = rendered - ideal
+
+  const inX = x + ux * rendered
+  const inY = y + uy * rendered
+  const outX = x + vx * rendered
+  const outY = y + vy * rendered
+  let ox = x + ux * reach
+  let oy = y + uy * reach
+  let ix = x + vx * reach
+  let iy = y + vy * reach
+  if (radius < 0) {
+    // rotatePoints: the handles turn twice the corner's angle about the points the fillet starts and ends at
+    const angle = Math.atan2((inX - outX) * (y - outY) - (inY - outY) * (x - outX), (inX - outX) * (x - outX) + (inY - outY) * (y - outY))
+    const s = Math.sin(angle * 2)
+    const c = Math.cos(angle * 2)
+    const dx = ox - inX
+    const dy = oy - inY
+    ox = dx * c - dy * s + inX
+    oy = dx * s + dy * c + inY
+    const ex = ix - outX
+    const ey = iy - outY
+    ix = ex * c + ey * s + outX
+    iy = -ex * s + ey * c + outY
+  }
+  emit(path, k, space, inX, inY, 0, 0, ox - inX, oy - inY)
+  emit(path, k + 1, space, outX, outY, ix - outX, iy - outY, 0, 0)
+  return k + 2
+}
+
+/**
+ * The skin's path for a set of bone values, as a fresh rig makes it: a
+ * convenience for a one-off deform. Each value of `poses` is a bone's `x`,
+ * `y`, `rotation`, `scaleX`, `scaleY` or `length`; the setup stays where it
+ * is not given. A caller deforming often keeps a rig instead.
+ *
+ * @param   {Skin}                          skin
+ * @param   {Array<Record<string, number>>} poses per bone
+ * @param   {Array<Record<string, number>> | { nodes?: Array<Record<string, number>>, vertices?: Array<Record<string, number>>, ik?: Array<Record<string, number>> }} [more] IK constraint values (`strength`, `x`, `y`), or node, vertex and IK values likewise
+ * @returns {LottiePath}
+ */
+export function deform(skin, poses, more) {
+  const rig = createRig(skin)
+  /** @param {Array<Record<string, number>> | undefined} list @param {Record<string, number>} channels @param {number} at @param {number} width */
+  const apply = (list, channels, at, width) => {
+    if (!list) return
+    for (let n = 0; n < list.length; n++) for (const name in list[n]) rig.now[at + n * width + channels[name]] = list[n][name]
+  }
+  apply(poses, BONE_CHANNELS, 0, 6)
+  if (Array.isArray(more)) apply(more, IK_CHANNELS, rig.ikAt, 3)
+  else if (more) {
+    apply(more.ik, IK_CHANNELS, rig.ikAt, 3)
+    apply(more.nodes, NODE_CHANNELS, rig.nodeAt, 5)
+    apply(more.vertices, VERTEX_CHANNELS, rig.vertexAt, 7)
+  }
+  return deformRig(rig)
+}