Function warnIfZSignificant

packages/engine/src/utils/alphaBlit.ts:965–1015

(parts: number[])

const Z_EPSILON = 1e-6;

function warnIfZSignificant(parts: number[]): void {
  if (warnedZSignificant) return;
  // CSS matrix3d() is column-major:
  //   matrix3d(a1, b1, c1, d1, a2, b2, c2, d2, a3, b3, c3, d3, a4, b4, c4, d4)
  // laid out as:
  //   | a1 a2 a3 a4 |   | parts[0]  parts[4]  parts[8]  parts[12] |
  //   | b1 b2 b3 b4 | = | parts[1]  parts[5]  parts[9]  parts[13] |
  //   | c1 c2 c3 c4 |   | parts[2]  parts[6]  parts[10] parts[14] |
  //   | d1 d2 d3 d4 |   | parts[3]  parts[7]  parts[11] parts[15] |
  //
  // For a flat 2D transform — the only thing this engine path can render
  // faithfully — we expect:
  //   a3 = b3 = c1 = c2 = 0   (no XZ/YZ rotation coupling)
  //   c3 = 1                  (no Z scaling)
  //   d1 = d2 = d3 = 0        (no perspective)
  //   d4 = 1                  (no homogeneous scaling)
  // Z translation (c4 = parts[14]) is explicitly dropped by the 2D affine
  // extraction below — that's the whole point of supporting GSAP's
  // `force3D: true` translate3d(x, y, 0) emission — so it is NOT flagged.
  const a3 = parts[8] ?? 0;
  const b3 = parts[9] ?? 0;
  const c1 = parts[2] ?? 0;
  const c2 = parts[6] ?? 0;
  const c3 = parts[10] ?? 1;
  const d1 = parts[3] ?? 0;
  const d2 = parts[7] ?? 0;
  const d3 = parts[11] ?? 0;
  const d4 = parts[15] ?? 1;
  if (
    Math.abs(a3) > Z_EPSILON ||
    Math.abs(b3) > Z_EPSILON ||
    Math.abs(c1) > Z_EPSILON ||
    Math.abs(c2) > Z_EPSILON ||
    Math.abs(c3 - 1) > Z_EPSILON ||
    Math.abs(d1) > Z_EPSILON ||
    Math.abs(d2) > Z_EPSILON ||
    Math.abs(d3) > Z_EPSILON ||
    Math.abs(d4 - 1) > Z_EPSILON
  ) {
    warnedZSignificant = true;
    console.warn(
      `[alphaBlit] parseTransformMatrix received a matrix3d with non-trivial 3D components ` +
        `(a3=${a3}, b3=${b3}, c1=${c1}, c2=${c2}, c3=${c3}, d1=${d1}, d2=${d2}, d3=${d3}, d4=${d4}). ` +
        `The engine projects 3D transforms to 2D (m11, m12, m21, m22, m41, m42) and silently ` +
        `discards perspective and out-of-plane rotation. If your composition uses real 3D ` +
        `(rotateX/Y, perspective), the rendered output will not match the studio preview. ` +
        `Z translation (translateZ) is dropped by design and does not trigger this warning. ` +
        `This warning is emitted once per process.`,
    );
  }
}