Skip to content
TypeScript
5.7 KB
Raw Blame
// Normal maps: per-pixel surface directions that make lighting() rake across relief (bricks,
// domes, bevels) instead of lighting everything flat. Generated from shape (bump) or painted
// with numpad direction grids (normals); stored on the image (Img.norm) so they travel with it.
import { TRANSPARENT, pack } from "./color.ts";
import { PxError } from "./errors.ts";
import { Img } from "./image.ts";
import type { BumpOpts } from "./model.ts";

/** Write normal (nx, ny, nz) (any length, ny pointing down) for pixel i; nz is kept >= ~0. */
export function setNormal(n: Int8Array, i: number, nx: number, ny: number, nz: number): void {
  const len = Math.hypot(nx, ny, nz) || 1;
  n[i * 3] = Math.round((nx / len) * 127);
  n[i * 3 + 1] = Math.round((ny / len) * 127);
  n[i * 3 + 2] = Math.max(1, Math.round((nz / len) * 127)); // 0 is "no normal"
}

/**
 * Numpad directions for normals() grids: the way the surface faces. 8 = up, 3 = down-right,
 * 5 = straight at the viewer; lowercase-style softer tilts use the shifted row (q w e / a s d / z x c).
 */
const DIRS: Record<string, [number, number, number]> = {};
const steep = 1, soft = 0.4;
for (const [keys, t] of [["789456123", steep], ["qweasdzxc", soft]] as const)
  [...keys].forEach((ch, k) => {
    const dx = (k % 3) - 1, dy = Math.floor(k / 3) - 1;
    DIRS[ch] = [dx * t, dy * t, 1];
  });

/** Normal for a direction grid char, null = skip ("." / space), "none" = clear ("0"). */
export function dirOf(ch: string): [number, number, number] | null | "none" {
  if (ch === "." || ch === " ") return null;
  if (ch === "0") return "none";
  const d = DIRS[ch];
  if (!d) throw new PxError(`normals: unknown direction '${ch}' (numpad 1-9 steep, qweasdzxc soft, 0 clears, . skips)`);
  return d;
}

/**
 * Generate normals over `mask` pixels from a height field:
 * - "bevel": edges slope down over `w` px, flat top (bricks, panels, buttons)
 * - "dome": each connected blob bulges like a pillow / sphere (barrels, fruit, rocks)
 * - "luma": brighter = higher, from the art's own shading (hand-shaded sprites)
 * Pixels outside the mask (and outside the image) count as height 0 for bevel/dome.
 */
export function bump(img: Img, mask: Uint8Array, o: BumpOpts): void {
  const { w, h } = img, n = w * h;
  const shape = o.shape ?? "dome", depth = o.depth ?? 1;
  const ht = new Float32Array(n);
  if (shape === "luma") {
    for (let i = 0; i < n; i++) {
      if (!mask[i]) continue;
      const c = img.data[i];
      ht[i] = (0.3 * (c >>> 24) + 0.59 * ((c >>> 16) & 255) + 0.11 * ((c >>> 8) & 255)) / 255 * 4;
    }
  } else if (shape === "bevel" || shape === "dome") {
    const d = distance(mask, w, h);
    if (shape === "bevel") {
      const bw = Math.max(1, o.w ?? 2);
      for (let i = 0; i < n; i++) ht[i] = Math.min(d[i], bw);
    } else {
      // Per blob: a circular profile over its own deepest distance.
      const blob = new Int32Array(n).fill(-1), peak: number[] = [];
      for (let s = 0; s < n; s++) {
        if (!mask[s] || blob[s] >= 0) continue;
        const id = peak.length, stack = [s];
        let top = 0;
        blob[s] = id;
        while (stack.length) {
          const i = stack.pop()!, x = i % w;
          top = Math.max(top, d[i]);
          for (const j of [x > 0 ? i - 1 : -1, x < w - 1 ? i + 1 : -1, i - w, i + w])
            if (j >= 0 && j < n && mask[j] && blob[j] < 0) { blob[j] = id; stack.push(j); }
        }
        peak.push(top);
      }
      for (let i = 0; i < n; i++) {
        if (!mask[i]) continue;
        const R = peak[blob[i]], t = 1 - d[i] / (R + 0.5);
        ht[i] = (R + 0.5) * Math.sqrt(Math.max(0, 1 - t * t));
      }
    }
  } else throw new PxError(`bump shape must be "bevel", "dome" or "luma", got '${shape}'`);

  const nm = img.normals();
  const at = (x: number, y: number, i: number) => {
    if (x < 0 || y < 0 || x >= w || y >= h) return shape === "luma" ? ht[i] : 0;
    const j = y * w + x;
    return mask[j] ? ht[j] : shape === "luma" ? ht[i] : 0;
  };
  for (let y = 0; y < h; y++)
    for (let x = 0; x < w; x++) {
      const i = y * w + x;
      if (!mask[i]) continue;
      const gx = (at(x + 1, y, i) - at(x - 1, y, i)) / 2, gy = (at(x, y + 1, i) - at(x, y - 1, i)) / 2;
      setNormal(nm, i, -gx * depth, -gy * depth, 1);
    }
}

/** Chamfer distance (1, √2) from each mask pixel to the nearest non-mask pixel or the border. */
function distance(mask: Uint8Array, w: number, h: number): Float32Array {
  const d = new Float32Array(w * h), D = Math.SQRT2;
  const get = (x: number, y: number) => (x < 0 || y < 0 || x >= w || y >= h ? 0 : d[y * w + x]);
  for (let i = 0; i < d.length; i++) d[i] = mask[i] ? 1e9 : 0;
  for (let y = 0; y < h; y++)
    for (let x = 0; x < w; x++) {
      const i = y * w + x;
      if (d[i]) d[i] = Math.min(d[i], get(x - 1, y) + 1, get(x, y - 1) + 1, get(x - 1, y - 1) + D, get(x + 1, y - 1) + D);
    }
  for (let y = h - 1; y >= 0; y--)
    for (let x = w - 1; x >= 0; x--) {
      const i = y * w + x;
      if (d[i]) d[i] = Math.min(d[i], get(x + 1, y) + 1, get(x, y + 1) + 1, get(x + 1, y + 1) + D, get(x - 1, y + 1) + D);
    }
  return d;
}

/**
 * The normal map as an image in the common game-engine encoding (Godot, Unity, LDtk...):
 * RGB = normal * 0.5 + 0.5 with green pointing up; flat (128, 128, 255) where none was set.
 */
export function normalImage(img: Img): Img {
  const out = new Img(img.w, img.h), n = img.norm;
  for (let i = 0; i < img.data.length; i++) {
    if (img.data[i] === TRANSPARENT) continue;
    const has = n && n[i * 3 + 2] > 0;
    const nx = has ? n![i * 3] / 127 : 0, ny = has ? n![i * 3 + 1] / 127 : 0, nz = has ? n![i * 3 + 2] / 127 : 1;
    const b = (v: number) => Math.min(255, Math.max(0, Math.round((v * 0.5 + 0.5) * 255)));
    out.data[i] = pack(b(nx), b(-ny), b(nz), 255);
  }
  return out;
}