@swf2es/player 0.0.0-stage → 0.1.0

package/src/playerglobal/flash/geom/PerspectiveProjection.ts

@@ -0,0 +1,162 @@
+// flash.geom.PerspectiveProjection: a field of view and a centre, of its
+// own or, got from a Transform, of its display object, which it then
+// reads and writes. The stage and each SWF's root always have one, back to
+// their defaults when set to null. What is in a display object with one
+// is drawn through it (display/perspective.ts).
+import { avm2 } from "@swf2es/runtime";
+import { type DisplayObject, type Projection, TRANSFORM } from "../../../display/display.js";
+import { defaultProjection, focalLengthOver as focalLength } from "../../../display/perspective.js";
+import type { Scripting } from "../../../scripting.js";
+
+type AsObject = avm2.AsObject;
+type Value = avm2.Value;
+
+const DEGREES_TO_RADIANS = Math.PI / 180;
+
+/** Whether `d` has a projection whatever a script sets: the stage, or a SWF's root. */
+export function alwaysProjects(s: Scripting, d: DisplayObject): boolean {
+  return d === s.stage || d.loaderInfo !== null;
+}
+
+/** The projection `d` has: its own, or the default the stage, a root, or a projection's reader falls back on. */
+function projectionOf(s: Scripting, d: DisplayObject): Projection {
+  if (d.projection) {
+    return d.projection;
+  }
+
+  const root = d !== s.stage && d.loaderInfo !== null;
+  return root
+    ? defaultProjection(s.stageWidth / 2, s.stageHeight / 2)
+    : defaultProjection(250, 250);
+}
+
+export function perspectiveProjectionNatives(s: Scripting): avm2.Natives {
+  const natives: avm2.Natives = {};
+
+  /** The stage's projection and one of its own measure 500 wide; any other object's, the stage's width. */
+  const width = (d: DisplayObject | null): number => (d && d !== s.stage ? s.stageWidth : 500);
+
+  const focalOf = (o: { $display: DisplayObject | null; $fieldOfView: number }): number =>
+    o.$display
+      ? focalLength(projectionOf(s, o.$display).fieldOfView, width(o.$display))
+      : focalLength(o.$fieldOfView * DEGREES_TO_RADIANS, 500);
+
+  class PerspectiveProjectionNatives {
+    declare $display: DisplayObject | null;
+    /** Its own field of view, in degrees, and centre, while it has no display object. */
+    declare $fieldOfView: number;
+    declare $centerX: number;
+    declare $centerY: number;
+
+    "flash.geom:PerspectiveProjection::ctor"(): void {
+      this.$display = null;
+      this.$fieldOfView = 55;
+      this.$centerX = 250;
+      this.$centerY = 250;
+    }
+
+    get fieldOfView(): number {
+      if (this.$display) {
+        return (projectionOf(s, this.$display).fieldOfView * 180) / Math.PI;
+      }
+
+      return this.$fieldOfView;
+    }
+
+    set fieldOfView(v: Value) {
+      const degrees = s.rt.toNumber(v);
+      if (!(degrees > 0 && degrees < 180)) {
+        throw s.rt.error("ArgumentError", 2182);
+      }
+
+      if (this.$display) {
+        update(this.$display, { fieldOfView: (degrees * Math.PI) / 180 });
+      } else {
+        this.$fieldOfView = degrees;
+      }
+    }
+
+    get focalLength(): number {
+      return focalOf(this);
+    }
+
+    set focalLength(v: Value) {
+      const length = s.rt.toNumber(v);
+      if (!(length > 0)) {
+        throw s.rt.error("ArgumentError", 2186, length);
+      }
+
+      const radians = Math.atan(width(this.$display) / 2 / length) * 2;
+      if (this.$display) {
+        update(this.$display, { fieldOfView: radians });
+      } else {
+        this.$fieldOfView = (radians * 180) / Math.PI;
+      }
+    }
+
+    get projectionCenter(): AsObject {
+      const p = this.$display ? projectionOf(s, this.$display) : null;
+      return s.rt.construct(
+        s.rt.classNamed("flash.geom::Point"),
+        p ? p.centerX : this.$centerX,
+        p ? p.centerY : this.$centerY,
+      ) as AsObject;
+    }
+
+    set projectionCenter(v: Value) {
+      if (v === null || v === undefined) {
+        throw s.rt.error("TypeError", 2007, "projectionCenter");
+      }
+
+      const point = v as AsObject;
+      const x = s.rt.toNumber(s.rt.getProperty(point, s.rt.publicName("x")));
+      const y = s.rt.toNumber(s.rt.getProperty(point, s.rt.publicName("y")));
+      if (this.$display) {
+        update(this.$display, { centerX: x, centerY: y });
+      } else {
+        this.$centerX = x;
+        this.$centerY = y;
+      }
+    }
+
+    toMatrix3D(): AsObject {
+      const length = focalOf(this);
+      const m = s.rt.construct(s.rt.classNamed("flash.geom::Matrix3D")) as AsObject;
+      (m.$matrix3D as Float32Array).set([length, 0, 0, 0, 0, length, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0]);
+      return m;
+    }
+  }
+
+  /** A change to a display object's projection, made from its current one. */
+  const update = (d: DisplayObject, change: Partial<Projection>): void => {
+    d.projection = { ...projectionOf(s, d), ...change };
+    d.invalidate(TRANSFORM);
+  };
+
+  avm2.registerNativeClass(
+    natives,
+    "flash.geom::PerspectiveProjection",
+    PerspectiveProjectionNatives,
+  );
+  return natives;
+}
+
+/** A PerspectiveProjection of `d`'s, which reads and writes `d`'s. */
+export function projectionObject(s: Scripting, d: DisplayObject): AsObject {
+  const o = s.rt.construct(s.rt.classNamed("flash.geom::PerspectiveProjection")) as AsObject;
+  o.$display = d;
+  return o;
+}
+
+/** What setting `o` on a transform gives: a copy of its values, in radians. */
+export function projectionFrom(s: Scripting, o: AsObject): Projection {
+  if (o.$display) {
+    return { ...projectionOf(s, o.$display) };
+  }
+
+  return {
+    fieldOfView: (o.$fieldOfView * Math.PI) / 180,
+    centerX: o.$centerX,
+    centerY: o.$centerY,
+  };
+}

package/src/playerglobal/flash/geom/Transform.ts

@@ -0,0 +1,335 @@
+// flash.geom.Transform: a display object's matrix and color transform as
+// flash.geom's Matrix and ColorTransform, copies each time, as Flash gives
+// them, and set from either; and its 3D transform, the object's own
+// Matrix3D, and perspective projection, kept and reported as Flash's, and
+// drawn in perspective (display/perspective.ts).
+import type { Matrix as Linear } from "@swf2es/format";
+import { avm2 } from "@swf2es/runtime";
+import { bounds, boundsIn } from "../../../display/bounds.js";
+import { type DisplayObject, TRANSFORM } from "../../../display/display.js";
+import { concat } from "../../../display/geometry.js";
+import {
+  determinant3D,
+  identity3D,
+  invert3D,
+  multiply3D,
+  type Raw,
+} from "../../../display/matrix3d.js";
+import type { Scripting } from "../../../scripting.js";
+import { alwaysProjects, projectionFrom, projectionObject } from "./PerspectiveProjection.js";
+
+type AsObject = avm2.AsObject;
+type Value = avm2.Value;
+
+const MATRIX = ["a", "b", "c", "d", "tx", "ty"] as const;
+const COLOR = [
+  ["rMul", "redMultiplier"],
+  ["gMul", "greenMultiplier"],
+  ["bMul", "blueMultiplier"],
+  ["aMul", "alphaMultiplier"],
+  ["rAdd", "redOffset"],
+  ["gAdd", "greenOffset"],
+  ["bAdd", "blueOffset"],
+  ["aAdd", "alphaOffset"],
+] as const;
+type Color = Record<(typeof COLOR)[number][0], number>;
+// Made once: a script reads and writes a transform on every frame.
+const MATRIX_NAMES = MATRIX.map((k) => avm2.qname(avm2.publicNs, k));
+const COLOR_NAMES = COLOR.map(([, name]) => avm2.qname(avm2.publicNs, name));
+const IDENTITY_COLOR: Color = {
+  rMul: 1,
+  gMul: 1,
+  bMul: 1,
+  aMul: 1,
+  rAdd: 0,
+  gAdd: 0,
+  bAdd: 0,
+  aAdd: 0,
+};
+
+/** A new flash.geom.Matrix of `m`. */
+function matrixObject(s: Scripting, m: Linear): AsObject {
+  return s.rt.construct(
+    s.rt.classNamed("flash.geom::Matrix"),
+    m.a,
+    m.b,
+    m.c,
+    m.d,
+    m.tx,
+    m.ty,
+  ) as AsObject;
+}
+
+/** The matrix a flash.geom.Matrix holds. */
+export function matrixOf(s: Scripting, o: AsObject): Linear {
+  const value = (i: number) => Number(s.rt.getProperty(o, MATRIX_NAMES[i]));
+  return { a: value(0), b: value(1), c: value(2), d: value(3), tx: value(4), ty: value(5) };
+}
+
+/** A new flash.geom.ColorTransform of `c`. */
+function colorObject(s: Scripting, c: Color): AsObject {
+  return s.rt.construct(
+    s.rt.classNamed("flash.geom::ColorTransform"),
+    c.rMul,
+    c.gMul,
+    c.bMul,
+    c.aMul,
+    c.rAdd,
+    c.gAdd,
+    c.bAdd,
+    c.aAdd,
+  ) as AsObject;
+}
+
+/** The color transform a flash.geom.ColorTransform holds. */
+export function colorOf(s: Scripting, o: AsObject): Color {
+  const value = (i: number) => Number(s.rt.getProperty(o, COLOR_NAMES[i]));
+  return {
+    rMul: value(0),
+    gMul: value(1),
+    bMul: value(2),
+    aMul: value(3),
+    rAdd: value(4),
+    gAdd: value(5),
+    bAdd: value(6),
+    aAdd: value(7),
+  };
+}
+
+export function transformNatives(s: Scripting): avm2.Natives {
+  const natives: avm2.Natives = {};
+  /** Each 3D object's own Matrix3D, while it shares the object's matrix (`matrix3D`). */
+  const bound = new WeakMap<DisplayObject, AsObject>();
+
+  class TransformNatives {
+    declare $display: DisplayObject;
+
+    "flash.geom:Transform::ctor"(display: Value): void {
+      this.$display = (display as AsObject).$display;
+    }
+
+    /** Null in 3D. */
+    get matrix(): Value {
+      return this.$display.space ? null : matrixObject(s, this.$display.matrix);
+    }
+
+    /** Null puts the object in 3D, its matrix3D made from the 2D one; a matrix takes it back to 2D. */
+    set matrix(v: Value) {
+      this.$display.touch();
+      if (v) {
+        this.$display.setMatrix(matrixOf(s, v as AsObject));
+      } else {
+        this.$display.enter3D();
+      }
+    }
+
+    get colorTransform(): Value {
+      return colorObject(s, this.$display.colorTransform ?? IDENTITY_COLOR);
+    }
+
+    set colorTransform(v: Value) {
+      if (v) {
+        this.$display.colorTransform = colorOf(s, v as AsObject);
+        this.$display.touch();
+        this.$display.invalidate(TRANSFORM);
+      }
+    }
+
+    /**
+     * Its own scroll's shift left out, as Flash's does, its parents' taken in; null for a 3D
+     * object. Under one, adl gives it in the space of the bitmap that object is drawn into: up
+     * to the 3D object, then moved by the bitmap's corner, two pixels out from its bounds'
+     * top left out to whole pixels (the `three-d-bounds` case).
+     */
+    get concatenatedMatrix(): Value {
+      const d = this.$display;
+      if (d.space) {
+        return null;
+      }
+
+      let m = d.matrix;
+      let p = d.parent;
+      for (; p && p !== s.stage && !p.space; p = p.parent) {
+        m = concat(m, p.placed);
+      }
+
+      const r = p?.space ? bounds(p, true) : null;
+      if (r) {
+        m = { ...m, tx: m.tx + 2 - Math.floor(r.xMin), ty: m.ty + 2 - Math.floor(r.yMin) };
+      }
+
+      return matrixObject(s, m);
+    }
+
+    /** The color transform to the stage: multipliers multiplied, offsets carried through the parents' multipliers. */
+    get concatenatedColorTransform(): Value {
+      const c = { ...(this.$display.colorTransform ?? IDENTITY_COLOR) };
+      for (let p = this.$display.parent; p && p !== s.stage; p = p.parent) {
+        const q = p.colorTransform;
+        if (!q) {
+          continue;
+        }
+
+        for (const [mul, , add] of [
+          ["rMul", 0, "rAdd"],
+          ["gMul", 0, "gAdd"],
+          ["bMul", 0, "bAdd"],
+          ["aMul", 0, "aAdd"],
+        ] as const) {
+          c[add] = c[add] * q[mul] + q[add];
+          c[mul] = c[mul] * q[mul];
+        }
+      }
+
+      return colorObject(s, c);
+    }
+
+    /**
+     * The object's own Matrix3D, null in 2D: one, which shares its matrix, so that what a script
+     * does to it moves the object and what the object's properties do shows in it, as adl's
+     * does (Matrix3D's natives tell its `$owner`). A new one once the object leaves 3D.
+     */
+    get matrix3D(): Value {
+      const d = this.$display;
+      const space = d.space;
+      if (!space) {
+        return null;
+      }
+
+      let m = bound.get(d);
+      if (!m || m.$matrix3D !== space.raw) {
+        m = s.rt.construct(s.rt.classNamed("flash.geom::Matrix3D")) as AsObject;
+        m.$matrix3D = space.raw;
+        m.$owner = d;
+        bound.set(d, m);
+      }
+
+      return m;
+    }
+
+    /**
+     * Taken as the object's own, and apart into the 3D properties, as adl
+     * does, even one of the same values; null back to 2D, at the identity.
+     * The object's own Matrix3D set back changes nothing, its properties
+     * kept as they were set. One that is another object's is refused, as is
+     * any whose float32 determinant is 0.
+     */
+    set matrix3D(v: Value) {
+      const d = this.$display;
+      const held = bound.get(d);
+      if (!v) {
+        if (held) {
+          held.$owner = null;
+          bound.delete(d);
+        }
+
+        d.touch();
+        d.setMatrix3D(null);
+        return;
+      }
+
+      const m = v as AsObject;
+      const raw = m.$matrix3D as Float32Array;
+      if (m === held && d.space?.raw === raw) {
+        d.touch();
+        return;
+      }
+
+      const owner = m.$owner as DisplayObject | null | undefined;
+      if (owner && owner !== d && owner.space?.raw === raw) {
+        throw s.rt.error("ArgumentError", 2189);
+      }
+
+      if (determinant3D(raw) === 0) {
+        throw s.rt.error("ArgumentError", 2188);
+      }
+
+      if (held) {
+        held.$owner = null;
+      }
+
+      d.touch();
+      d.setMatrix3D(raw, false, true);
+      m.$owner = d;
+      bound.set(d, m);
+    }
+
+    /**
+     * The matrix3D from this object's space to `relativeTo`'s, through
+     * their concatenated transforms, each 2D one taken as 3D; null for an
+     * object in 2D, as Flash gives.
+     */
+    getRelativeMatrix3D(relativeTo: Value): Value {
+      if (relativeTo === null || relativeTo === undefined) {
+        throw s.rt.error("TypeError", 2007, "relativeTo");
+      }
+
+      const d = this.$display;
+      if (!d.space) {
+        return null;
+      }
+
+      const target: DisplayObject = (relativeTo as AsObject).$display;
+      const toTarget = invert3D(concatenated3D(target)) ?? identity3D();
+      const m = s.rt.construct(s.rt.classNamed("flash.geom::Matrix3D")) as AsObject;
+      (m.$matrix3D as Float32Array).set(multiply3D(toTarget, concatenated3D(d)));
+      return m;
+    }
+
+    /** A new one of this object's, which reads and writes this object's; null for an object with none. */
+    get perspectiveProjection(): Value {
+      const d = this.$display;
+      return d.projection || alwaysProjects(s, d) ? projectionObject(s, d) : null;
+    }
+
+    set perspectiveProjection(v: Value) {
+      this.$display.projection = v ? projectionFrom(s, v as AsObject) : null;
+      // What is in it is drawn through it.
+      this.$display.invalidate(TRANSFORM);
+    }
+
+    /** The bounds on the stage, out to whole pixels. */
+    get pixelBounds(): Value {
+      const r = boundsIn(this.$display, s.stage, s.stage, true);
+      // Math.ceil gives -0 for an edge just left of 0, which Flash reports as 0.
+      const x = Math.ceil(r.xMin) || 0;
+      const y = Math.ceil(r.yMin) || 0;
+      const right = Math.ceil(r.xMax);
+      const bottom = Math.ceil(r.yMax);
+      return s.rt.construct(s.rt.classNamed("flash.geom::Rectangle"), x, y, right - x, bottom - y);
+    }
+  }
+
+  /** `d`'s transform to the top of its list, each 2D matrix taken as 3D. */
+  const concatenated3D = (d: DisplayObject): Raw => {
+    let m = identity3D();
+    for (let o: DisplayObject | null = d; o && o !== s.stage; o = o.parent) {
+      const local = o.space
+        ? o.space.shown
+        : Float32Array.of(
+            o.matrix.a,
+            o.matrix.b,
+            0,
+            0,
+            o.matrix.c,
+            o.matrix.d,
+            0,
+            0,
+            0,
+            0,
+            1,
+            0,
+            o.matrix.tx,
+            o.matrix.ty,
+            0,
+            1,
+          );
+      m = multiply3D(local, m);
+    }
+
+    return m;
+  };
+
+  avm2.registerNativeClass(natives, "flash.geom::Transform", TransformNatives);
+  return natives;
+}

package/src/playerglobal/flash/geom/Utils3D.ts

@@ -0,0 +1,132 @@
+// flash.geom.Utils3D: points through a projection matrix, to the plane w = 1,
+// and a matrix turned part of the way to face a point.
+import { avm2 } from "@swf2es/runtime";
+import { interpolate3D, pointAt3D, transform3D, translation3D } from "../../../display/matrix3d.js";
+import type { Scripting } from "../../../scripting.js";
+
+type AsObject = avm2.AsObject;
+type Value = avm2.Value;
+
+const f = Math.fround;
+
+export function utils3DNatives(s: Scripting): avm2.Natives {
+  const natives: avm2.Natives = {};
+
+  const nonNull = (v: Value, name: string): AsObject => {
+    if (v === null || v === undefined) {
+      throw s.rt.error("TypeError", 2007, name);
+    }
+
+    return v as AsObject;
+  };
+
+  const component = (v: AsObject, name: string): number =>
+    s.rt.toNumber(s.rt.getProperty(v, s.rt.publicName(name)));
+
+  /** A vector grown with zeros to `n`, as Flash grows it; a fixed one too short is RangeError 1126. */
+  const grow = (v: AsObject, n: number): void => {
+    if (v.$a.length >= n) {
+      return;
+    }
+
+    if (v.$fixed) {
+      throw s.rt.error("RangeError", 1126, v.$a.length, n);
+    }
+
+    while (v.$a.length < n) {
+      v.$a.push(0);
+    }
+  };
+
+  const xyz = (v: AsObject): number[] => ["x", "y", "z"].map((name) => component(v, name));
+
+  class Utils3DNatives {
+    /**
+     * A new matrix, `mat` interpolated toward its translation alone turned
+     * by pointAt, the percent held to 0 to 1, as adl has it: so the scale
+     * goes to 1 with it. Where pointAt would leave the matrix, a copy of
+     * it. The translation is lerped apart from the rotation, and the last
+     * element is 1, so a NaN direction leaves both as they were.
+     */
+    static pointTowards(
+      percent: Value,
+      mat: Value,
+      pos: Value,
+      at: Value = null,
+      up: Value = null,
+    ): AsObject {
+      const from: Float32Array = nonNull(mat, "fromMat").$matrix3D;
+      const target = xyz(nonNull(pos, "target"));
+      const position = translation3D(from[12], from[13], from[14]);
+      const turned = pointAt3D(
+        position,
+        target,
+        at === null || at === undefined ? [0, 1, 0] : xyz(at as AsObject),
+        up === null || up === undefined ? [0, 0, 1] : xyz(up as AsObject),
+      );
+      const out = s.rt.construct(s.rt.classNamed("flash.geom::Matrix3D")) as AsObject;
+      const raw: Float32Array = out.$matrix3D;
+      if (!turned) {
+        raw.set(from);
+        return out;
+      }
+
+      const p = Math.max(0, Math.min(1, s.rt.toNumber(percent)));
+      raw.set(interpolate3D(from, turned, p));
+      for (let i = 0; i < 3; i++) {
+        raw[12 + i] = from[12 + i] + (position[12 + i] - from[12 + i]) * p;
+      }
+
+      raw[15] = 1;
+      return out;
+    }
+
+    /**
+     * transformVector's float32 result times the float32 reciprocal of its
+     * w, as adl has it; the Flash Player of Ruffle's corpus rounds the
+     * products to float32 too.
+     */
+    static projectVector(m: Value, v: Value): AsObject {
+      const raw: Float32Array = nonNull(m, "m").$matrix3D;
+      const at = nonNull(v, "v");
+      const [x, y, z, w] = transform3D(
+        raw,
+        component(at, "x"),
+        component(at, "y"),
+        component(at, "z"),
+      );
+      const over = f(1 / w);
+      return s.rt.construct(
+        s.rt.classNamed("flash.geom::Vector3D"),
+        x * over,
+        y * over,
+        z * over,
+        w,
+      ) as AsObject;
+    }
+
+    /** Each (x, y, z) of `verts` through the matrix in float32, to an (x, y) in `projected` over w in doubles, and 1/w to its t in `uvts`. */
+    static projectVectors(m: Value, verts: Value, projected: Value, uvts: Value): void {
+      const raw: Float32Array = nonNull(m, "m").$matrix3D;
+      const input: Value[] = nonNull(verts, "verts").$a;
+      const out = nonNull(projected, "projectedVerts");
+      const uvt = nonNull(uvts, "uvts");
+      grow(uvt, input.length);
+      grow(out, Math.floor(input.length / 3) * 2);
+      for (let i = 0, j = 0; i + 2 < input.length; i += 3, j += 2) {
+        const [x, y, , w] = transform3D(
+          raw,
+          Number(input[i]),
+          Number(input[i + 1]),
+          Number(input[i + 2]),
+        );
+        out.$a[j] = x / w;
+        out.$a[j + 1] = y / w;
+        uvt.$a[i + 2] = 1 / w;
+      }
+    }
+  }
+
+  avm2.registerNativeClass(natives, "flash.geom::Utils3D", Utils3DNatives);
+  return natives;
+}