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

package/script/rive/api/draw/draw.paint.js

@@ -0,0 +1,235 @@
+/**
+ * Rive's `Paint` (how a path is filled or stroked) and `Gradient`. A paint
+ * is mutable; the renderer copies it when a path is drawn, so a script can
+ * change one between draws.
+ */
+
+import { LuaTable, NativeFunction, Vector, fail } from '../../../luau/vm/vm.value.js'
+import { decodeUtf8 } from '../../../luau/luau.convert.js'
+import { defineType, badArg, num, wrapped } from '../api.type.js'
+import { Mat2D } from '../math/math.mat2d.js'
+import { channels } from '../math/math.color.js'
+
+/**
+ * @typedef {object} Stop
+ * @property {number} position  0 to 1
+ * @property {number} color     ARGB
+ */
+
+/**
+ * @typedef {object} GradientData
+ * @property {'linear' | 'radial'} kind
+ * @property {number[]} from    [x, y]: the start of a linear gradient, the centre of a radial one
+ * @property {number[]} [to]    [x, y]: the end of a linear one
+ * @property {number}   [radius]
+ * @property {Stop[]}   stops
+ */
+
+/**
+ * @typedef {object} PaintData
+ * @property {'fill' | 'stroke'} style
+ * @property {number} color        ARGB
+ * @property {number} thickness
+ * @property {string} join         miter, round, bevel
+ * @property {string} cap          butt, round, square
+ * @property {string} blendMode
+ * @property {number} feather
+ * @property {GradientData | null} gradient
+ * @property {number[] | null} gradientTransform
+ */
+
+const STYLES = [ 'fill', 'stroke' ]
+const JOINS = [ 'miter', 'round', 'bevel' ]
+const CAPS = [ 'butt', 'round', 'square' ]
+const BLENDS = [ 'srcOver', 'additive', 'screen', 'overlay', 'darken', 'lighten', 'colorDodge', 'colorBurn', 'hardLight', 'softLight', 'difference', 'exclusion', 'multiply', 'hue', 'saturation', 'color', 'luminosity' ]
+
+/** @returns {PaintData} */
+export function defaultPaint() {
+  return { style: 'fill', color: 0xff000000, thickness: 1, join: 'miter', cap: 'butt', blendMode: 'srcOver', feather: 0, gradient: null, gradientTransform: null }
+}
+
+/**
+ * @param   {string}   name
+ * @param   {string[]} allowed
+ * @returns {{ get: (h: any) => any, set: (h: any, v: any) => void }}
+ */
+function choice(name, allowed) {
+  return {
+    get: (h) => h[name],
+    set: (h, v) => {
+      const s = typeof v === 'string' ? decodeUtf8(v) : ''
+      if (allowed.indexOf(s) < 0) throw fail("invalid Paint." + name + ' (' + allowed.join(', ') + ' expected)')
+      h[name] = s
+    },
+  }
+}
+
+/**
+ * @param   {string} name
+ * @returns {{ get: (h: any) => any, set: (h: any, v: any) => void }}
+ */
+function numeric(name) {
+  return {
+    get: (h) => h[name],
+    set: (h, v) => {
+      if (typeof v !== 'number') throw fail('Paint.' + name + ' must be a number')
+      h[name] = v
+    },
+  }
+}
+
+export const Gradient = defineType('Gradient', {})
+
+export const Paint = defineType('Paint', {
+  fields: {
+    style: choice('style', STYLES),
+    join: choice('join', JOINS),
+    cap: choice('cap', CAPS),
+    blendMode: choice('blendMode', BLENDS),
+    color: numeric('color'),
+    thickness: numeric('thickness'),
+    feather: numeric('feather'),
+    gradient: {
+      get: (h) => (h.gradient ? Gradient.wrap(h.gradient) : undefined),
+      set: (h, v) => {
+        h.gradient = v === undefined ? null : wrapped([ v ], 0, Gradient, 'gradient')
+      },
+    },
+    gradientTransform: {
+      get: (h) => (h.gradientTransform ? Mat2D.wrap(h.gradientTransform.slice()) : undefined),
+      set: (h, v) => {
+        h.gradientTransform = v === undefined ? null : wrapped([ v ], 0, Mat2D, 'gradientTransform').slice()
+      },
+    },
+  },
+  methods: {
+    copy: (h, args) => applyDefinition(copyPaint(h), args[1]),
+  },
+})
+
+/**
+ * @param   {PaintData} h
+ * @returns {PaintData}
+ */
+function copyPaint(h) {
+  return { style: h.style, color: h.color, thickness: h.thickness, join: h.join, cap: h.cap, blendMode: h.blendMode, feather: h.feather, gradient: h.gradient, gradientTransform: h.gradientTransform }
+}
+
+/**
+ * Sets the fields a definition table names.
+ *
+ * @param   {PaintData} h
+ * @param   {any}       def  a table of fields, or nil
+ * @returns {any}       the paint, wrapped
+ */
+function applyDefinition(h, def) {
+  const w = Paint.wrap(h)
+  if (def === undefined) return w
+  if (!(def instanceof LuaTable)) throw badArg(0, 'Paint.with', 'table', [ def ])
+  for (let pos = 0, next = def.advance(pos); next !== null; next = def.advance(pos)) {
+    pos = next
+    const key = typeof def.ck === 'string' ? def.ck : ''
+    if (key === '') continue
+    // the metatable's __newindex validates each field
+    const setter = /** @type {LuaTable} */ (Paint.meta).getStr('__newindex')
+    if (setter instanceof NativeFunction) setter.fn(null, [ w, key, def.cv ])
+  }
+  return w
+}
+
+/**
+ * @param   {any} t  a table of `{ position, color }`
+ * @returns {Stop[]}
+ */
+function stopsOf(t) {
+  if (!(t instanceof LuaTable)) throw badArg(2, 'Gradient', 'table of stops', [ undefined, undefined, t ])
+  /** @type {Stop[]} */
+  const stops = []
+  for (let n = 1; n <= t.length(); n++) {
+    const s = t.get(n)
+    if (!(s instanceof LuaTable)) throw fail('Gradient stop ' + n + ' must be a table')
+    const position = s.getStr('position')
+    const color = s.getStr('color')
+    if (typeof position !== 'number' || typeof color !== 'number') throw fail('Gradient stop ' + n + ' needs a position and a color')
+    stops.push({ position, color })
+  }
+  return stops
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i
+ * @param   {string} fname
+ * @returns {number[]}
+ */
+function point(args, i, fname) {
+  const v = args[i]
+  if (!(v instanceof Vector)) throw badArg(i, fname, 'Vector', args)
+  return [ v.x, v.y ]
+}
+
+/** @type {Record<string, (args: any[]) => any>} */
+const PAINT_STATICS = {
+  new: () => Paint.wrap(defaultPaint()),
+  with: (a) => applyDefinition(defaultPaint(), a[0]),
+}
+
+/** @type {Record<string, (args: any[]) => any>} */
+const GRADIENT_STATICS = {
+  linear: (a) => Gradient.wrap({ kind: 'linear', from: point(a, 0, 'linear'), to: point(a, 1, 'linear'), stops: stopsOf(a[2]) }),
+  radial: (a) => Gradient.wrap({ kind: 'radial', from: point(a, 0, 'radial'), radius: num(a, 1, 'radial'), stops: stopsOf(a[2]) }),
+}
+
+/**
+ * @param   {string} prefix
+ * @param   {Record<string, (args: any[]) => any>} fns
+ * @returns {LuaTable}
+ */
+function table(prefix, fns) {
+  const t = new LuaTable()
+  for (const name in fns) {
+    const fn = fns[name]
+    t.set(name, new NativeFunction(prefix + '.' + name, function (vm, args) {
+      return fn(args)
+    }))
+  }
+  return t
+}
+
+/**
+ * Installs the `Paint` and `Gradient` globals.
+ *
+ * @param {import('../../../luau/vm/vm.js').VM} vm
+ */
+export function installPaint(vm) {
+  vm.globals.set('Paint', table('Paint', PAINT_STATICS))
+  vm.globals.set('Gradient', table('Gradient', GRADIENT_STATICS))
+}
+
+/**
+ * A paint as the plain record a drawing carries.
+ *
+ * @param   {PaintData} h
+ * @param   {number}    [modulate]  a colour the renderer multiplies in (ARGB)
+ * @returns {{ style: string, color: number, rgba: number[], thickness: number, join: string, cap: string, blendMode: string, feather: number, gradient: GradientData | null, gradientTransform: number[] | null }}
+ */
+export function snapshotPaint(h, modulate) {
+  const ch = channels(h.color)
+  if (modulate !== undefined && modulate !== 0xffffffff) {
+    const m = channels(modulate)
+    for (let i = 0; i < 4; i++) ch[i] = Math.round((ch[i] * m[i]) / 255)
+  }
+  const color = ch[3] * 16777216 + ch[0] * 65536 + ch[1] * 256 + ch[2]
+  return {
+    style: h.style,
+    color,
+    rgba: [ ch[0] / 255, ch[1] / 255, ch[2] / 255, ch[3] / 255 ],
+    thickness: h.thickness,
+    join: h.join,
+    cap: h.cap,
+    blendMode: h.blendMode,
+    feather: h.feather,
+    gradient: h.gradient,
+    gradientTransform: h.gradientTransform ? h.gradientTransform.slice() : null,
+  }
+}

package/script/rive/api/draw/draw.path.js

@@ -0,0 +1,153 @@
+/**
+ * Rive's `Path` (and the `PathData` a path effect receives, which is the same
+ * thing here): a list of drawing commands a script builds with `moveTo`,
+ * `lineTo`, `quadTo`, `cubicTo` and `close`. It reads as an array of
+ * `PathCommand`s too (`#path`, `path[i]`, `ipairs`), each a table with a `type`
+ * and its points as vectors, which the wrapper keeps in step with the commands.
+ */
+
+import { LuaTable, NativeFunction, Vector, fail } from '../../../luau/vm/vm.value.js'
+import { Wrapped, defineType, wrapped } from '../api.type.js'
+import { Mat2D, apply } from '../math/math.mat2d.js'
+import { vec } from '../math/math.vector.js'
+import { commandsToContours, contoursToCommands } from './draw.contours.js'
+import { measureOf } from './draw.measure.js'
+
+/** @import { Command, Contour } from './draw.contours.js' */
+
+/** @typedef {{ cmds: Command[], wrapper: Wrapped | null }} PathData */
+
+/**
+ * @param   {Command} cmd
+ * @returns {LuaTable} the `PathCommand` a script sees
+ */
+function commandTable(cmd) {
+  const t = new LuaTable()
+  t.set('type', cmd.t)
+  const points = []
+  for (let i = 0; i < cmd.p.length; i += 2) points.push(new Vector(cmd.p[i], cmd.p[i + 1], 0))
+  t.setRange(1, points, 0, points.length)
+  return t
+}
+
+/**
+ * Appends a command to a path and its wrapper's array.
+ *
+ * @param {Wrapped}  w
+ * @param {Command}  cmd
+ */
+function push(w, cmd) {
+  w.host.cmds.push(cmd)
+  w.set(w.host.cmds.length, commandTable(cmd))
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} first  the index of the first Vector argument
+ * @param   {number} n      how many vectors
+ * @param   {string} fname
+ * @returns {number[]} their x, y flattened
+ */
+function points(args, first, n, fname) {
+  const out = []
+  for (let k = 0; k < n; k++) {
+    const v = vec(args, first + k, fname)
+    out.push(v.x, v.y)
+  }
+  return out
+}
+
+/**
+ * @param {any}       dest  the Path a script passed to `extract`
+ * @param {Command[]} cmds
+ */
+function append(dest, cmds) {
+  const w = dest instanceof Wrapped && Path.is(dest) ? dest : null
+  if (!w) throw fail("invalid argument #3 to 'extract' (Path expected)")
+  for (let n = 0; n < cmds.length; n++) push(w, cmds[n])
+}
+
+/** The Lua type; `args[0]` is the wrapper in a method */
+export const Path = defineType('Path', {
+  methods: {
+    moveTo: (h, args) => push(h.wrapper, { t: 'moveTo', p: points(args, 1, 1, 'moveTo') }),
+    lineTo: (h, args) => push(h.wrapper, { t: 'lineTo', p: points(args, 1, 1, 'lineTo') }),
+    quadTo: (h, args) => push(h.wrapper, { t: 'quadTo', p: points(args, 1, 2, 'quadTo') }),
+    cubicTo: (h, args) => push(h.wrapper, { t: 'cubicTo', p: points(args, 1, 3, 'cubicTo') }),
+    close: (h) => push(h.wrapper, { t: 'close', p: [] }),
+    reset: (h) => {
+      h.cmds.length = 0
+      const w = h.wrapper
+      w.arr.length = 0
+    },
+    add: (h, args) => {
+      const other = wrapped(args, 1, Path, 'add')
+      const m = args[2] === undefined ? null : wrapped(args, 2, Mat2D, 'add')
+      // a path added to itself adds what it held
+      const source = other.cmds.slice()
+      for (let n = 0; n < source.length; n++) push(h.wrapper, m ? transformCommand(source[n], m) : source[n])
+    },
+    contours: (h) => measureOf(commandsToContours(h.cmds), true, append),
+    measure: (h) => measureOf(commandsToContours(h.cmds), false, append),
+  },
+})
+
+/**
+ * @param   {Command}  cmd
+ * @param   {number[]} m
+ * @returns {Command}
+ */
+function transformCommand(cmd, m) {
+  const p = []
+  for (let i = 0; i < cmd.p.length; i += 2) {
+    const q = apply(m, cmd.p[i], cmd.p[i + 1])
+    p.push(q[0], q[1])
+  }
+  return { t: cmd.t, p }
+}
+
+/**
+ * A new empty path.
+ *
+ * @param   {Command[]} [cmds]  commands to start with
+ * @returns {Wrapped}
+ */
+export function newPath(cmds) {
+  /** @type {PathData} */
+  const host = { cmds: [], wrapper: null }
+  const w = Path.wrap(host)
+  host.wrapper = w
+  if (cmds) for (let n = 0; n < cmds.length; n++) push(w, cmds[n])
+  return w
+}
+
+/**
+ * @param   {Contour[]} contours  Lottie vertex arrays
+ * @returns {Wrapped}
+ */
+export function pathFromContours(contours) {
+  return newPath(contoursToCommands(contours))
+}
+
+/**
+ * @param   {any} v  a value a script returned
+ * @returns {Command[] | undefined} its commands when it is a path
+ */
+export function commandsOf(v) {
+  const h = Path.unwrap(v)
+  return h === undefined ? undefined : h.cmds
+}
+
+/**
+ * Installs the `Path` global.
+ *
+ * @param {import('../../../luau/vm/vm.js').VM} vm
+ */
+export function installPath(vm) {
+  const table = new LuaTable()
+  table.set('new', new NativeFunction('Path.new', function () {
+    return newPath()
+  }))
+  vm.globals.set('Path', table)
+}
+

package/script/rive/api/draw/draw.renderer.js

@@ -0,0 +1,117 @@
+/**
+ * Rive's `Renderer` as a recorder: the script's `draw(self, renderer)` calls
+ * land in a list of drawings, each a path as Lottie vertex arrays under the
+ * transform, clips and opacity in force when it was drawn, with a copy of the
+ * paint. A player turns the list into shapes (a group with the path, a fill or
+ * stroke, and the clips as masks).
+ */
+
+import { Mat2D, identity, multiply } from '../math/math.mat2d.js'
+import { defineType, wrapped, num } from '../api.type.js'
+import { channels } from '../math/math.color.js'
+import { Paint, snapshotPaint } from './draw.paint.js'
+import { Path } from './draw.path.js'
+import { commandsToContours, transformContours } from './draw.contours.js'
+import { drawImage, drawImageMesh } from '../media/media.draw.js'
+
+/** @import { Contour } from './draw.contours.js' */
+
+/**
+ * Also in the list, from other APIs: `{ kind: 'image' }` (media/media.draw.js), `{ kind: 'text' }` (text/text.js) and `{ kind: 'artboard' }` (artboard/artboard.js).
+ *
+ * @typedef {object} Drawing
+ * @property {'path'} kind
+ * @property {Contour[]} path        vertex arrays with the transform already applied
+ * @property {number[]}  transform   the matrix that was in force, [xx, xy, yx, yy, tx, ty]
+ * @property {Contour[][]} clips     the clip paths in force, each transformed
+ * @property {number}    opacity     0 to 1, from `modulateOpacity`
+ * @property {ReturnType<typeof snapshotPaint>} paint
+ */
+
+/**
+ * @typedef {object} RenderState
+ * @property {number[]}    m
+ * @property {Contour[][]} clips
+ * @property {number}      opacity
+ * @property {number}      color    the colour modulation, ARGB
+ */
+
+/** What a `draw` call records; the host keeps one and `reset`s it for each frame */
+export class Recorder {
+  /** @param {any[]} [into]  a list to fill instead of a new one (it is emptied) */
+  reset(into) {
+    if (into) into.length = 0
+    this.drawings = into || []
+    this.state.m = identity()
+    this.state.clips = []
+    this.state.opacity = 1
+    this.state.color = 0xffffffff
+    this.stack.length = 0
+  }
+
+  constructor() {
+    /** @type {any[]} */
+    this.drawings = []
+    /** @type {RenderState} */
+    this.state = { m: identity(), clips: [], opacity: 1, color: 0xffffffff }
+    /** @type {RenderState[]} */
+    this.stack = []
+  }
+}
+
+/**
+ * @param   {number} a  ARGB
+ * @param   {number} b  ARGB
+ * @returns {number}    the channel-wise product
+ */
+function modulate(a, b) {
+  const p = channels(a)
+  const q = channels(b)
+  return Math.round((p[3] * q[3]) / 255) * 16777216 + Math.round((p[0] * q[0]) / 255) * 65536 + Math.round((p[1] * q[1]) / 255) * 256 + Math.round((p[2] * q[2]) / 255)
+}
+
+export const Renderer = defineType('Renderer', {
+  methods: {
+    save: (r) => {
+      r.stack.push({ m: r.state.m, clips: r.state.clips, opacity: r.state.opacity, color: r.state.color })
+    },
+    restore: (r) => {
+      const s = r.stack.pop()
+      if (s) r.state = s
+    },
+    transform: (r, args) => {
+      r.state = { m: multiply(r.state.m, wrapped(args, 1, Mat2D, 'transform')), clips: r.state.clips, opacity: r.state.opacity, color: r.state.color }
+    },
+    modulateOpacity: (r, args) => {
+      r.state = { m: r.state.m, clips: r.state.clips, opacity: r.state.opacity * num(args, 1, 'modulateOpacity'), color: r.state.color }
+    },
+    modulateColor: (r, args) => {
+      r.state = { m: r.state.m, clips: r.state.clips, opacity: r.state.opacity, color: modulate(r.state.color, num(args, 1, 'modulateColor')) }
+    },
+    setColorModulation: (r, args) => {
+      r.state = { m: r.state.m, clips: r.state.clips, opacity: r.state.opacity, color: num(args, 1, 'setColorModulation') }
+    },
+    clipPath: (r, args) => {
+      const path = wrapped(args, 1, Path, 'clipPath')
+      r.state = { m: r.state.m, clips: r.state.clips.concat([ commandsToContours(path.cmds, r.state.m) ]), opacity: r.state.opacity, color: r.state.color }
+    },
+    drawPath: (r, args) => {
+      const path = wrapped(args, 1, Path, 'drawPath')
+      const paint = wrapped(args, 2, Paint, 'drawPath')
+      const s = r.state
+      r.drawings.push({
+        kind: 'path',
+        path: transformContours(commandsToContours(path.cmds), s.m),
+        transform: s.m.slice(),
+        clips: s.clips,
+        opacity: s.opacity,
+        paint: snapshotPaint(paint, s.color),
+      })
+    },
+    // images are recorded (media/media.draw.js); text and artboards draw themselves into the same list
+    drawImage: (r, args) => drawImage(r, args),
+    drawImageMesh: (r, args) => drawImageMesh(r, args),
+    // instances carry a MeshInstances table this recorder has no use for
+    drawImageMeshInstanced: () => {},
+  },
+})

package/script/rive/api/math/math.color.js

@@ -0,0 +1,96 @@
+/**
+ * Rive's `Color`: an ARGB packed into one unsigned number (`0xAARRGGBB`),
+ * as a view-model colour property holds it. The constructors keep the low 8
+ * bits of each channel.
+ */
+
+import { LuaTable, NativeFunction } from '../../../luau/vm/vm.value.js'
+import { num, optNum } from '../api.type.js'
+
+/**
+ * @param   {number} r
+ * @param   {number} g
+ * @param   {number} b
+ * @param   {number} a
+ * @returns {number}
+ */
+export function argb(r, g, b, a) {
+  return (a & 255) * 16777216 + ((r & 255) << 16) + ((g & 255) << 8) + (b & 255)
+}
+
+/**
+ * @param   {number} c
+ * @returns {number[]} [r, g, b, a], each 0 to 255
+ */
+export function channels(c) {
+  const n = c % 4294967296
+  return [ (n >>> 16) & 255, (n >>> 8) & 255, n & 255, Math.floor(n / 16777216) & 255 ]
+}
+
+/**
+ * @param   {number} c
+ * @returns {number[]} [r, g, b, a], each 0 to 1
+ */
+export function colorFloats(c) {
+  const ch = channels(c)
+  return [ ch[0] / 255, ch[1] / 255, ch[2] / 255, ch[3] / 255 ]
+}
+
+/**
+ * @param   {number} index  0 red, 1 green, 2 blue, 3 alpha
+ * @returns {(args: any[]) => any}
+ */
+function channelFn(index) {
+  const name = [ 'red', 'green', 'blue', 'alpha' ][index]
+  return function (args) {
+    const ch = channels(num(args, 0, name))
+    if (args[1] === undefined) return ch[index]
+    ch[index] = num(args, 1, name) & 255
+    return argb(ch[0], ch[1], ch[2], ch[3])
+  }
+}
+
+/** @type {Record<string, (args: any[]) => any>} */
+const FNS = {
+  rgb: (a) => argb(num(a, 0, 'rgb'), num(a, 1, 'rgb'), num(a, 2, 'rgb'), 255),
+  rgba: (a) => argb(num(a, 0, 'rgba'), num(a, 1, 'rgba'), num(a, 2, 'rgba'), num(a, 3, 'rgba')),
+  lerp: (a) => {
+    const p = channels(num(a, 0, 'lerp'))
+    const q = channels(num(a, 1, 'lerp'))
+    const t = num(a, 2, 'lerp')
+    const m = []
+    for (let i = 0; i < 4; i++) m.push(Math.round(p[i] + (q[i] - p[i]) * t))
+    return argb(m[0], m[1], m[2], m[3])
+  },
+  red: channelFn(0),
+  green: channelFn(1),
+  blue: channelFn(2),
+  alpha: channelFn(3),
+  opacity: (a) => {
+    const ch = channels(num(a, 0, 'opacity'))
+    if (a[1] === undefined) return ch[3] / 255
+    return argb(ch[0], ch[1], ch[2], Math.round(Math.max(0, Math.min(1, optNum(a, 1, 'opacity', 1))) * 255))
+  },
+  toFloat: (a) => {
+    const t = new LuaTable()
+    const f = colorFloats(num(a, 0, 'toFloat'))
+    t.setRange(1, f, 0, 4)
+    return t
+  },
+}
+
+/**
+ * Installs the `Color` global.
+ *
+ * @param {import('../../../luau/vm/vm.js').VM} vm
+ */
+export function installColor(vm) {
+  const color = new LuaTable()
+  for (const name in FNS) {
+    const fn = FNS[name]
+    color.set(name, new NativeFunction('Color.' + name, function (vm2, args) {
+      return fn(args)
+    }))
+  }
+  vm.globals.set('Color', color)
+}