@swf2es/player 0.0.0-stage → 0.1.1

package/src/display/perspective.ts

@@ -0,0 +1,253 @@
+// A 3D display object's plane in perspective (docs/architecture/rendering.md, "3D
+// display objects"): as Flash Player and adl project it, through the
+// perspective projection of the nearest container above it that has one
+// set, or else of its SWF's root (the stage's, for one put on the stage).
+// Its matrix3D, those of the 3D objects above it and the 2D matrices
+// between go into one 3D transform to that container's space, which the
+// projection then divides: a 3D object inside another is in true 3D, not
+// flattened into the other's plane. The plane of each object, 2D or 3D,
+// is then a projective map of its space to the container's, and a 3D
+// object's in its parent's is the parent's inverse after its own.
+
+import type { Matrix } from "@swf2es/format";
+import type { DisplayObject, Projection } from "./display.js";
+import { apply, concat, invert, type Projective } from "./geometry.js";
+
+/** Each player's stage's size, for the default projection of a root: centred on the stage and as wide. */
+const stageSizes = new WeakMap<DisplayObject, { width: number; height: number }>();
+
+export function setStageSize(stage: DisplayObject, width: number, height: number): void {
+  stageSizes.set(stage, { width, height });
+}
+
+/**
+ * A BitmapData's draw of what is on no stage, `top` the topmost of it: as
+ * in Flash, what is in 3D in it projects as on a stage the bitmap's size,
+ * centred on it, for the draw. Returns how to put it back, or null where it
+ * is on a stage already.
+ */
+export function drawnAsStage(
+  top: DisplayObject,
+  width: number,
+  height: number,
+): (() => void) | null {
+  if (top.parent || top.loaderInfo || stageSizes.has(top)) {
+    return null;
+  }
+
+  stageSizes.set(top, { width, height });
+  return () => stageSizes.delete(top);
+}
+
+/** The size of the stage `d` is under, or Flash's default stage's where it is under none. */
+function stageSizeOf(d: DisplayObject): { width: number; height: number } {
+  let top = d;
+  while (top.parent) {
+    top = top.parent;
+  }
+
+  return stageSizes.get(top) ?? { width: 550, height: 400 };
+}
+
+/** Flash's default field of view, 55 degrees, in radians. */
+const FIELD_OF_VIEW = (55 * Math.PI) / 180;
+
+/** The projection of what has none set: Flash's field of view, centred on (centerX, centerY). */
+export function defaultProjection(centerX: number, centerY: number): Projection {
+  return { fieldOfView: FIELD_OF_VIEW, centerX, centerY };
+}
+
+/** The focal length of a field of view in radians over a width, in float32 as Flash's. */
+export function focalLengthOver(radians: number, width: number): number {
+  return Math.fround((width / 2) * Math.fround(Math.tan((Math.PI - radians) / 2)));
+}
+
+/** Whether `d` projects what is in it: a projection set on it, a SWF's root, or the stage (no parent). */
+function projects(d: DisplayObject): boolean {
+  return d.projection !== null || d.loaderInfo !== null || d.parent === null;
+}
+
+/** The container whose projection `o` is drawn through: the nearest above it that projects. */
+function projectorOf(o: DisplayObject): DisplayObject | null {
+  for (let p = o.parent; p; p = p.parent) {
+    if (projects(p)) {
+      return p;
+    }
+  }
+
+  return null;
+}
+
+/** The projection `d` projects through: its own, or the default of the stage or a root. */
+function projectionOf(d: DisplayObject): Projection {
+  if (d.projection) {
+    return d.projection;
+  }
+
+  const stage = d.parent === null && d.loaderInfo !== null;
+  const size = stageSizeOf(d);
+  return stage ? defaultProjection(250, 250) : defaultProjection(size.width / 2, size.height / 2);
+}
+
+/**
+ * The focal length of a field of view in radians as `d` projects through
+ * it: the stage's projection measures 500 wide, any other object's the
+ * stage's width.
+ */
+function focalLength(radians: number, d: DisplayObject): number {
+  const width = d.parent === null && d.loaderInfo !== null ? 500 : stageSizeOf(d).width;
+  return focalLengthOver(radians, width);
+}
+
+/** A column-major 4x4 matrix. */
+type M4 = Float64Array;
+
+/** `m`, `d`'s own transform in 3D: its matrix3D, or its 2D matrix with z kept (a 3D object has no scroll). */
+function own3D(d: DisplayObject): M4 {
+  const m = new Float64Array(16);
+  const space = d.space;
+  if (space) {
+    m.set(space.shown);
+  } else {
+    const p = d.placed;
+    m.set([p.a, p.b, 0, 0, p.c, p.d, 0, 0, 0, 0, 1, 0, p.tx, p.ty, 0, 1]);
+  }
+
+  return m;
+}
+
+/** `a` after `b`: b's columns through a. */
+function multiply(a: M4, b: M4): M4 {
+  const out = new Float64Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let r = 0; r < 4; r++) {
+      out[c * 4 + r] =
+        a[r] * b[c * 4] +
+        a[4 + r] * b[c * 4 + 1] +
+        a[8 + r] * b[c * 4 + 2] +
+        a[12 + r] * b[c * 4 + 3];
+    }
+  }
+
+  return out;
+}
+
+/** `d`'s space to `top`'s in 3D, `top` excluded; null where `top` is not above it. */
+function toSpace(d: DisplayObject, top: DisplayObject | null): M4 | null {
+  let m = own3D(d);
+  for (let p = d.parent; p !== top; p = p.parent) {
+    if (!p) {
+      return null;
+    }
+
+    m = multiply(own3D(p), m);
+  }
+
+  return m;
+}
+
+/**
+ * A point in the projector's 3D space projected into its plane, as
+ * homogeneous coordinates: the field of view's focal length f, the centre
+ * (cx, cy), and a point at depth z drawn at f / (f + z) of its distance
+ * from the centre.
+ */
+function project(
+  projector: DisplayObject,
+  x: number,
+  y: number,
+  z: number,
+): [number, number, number] {
+  const p = projectionOf(projector);
+  const k = 1 / focalLength(p.fieldOfView, projector);
+  return [x + p.centerX * k * z, y + p.centerY * k * z, 1 + k * z];
+}
+
+/** The plane z = 0 of a 3D space `m` puts in the projector's, projected: a projective map. */
+function planeOf(projector: DisplayObject, m: M4): Projective {
+  const p = projectionOf(projector);
+  const k = 1 / focalLength(p.fieldOfView, projector);
+  const cx = p.centerX * k;
+  const cy = p.centerY * k;
+  return {
+    a: m[0] + cx * m[2],
+    b: m[1] + cy * m[2],
+    u: k * m[2] + m[3],
+    c: m[4] + cx * m[6],
+    d: m[5] + cy * m[6],
+    v: k * m[6] + m[7],
+    tx: m[12] + cx * m[14],
+    ty: m[13] + cy * m[14],
+    w: k * m[14] + m[15],
+  };
+}
+
+/**
+ * A 3D object's plane in its parent's space, in perspective (`placed`):
+ * through its projector's projection, its plane in the projector's space
+ * (`own`), and back through the parent's plane there (`back`, null where
+ * the parent is the projector), which is flat but for a 3D object above
+ * it. An object off the list projects through its topmost container's, as
+ * a root's.
+ */
+export function placedInPerspective(o: DisplayObject): {
+  placed: Projective;
+  own: Projective;
+  back: Matrix | null;
+} {
+  const parent = o.parent;
+  if (!parent) {
+    const m = own3D(o);
+    const placed = { a: m[0], b: m[1], c: m[4], d: m[5], tx: m[12], ty: m[13], u: 0, v: 0, w: 1 };
+    return { placed, own: placed, back: null };
+  }
+
+  const projector = projectorOf(o) as DisplayObject;
+  const up = parent === projector ? null : toSpace(parent, projector);
+  const m = up ? multiply(up, own3D(o)) : own3D(o);
+  // A NaN anywhere, as an infinite scale's column has, goes into all of Flash's projection, which
+  // then draws nothing: the plane's z column alone would leave it out.
+  if (m.some(Number.isNaN)) {
+    m.fill(Number.NaN);
+  }
+
+  const own = planeOf(projector, m);
+  if (!up) {
+    return { placed: own, own, back: null };
+  }
+
+  const back = invert(planeOf(projector, up));
+  return { placed: (back ? concat(own, back) : own) as Projective, own, back };
+}
+
+/**
+ * A point of `d`'s 3D space on the stage (`stage` itself excluded): into
+ * its projector's space, projected there, then through the projector's
+ * matrices up to the stage.
+ */
+export function stagePoint3D(
+  d: DisplayObject,
+  x: number,
+  y: number,
+  z: number,
+  stage: DisplayObject | null,
+): [number, number] {
+  const projector = projectorOf(d);
+  const m = projector && toSpace(d, projector);
+  if (!projector || !m) {
+    return apply(d.placed, x, y);
+  }
+
+  const [px, py, q] = project(
+    projector,
+    m[0] * x + m[4] * y + m[8] * z + m[12],
+    m[1] * x + m[5] * y + m[9] * z + m[13],
+    m[2] * x + m[6] * y + m[10] * z + m[14],
+  );
+  let at: [number, number] = [px / q, py / q];
+  for (let p: DisplayObject | null = projector; p && p !== stage; p = p.parent) {
+    at = apply(p.placed, at[0], at[1]);
+  }
+
+  return at;
+}

package/src/display/plane.ts

@@ -0,0 +1,192 @@
+// A 3D display object's bitmap and the quad it is drawn through, as the
+// renderer draws it (scene/view.ts): what it and its children draw, in its own
+// space, a pixel of it a texel, drawn into a bitmap at SAMPLES a side and
+// averaged down, with a texel of nothing around; and the bitmap's quad
+// placed through the object's plane in perspective (display/perspective.ts)
+// as Flash places it (docs/architecture/rendering.md, "3D display objects").
+import type { Matrix } from "@swf2es/format";
+import type { PixelRect } from "../bitmap/bitmap.js";
+import { filterRect } from "../bitmap/filters.js";
+import { bounds, toStage } from "./bounds.js";
+import type { DisplayObject } from "./displayobject.js";
+import { apply, concat, isProjective } from "./geometry.js";
+
+/**
+ * The samples a side the bitmap is drawn at before it is averaged to a
+ * texel a pixel, as Flash's high quality covers edges.
+ */
+const SAMPLES = 4;
+
+/**
+ * The most texels a side of a bitmap: larger, the object is drawn into it
+ * at less than a texel a pixel.
+ */
+const LARGEST = 2048;
+
+/** The most texels the samples a bitmap is drawn at may take (16 MiB): past it, fewer samples. */
+const SAMPLED_TEXELS = 4 * 1024 * 1024;
+
+/**
+ * The samples a side, and texels a pixel of the object's space, a bitmap of
+ * a w by h rectangle is drawn at.
+ */
+export function bitmapScale(
+  width: number,
+  height: number,
+  largest: number,
+): { samples: number; texels: number } {
+  const texels = Math.min(1, Math.min(LARGEST, largest) / Math.max(width, height));
+  const w = Math.max(1, Math.ceil(width * texels));
+  const h = Math.max(1, Math.ceil(height * texels));
+  let samples = SAMPLES;
+  while (
+    samples > 1 &&
+    (w * samples > largest || h * samples > largest || w * h * samples * samples > SAMPLED_TEXELS)
+  ) {
+    samples /= 2;
+  }
+
+  return { samples, texels };
+}
+
+/**
+ * A bitmap's rectangle in the object's space, and its quad's corners in its
+ * parent's space with the w each divides by: top left, top right, bottom
+ * right, bottom left.
+ */
+export interface PlaneQuad {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  positions: Float64Array;
+  ws: Float64Array;
+}
+
+/**
+ * The quad of the bitmap of what the object draws over xMin to xMax and
+ * yMin to yMax of its own space, by its plane in its parent's space, `m`,
+ * into `out`: false, and nothing to draw, where a corner is behind the eye,
+ * as Flash draws none of it. The bitmap reaches from the rectangle's left
+ * and top out to whole pixels, a texel a pixel, and a texel of nothing
+ * around. Flash draws it a texel wider and taller than it is, about its
+ * centre, and half a pixel of the stage right and down: so unturned at a
+ * texel a pixel its left and top edges stay where they are, and magnified
+ * it grows as much each way.
+ */
+export function placeQuad(
+  m: Matrix,
+  xMin: number,
+  yMin: number,
+  xMax: number,
+  yMax: number,
+  out: PlaneQuad,
+): boolean {
+  const xFrom = Math.floor(xMin);
+  const yFrom = Math.floor(yMin);
+  const across = Math.ceil(xMax) - xFrom;
+  const down = Math.ceil(yMax) - yFrom;
+  if (!(across >= 1 && down >= 1 && across < 1e6 && down < 1e6)) {
+    return false;
+  }
+
+  const [u, v, w] = isProjective(m) ? [m.u, m.v, m.w] : [0, 0, 1];
+  const cx = xFrom + across / 2;
+  const cy = yFrom + down / 2;
+  const at = (x: number, y: number): [number, number] => {
+    const q = u * x + v * y + w;
+    return [(m.a * x + m.c * y + m.tx) / q, (m.b * x + m.d * y + m.ty) / q];
+  };
+  // Half a pixel of the stage right and down, in the object's space: through the inverse of
+  // how its plane moves a point at the centre.
+  const [ax, ay] = at(cx - 0.5, cy);
+  const [bx, by] = at(cx + 0.5, cy);
+  const [dx, dy] = at(cx, cy - 0.5);
+  const [ex, ey] = at(cx, cy + 0.5);
+  const jxx = bx - ax;
+  const jyx = by - ay;
+  const jxy = ex - dx;
+  const jyy = ey - dy;
+  const det = jxx * jyy - jxy * jyx;
+  const shiftX = det ? (0.5 * jyy - 0.5 * jxy) / det : 0;
+  const shiftY = det ? (0.5 * jxx - 0.5 * jyx) / det : 0;
+  const sx = (across + 1) / across;
+  const sy = (down + 1) / down;
+  const left = cx + shiftX - (across / 2 + 1) * sx;
+  const right = cx + shiftX + (across / 2 + 1) * sx;
+  const top = cy + shiftY - (down / 2 + 1) * sy;
+  const bottom = cy + shiftY + (down / 2 + 1) * sy;
+  for (let i = 0; i < 4; i++) {
+    const x = i === 1 || i === 2 ? right : left;
+    const y = i >= 2 ? bottom : top;
+    const q = u * x + v * y + w;
+    if (!(q > 0)) {
+      return false;
+    }
+
+    out.positions[i * 2] = (m.a * x + m.c * y + m.tx) / q;
+    out.positions[i * 2 + 1] = (m.b * x + m.d * y + m.ty) / q;
+    out.ws[i] = q;
+  }
+
+  out.x = xFrom - 1;
+  out.y = yFrom - 1;
+  out.width = across + 2;
+  out.height = down + 2;
+
+  return true;
+}
+
+/**
+ * What a 3D object draws in its own space, which its bitmap holds: its
+ * bounds, its children's and its lines', out as far as its filters reach;
+ * null for nothing.
+ */
+export function drawnRect(o: DisplayObject): PixelRect | null {
+  const r = bounds(o, true, true);
+  let rect: PixelRect | null = r && {
+    x: r.xMin,
+    y: r.yMin,
+    width: r.xMax - r.xMin,
+    height: r.yMax - r.yMin,
+  };
+  for (const f of o.filters) {
+    rect = rect && filterRect(rect, f);
+  }
+
+  return rect;
+}
+
+/**
+ * The map from the space of `mask`, a 2D mask outside the 3D object `o`, to
+ * `o`'s, as Flash clips the bitmap it draws `o` into: the mask is placed by
+ * its matrices up to the nearest 3D object above it (or the stage), and then
+ * moved as if the bitmap's corner, `o`'s bounds' top left in its own space,
+ * were where `o`'s bounds' top left is on the stage. So a mask over a turned
+ * card clips a part of the card that is not under it (the `three-d-mask` case).
+ */
+export function outsideMaskMap(o: DisplayObject, mask: DisplayObject): Matrix {
+  let m = mask.placed;
+  for (let p = mask.parent; p && !p.space; p = p.parent) {
+    m = concat(m, p.placed);
+  }
+
+  const own = bounds(o, true) ?? { xMin: 0, yMin: 0, xMax: 0, yMax: 0 };
+  const up = toStage(o, null);
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  for (let i = 0; i < 4; i++) {
+    const [x, y] = apply(up, i & 1 ? own.xMax : own.xMin, i & 2 ? own.yMax : own.yMin);
+    left = Math.min(left, x);
+    top = Math.min(top, y);
+  }
+
+  return {
+    a: m.a,
+    b: m.b,
+    c: m.c,
+    d: m.d,
+    tx: m.tx + own.xMin - Math.round(left),
+    ty: m.ty + own.yMin - Math.round(top),
+  };
+}