graphics source

← graphics · API reference · version 0.9.12

19 file(s), 3801 lines. This is the source the published version ships, and it is loft — the library is written in the same language you call it from.

Public items

A worked example is a call site the author chose as the thing to read first. Call sites are every line naming the item, found mechanically over the source with comments excluded — so an item with no worked example is not an item nobody uses.

src/graphics.loft

// Copyright (c) 2026 Jurjen Stellingwerff
// SPDX-License-Identifier: LGPL-3.0-or-later
// graphics — a 2-D pixel canvas, and the window/GPU layer under it.
//
// TWO HALVES, and which one you want decides everything else.  The `Canvas` half
// is a flat vector of packed RGBA integers: it needs no window, no driver and no
// GL context, so it runs under `loft test` and answers questions about pixels.
// The `gl_*` half is the real window — shaders, VBOs, framebuffers — and every
// one of those is a native call that answers *"native function not loaded"* where
// there is no context.  Write the drawing against `Canvas` and it stays testable.
//
// ── Using it ─────────────────────────────────────────────────────────────────
//
//     cv = graphics::canvas(64, 48, graphics::rgb(20, 20, 30));
//     cv.fill_rect(8, 8, 20, 12, graphics::rgb(200, 60, 40));
//     cv.draw_line(0, 0, 63, 47, graphics::rgb(255, 255, 255));
//
//     // Alpha COMPOSITES; `set_pixel` would have replaced instead.
//     cv.blend_pixel(10, 10, graphics::rgba(0, 0, 255, 128));
//     px = cv.get_pixel(10, 10);          // -> r 99, g 29, b 147, a 255:
//                                         //    half the red rect, half the blue
//     cv.save_png("out.png");
//
// ⚠ COLOUR IS 0xAARRGGBB, so a bare `0xFF0000` literal is red at alpha ZERO and
// composites to nothing.  `rgb()` is the same pack with alpha 255 — reach for it
// rather than for a literal, and `color_r`/`_g`/`_b`/`_a` take the channels back
// out.
//
// The rest of the canvas surface is more primitives at the same level: lines,
// rects, circles, ellipses, beziers, an anti-aliased line, triangles and
// polygons, plus two resamplers (`resize_lanczos`, `resize_bicubic`).  The `gl_*`
// surface below them mirrors the OpenGL calls it wraps, and `stage` is the
// retained scene that drives either half.

use mesh3d::*;
use glb::*;

// RGBA color packed as a single integer: 0xAARRGGBB.
// Alpha: 255 = fully opaque, 0 = fully transparent.
// Use rgba() to construct and r()/g()/b()/a() to extract channels.

// Pack RGBA channels into a single integer using bitwise ops.
// Layout: bits 24..31 = alpha, 16..23 = red, 8..15 = green, 0..7 = blue.
// Loft integers are 64-bit signed post-2c, so the packed value fits
// directly — no widening cast needed.  Each channel is MASKED to 8 bits, so an
// out-of-range argument wraps rather than saturating or being refused.
// Example: @GFX-001 — the alpha byte is the one a hand-written hex literal
// leaves at zero, and a zero alpha is fully transparent.
pub fn rgba(cr: integer, cg: integer, cb: integer, ca: integer) -> integer {
  ((ca & 255) << 24) | ((cr & 255) << 16) | ((cg & 255) << 8) | (cb & 255)
}

// Opaque colour: the same pack with alpha 255.  `rgb(255, 0, 0)` is 0xFFFF0000 —
// NOT the 0xFF0000 a reader reaches for, which has alpha 0.
// Example: @GFX-001 — why the literal and this call are different colours, and
// what each compositing path does with the difference.
pub fn rgb(cr: integer, cg: integer, cb: integer) -> integer {
  rgba(cr, cg, cb, 255)
}

// The channels back out of a packed colour, matching `rgba`'s layout — red,
// green, blue, then alpha off the high byte.
pub fn color_r(color: integer) -> integer { (color >> 16) & 255 }
// Green.
pub fn color_g(color: integer) -> integer { (color >> 8) & 255 }
// Blue.
pub fn color_b(color: integer) -> integer { color & 255 }
// Alpha.  255 is opaque; a colour written as a bare 0xRRGGBB literal reads 0
// here, which is what makes it composite to nothing.
pub fn color_a(color: integer) -> integer {
  // integer is i64 post-2c, so the shift is logical on the high byte.
  ((color & 0xFF000000) >> 24) & 255
}

// A 2D pixel canvas backed by a flat vector of RGBA integers.
// Pixels are stored row-major: data[y * width + x].
pub struct Canvas {
  pub const width: integer,
  pub const height: integer,
  pub const data: vector<integer>
}

// `count` copies of `value`, built by doubling rather than one element
// at a time.
//
// A comprehension — `[for _ in 0..count { value }]` — emits three
// bytecodes per element (allocate the slot, write it, bump the length),
// so a 960x720 pixel buffer costs about 2.07 million dispatches.
// Appending a vector to ITSELF is a single block copy, so doubling
// reaches `count` in roughly log2(count) of them.
//
// Walking the bits of `count` from the top — double, then append one
// element where that bit is set — lands on `count` EXACTLY, which is
// what makes this usable: no overshoot to trim, and no tail loop.
// A prefix-slice variant was measured too and is both slower (51 ms)
// and wrong at count = 0.
//
// Measured on the interpreter, count = 691 200 (one 960x720 frame):
// 177 ms -> 10 ms, a factor of 17.  Sizes 0, 1, 9 216, 65 537 and
// 691 200 all match the comprehension element for element.
fn filled(count: integer, value: integer) -> vector<integer> {
  fi_out: vector<integer> = [];
  if count <= 0 { return fi_out; }
  // Highest set bit of `count`.
  fi_top = 0;
  while (count >> (fi_top + 1)) != 0 { fi_top = fi_top + 1; }
  fi_i = fi_top;
  while fi_i >= 0 {
    fi_out += fi_out;
    if ((count >> fi_i) & 1) == 1 { fi_out += [value]; }
    fi_i = fi_i - 1;
  }
  fi_out
}

// Create a canvas filled with a solid color.
pub fn canvas(cw: integer, ch: integer, fill_color: integer) -> Canvas {
  // Build `data` inside the literal so the const field is set once at
  // construction (was a post-literal `result.data = …` fill).
  Canvas { width: cw, height: ch, data: filled(cw * ch, fill_color) }
}

// Get pixel color at (x, y). Returns 0 if out of bounds — and 0 is a COLOUR the
// canvas can hold (`rgba(0, 0, 0, 0)`), so the answer cannot serve as a bounds
// test.  Bound with `width`/`height`.
// Example: @GFX-003 — a neighbourhood scan that tests the returned colour
// miscounts its own transparent pixels as off-canvas.
pub fn get_pixel(self: const Canvas, gx: integer, gy: integer) -> integer {
  if gx < 0 or gx >= self.width or gy < 0 or gy >= self.height {
    0
  } else {
    gp_idx = gy * self.width + gx;
    gp_d = &self.data;
    if gp_idx < len(gp_d) { gp_d[gp_idx] ?? 0 } else { 0 }
  }
}

// Set pixel color at (x, y). No-op if out of bounds.  STORES the colour byte for
// byte, alpha included — it does not composite; `blend_pixel` does.
// Example: @GFX-002 — storing a half-transparent colour replaces what was under
// it, rather than showing through it.
// Example: @GFX-003 — an out-of-range coordinate is declined in silence, so a
// wrong index is a missing part of the drawing, never a message.
pub fn set_pixel(self: Canvas, sx: integer, sy: integer, color: integer) {
  if sx >= 0 and sx < self.width and sy >= 0 and sy < self.height {
    sp_idx = sy * self.width + sx;
    sp_d = &self.data;
    if sp_idx < len(sp_d) {
      sp_d[sp_idx] = color;
    }
  }
}

// Fill the entire canvas with a solid color.
pub fn clear(self: Canvas, color: integer) {
  cl_n = self.data.len();
  for cl_i in 0..cl_n {
    self.data[cl_i] = color;
  }
}

// Alpha-blend src over dst. Both are 0xAARRGGBB packed integers.
// Uses standard "src over" compositing: out = src * alpha + dst * (1 - alpha).
pub fn blend(dst: integer, src: integer) -> integer {
  sa = color_a(src);
  if sa == 255 { return src; }
  if sa == 0 { return dst; }
  inv = 255 - sa;
  br = (color_r(src) * sa + color_r(dst) * inv) / 255;
  bg = (color_g(src) * sa + color_g(dst) * inv) / 255;
  bb = (color_b(src) * sa + color_b(dst) * inv) / 255;
  ba = sa + (color_a(dst) * inv) / 255;
  rgba(br, bg, bb, ba)
}

// Draw a pixel with alpha blending at (x, y) — the compositing counterpart to
// `set_pixel`, and the one a caller reaching for alpha usually meant.
// Example: @GFX-002 — store versus composite, side by side.
pub fn blend_pixel(self: Canvas, bx: integer, by: integer, color: integer) {
  if bx >= 0 and bx < self.width and by >= 0 and by < self.height {
    bp_idx = by * self.width + bx;
    bp_d = &self.data;
    if bp_idx < len(bp_d) {
      bp_d[bp_idx] = blend(bp_d[bp_idx] ?? 0, color);
    }
  }
}

// Fill a rectangle with a solid color. Clipped to canvas bounds.  Like every
// solid primitive here it STORES the colour (see `set_pixel`); a rectangle drawn
// in a half-transparent colour is not a translucent overlay.
// Example: @GFX-002 — what the buffer holds afterwards.
pub fn fill_rect(self: Canvas, rx: integer, ry: integer, rw: integer, rh: integer, color: integer) {
  x0 = if rx < 0 { 0 } else { rx };
  y0 = if ry < 0 { 0 } else { ry };
  x1 = if rx + rw > self.width { self.width } else { rx + rw };
  y1 = if ry + rh > self.height { self.height } else { ry + rh };
  fr_d = &self.data;
  fr_n = len(fr_d);
  for fr_y in y0..y1 {
    for fr_x in x0..x1 {
      fr_idx = fr_y * self.width + fr_x;
      if fr_idx < fr_n {
        fr_d[fr_idx] = color;
      }
    }
  }
}

// Draw a horizontal line from (x0, y) to (x1, y). Clipped.  The end is
// EXCLUSIVE — `[x0, x1)` — and a reversed span draws nothing rather than being
// normalised.
// Example: @GFX-004 — where a span starts and stops, and what silence looks like.
pub fn hline(self: Canvas, hx0: integer, hx1: integer, hy: integer, color: integer) {
  if hy < 0 or hy >= self.height { return; }
  left = if hx0 < 0 { 0 } else { hx0 };
  right = if hx1 > self.width { self.width } else { hx1 };
  hl_d = &self.data;
  hl_n = len(hl_d);
  for hl_x in left..right {
    hl_idx = hy * self.width + hl_x;
    if hl_idx < hl_n {
      hl_d[hl_idx] = color;
    }
  }
}

// Draw a vertical line from (x, y0) to (x, y1). Clipped.  Exclusive end and
// no normalisation, exactly like `hline`.
// Example: @GFX-004 — the half-open span rule on both axes.
pub fn vline(self: Canvas, vx: integer, vy0: integer, vy1: integer, color: integer) {
  if vx < 0 or vx >= self.width { return; }
  top = if vy0 < 0 { 0 } else { vy0 };
  bottom = if vy1 > self.height { self.height } else { vy1 };
  vl_d = &self.data;
  vl_n = len(vl_d);
  for vl_y in top..bottom {
    vl_idx = vl_y * self.width + vx;
    if vl_idx < vl_n {
      vl_d[vl_idx] = color;
    }
  }
}

// Draw a rectangle outline (1px border). Clipped.  Built from four half-open
// spans, so (x, y, w, h) covers x .. x + w - 1 by y .. y + h - 1.
// Example: @GFX-004 — the exact pixels, and the hollow interior.
pub fn draw_rect(self: Canvas, drx: integer, dry: integer, drw: integer, drh: integer, color: integer) {
  self.hline(drx, drx + drw, dry, color);
  self.hline(drx, drx + drw, dry + drh - 1, color);
  self.vline(drx, dry, dry + drh, color);
  self.vline(drx + drw - 1, dry, dry + drh, color);
}

// --- GL2.2: Bresenham line drawing ---

// Draw a line from (x0, y0) to (x1, y1) using Bresenham's algorithm.
// Handles all octants. Each pixel is set (no blending).
pub fn draw_line(self: Canvas, lx0: integer, ly0: integer, lx1: integer, ly1: integer, color: integer) {
  dx = if lx1 > lx0 { lx1 - lx0 } else { lx0 - lx1 };
  dy = if ly1 > ly0 { ly1 - ly0 } else { ly0 - ly1 };
  sx = if lx0 < lx1 { 1 } else { -1 };
  sy = if ly0 < ly1 { 1 } else { -1 };
  err = dx - dy;
  cx = lx0;
  cy = ly0;
  for _ in 0..dx + dy + 1 {
    self.set_pixel(cx, cy, color);
    if cx == lx1 and cy == ly1 { break; }
    e2 = 2 * err;
    if e2 > -dy {
      err -= dy;
      cx += sx;
    }
    if e2 < dx {
      err += dx;
      cy += sy;
    }
  }
}

// --- GL2.3: Circle and ellipse ---

// Draw a circle outline using the midpoint algorithm.
// Center at (cx, cy) with the given radius. Clipped via set_pixel.
pub fn draw_circle(self: Canvas, ccx: integer, ccy: integer, radius: integer, color: integer) {
  cx = 0;
  cy = radius;
  d = 1 - radius;
  for _ in 0..radius * 4 + 4 {
    if cx > cy { break; }
    // Draw all 8 octant-symmetric points.
    self.set_pixel(ccx + cx, ccy + cy, color);
    self.set_pixel(ccx - cx, ccy + cy, color);
    self.set_pixel(ccx + cx, ccy - cy, color);
    self.set_pixel(ccx - cx, ccy - cy, color);
    self.set_pixel(ccx + cy, ccy + cx, color);
    self.set_pixel(ccx - cy, ccy + cx, color);
    self.set_pixel(ccx + cy, ccy - cx, color);
    self.set_pixel(ccx - cy, ccy - cx, color);
    if d < 0 {
      d += 2 * cx + 3;
    } else {
      d += 2 * (cx - cy) + 5;
      cy -= 1;
    }
    cx += 1;
  }
}

// Fill a circle (solid disk). Center at (cx, cy), given radius.
pub fn fill_circle(self: Canvas, fcx: integer, fcy: integer, radius: integer, color: integer) {
  cx = 0;
  cy = radius;
  d = 1 - radius;
  for _ in 0..radius * 4 + 4 {
    if cx > cy { break; }
    self.hline(fcx - cx, fcx + cx + 1, fcy + cy, color);
    self.hline(fcx - cx, fcx + cx + 1, fcy - cy, color);
    self.hline(fcx - cy, fcx + cy + 1, fcy + cx, color);
    self.hline(fcx - cy, fcx + cy + 1, fcy - cx, color);
    if d < 0 {
      d += 2 * cx + 3;
    } else {
      d += 2 * (cx - cy) + 5;
      cy -= 1;
    }
    cx += 1;
  }
}

// Fill an axis-aligned ellipse (solid). Center (cx, cy), radii (rx, ry).
pub fn fill_ellipse(self: Canvas, fex: integer, fey: integer, ferx: integer, fery: integer, color: integer) {
  fe_x = 0;
  fe_y = fery;
  fe_rx2 = ferx * ferx;
  fe_ry2 = fery * fery;
  fe_d1 = fe_ry2 - fe_rx2 * fery + fe_rx2 / 4;
  for _ in 0..ferx + fery + 1 {
    if fe_ry2 * fe_x > fe_rx2 * fe_y { break; }
    self.hline(fex - fe_x, fex + fe_x + 1, fey + fe_y, color);
    self.hline(fex - fe_x, fex + fe_x + 1, fey - fe_y, color);
    if fe_d1 < 0 {
      fe_d1 += fe_ry2 * (2 * fe_x + 3);
    } else {
      fe_d1 += fe_ry2 * (2 * fe_x + 3) + fe_rx2 * (-2 * fe_y + 2);
      fe_y -= 1;
    }
    fe_x += 1;
  }
  fe_d2 = fe_ry2 * (fe_x * 2 + 1) * (fe_x * 2 + 1) / 4 + fe_rx2 * (fe_y - 1) * (fe_y - 1) - fe_rx2 * fe_ry2;
  for _ in 0..ferx + fery + 1 {
    if fe_y < 0 { break; }
    self.hline(fex - fe_x, fex + fe_x + 1, fey + fe_y, color);
    self.hline(fex - fe_x, fex + fe_x + 1, fey - fe_y, color);
    if fe_d2 > 0 {
      fe_d2 += fe_rx2 * (-2 * fe_y + 3);
    } else {
      fe_d2 += fe_ry2 * (2 * fe_x + 2) + fe_rx2 * (-2 * fe_y + 3);
      fe_x += 1;
    }
    fe_y -= 1;
  }
}

// Draw an axis-aligned ellipse outline. Center (cx, cy), radii (rx, ry).
pub fn draw_ellipse(self: Canvas, ecx: integer, ecy: integer, erx: integer, ery: integer, color: integer) {
  // Midpoint ellipse algorithm — two regions.
  ex = 0;
  ey = ery;
  rx2 = erx * erx;
  ry2 = ery * ery;
  // Region 1: dy/dx > -1
  d1 = ry2 - rx2 * ery + rx2 / 4;
  for _ in 0..erx + ery + 1 {
    if ry2 * ex > rx2 * ey { break; }
    self.set_pixel(ecx + ex, ecy + ey, color);
    self.set_pixel(ecx - ex, ecy + ey, color);
    self.set_pixel(ecx + ex, ecy - ey, color);
    self.set_pixel(ecx - ex, ecy - ey, color);
    if d1 < 0 {
      d1 += ry2 * (2 * ex + 3);
    } else {
      d1 += ry2 * (2 * ex + 3) + rx2 * (-2 * ey + 2);
      ey -= 1;
    }
    ex += 1;
  }
  // Region 2: dy/dx <= -1
  d2 = ry2 * (ex * 2 + 1) * (ex * 2 + 1) / 4 + rx2 * (ey - 1) * (ey - 1) - rx2 * ry2;
  for _ in 0..erx + ery + 1 {
    if ey < 0 { break; }
    self.set_pixel(ecx + ex, ecy + ey, color);
    self.set_pixel(ecx - ex, ecy + ey, color);
    self.set_pixel(ecx + ex, ecy - ey, color);
    self.set_pixel(ecx - ex, ecy - ey, color);
    if d2 > 0 {
      d2 += rx2 * (-2 * ey + 3);
    } else {
      d2 += ry2 * (2 * ex + 2) + rx2 * (-2 * ey + 3);
      ex += 1;
    }
    ey -= 1;
  }
}

// --- GL2.4: Cubic Bezier curves ---

// Draw a cubic Bezier curve from (bx0,by0) to (bx3,by3) with control points
// (bx1,by1) and (bx2,by2). Uses adaptive subdivision — splits until segments
// are flat enough, then draws with Bresenham lines.
// Flatness threshold: max deviation of control points from the chord.
pub fn draw_bezier(self: Canvas, bx0: integer, by0: integer, bx1: integer, by1: integer, bx2: integer, by2: integer, bx3: integer, by3: integer, color: integer) {
  // Stack-based adaptive subdivision. Each segment = 8 entries (4 points × 2 coords).
  // Use a stack pointer (`bz_top`) with truncate-then-append on each
  // push so the lint sees only appends + slice reads, never indexed
  // writes — see the push site below.
  bz_sx: vector<integer> = [bx0, bx1, bx2, bx3];
  bz_sy: vector<integer> = [by0, by1, by2, by3];
  bz_top = 4;  // stack pointer = current vector length post-push
  for _ in 0..1000 {
    if bz_top == 0 { break; }
    // Pop segment (read 4 values, then decrease pointer).  `?? 0`
    // suppresses the OOB lint — `bz_top` is the stack pointer kept
    // invariantly >= 4 by the `break if bz_top == 0` guard above plus
    // the push-4-pop-4 protocol below.
    bz_p0x = bz_sx[bz_top - 4] ?? 0; bz_p1x = bz_sx[bz_top - 3] ?? 0;
    bz_p2x = bz_sx[bz_top - 2] ?? 0; bz_p3x = bz_sx[bz_top - 1] ?? 0;
    bz_p0y = bz_sy[bz_top - 4] ?? 0; bz_p1y = bz_sy[bz_top - 3] ?? 0;
    bz_p2y = bz_sy[bz_top - 2] ?? 0; bz_p3y = bz_sy[bz_top - 1] ?? 0;
    bz_top -= 4;
    // Flatness test: cross product distances of control points from chord
    bz_dx = bz_p3x - bz_p0x;
    bz_dy = bz_p3y - bz_p0y;
    bz_d1 = (bz_p1x - bz_p3x) * bz_dy - (bz_p1y - bz_p3y) * bz_dx;
    bz_d2 = (bz_p2x - bz_p3x) * bz_dy - (bz_p2y - bz_p3y) * bz_dx;
    if bz_d1 < 0 { bz_d1 = -bz_d1; }
    if bz_d2 < 0 { bz_d2 = -bz_d2; }
    bz_flat = if bz_d1 > bz_d2 { bz_d1 } else { bz_d2 };
    bz_chord2 = bz_dx * bz_dx + bz_dy * bz_dy;
    if bz_flat * bz_flat <= bz_chord2 or bz_chord2 == 0 {
      self.draw_line(bz_p0x, bz_p0y, bz_p3x, bz_p3y, color);
    } else {
      // de Casteljau subdivision at t=0.5
      bz_m01x = (bz_p0x + bz_p1x) / 2; bz_m01y = (bz_p0y + bz_p1y) / 2;
      bz_m12x = (bz_p1x + bz_p2x) / 2; bz_m12y = (bz_p1y + bz_p2y) / 2;
      bz_m23x = (bz_p2x + bz_p3x) / 2; bz_m23y = (bz_p2y + bz_p3y) / 2;
      bz_m012x = (bz_m01x + bz_m12x) / 2; bz_m012y = (bz_m01y + bz_m12y) / 2;
      bz_m123x = (bz_m12x + bz_m23x) / 2; bz_m123y = (bz_m12y + bz_m23y) / 2;
      bz_mx = (bz_m012x + bz_m123x) / 2; bz_my = (bz_m012y + bz_m123y) / 2;
      // Push second half first (so first half is popped next).
      // Truncate-then-append: the stack pointer `bz_top` is always
      // the next free slot; truncating to `bz_top` ensures `+=`
      // appends at that slot.  A vector keeps its own slice in place
      // (`v = v[0..n]`), so the pop costs no copy.
      bz_sx = bz_sx[0..bz_top];
      bz_sy = bz_sy[0..bz_top];
      bz_sx += [bz_mx, bz_m123x, bz_m23x, bz_p3x];
      bz_sy += [bz_my, bz_m123y, bz_m23y, bz_p3y];
      bz_top += 4;
      bz_sx += [bz_p0x, bz_m01x, bz_m012x, bz_mx];
      bz_sy += [bz_p0y, bz_m01y, bz_m012y, bz_my];
      bz_top += 4;
    }
  }
}

// --- GL2.6: Wu anti-aliased line ---

// Draw an anti-aliased line using Xiaolin Wu's algorithm.
// Uses blend_pixel for sub-pixel coverage.
pub fn draw_aa_line(self: Canvas, ax0: integer, ay0: integer, ax1: integer, ay1: integer, color: integer) {
  aa_dx = if ax1 > ax0 { ax1 - ax0 } else { ax0 - ax1 };
  aa_dy = if ay1 > ay0 { ay1 - ay0 } else { ay0 - ay1 };
  aa_steep = aa_dy > aa_dx;
  // If steep, we step along y instead of x.
  // Map to canonical form: always step along the longer axis.
  aa_x0 = if aa_steep { ay0 } else { ax0 };
  aa_y0 = if aa_steep { ax0 } else { ay0 };
  aa_x1 = if aa_steep { ay1 } else { ax1 };
  aa_y1 = if aa_steep { ax1 } else { ay1 };
  // Ensure we draw left-to-right
  if aa_x0 > aa_x1 {
    aa_tmp = aa_x0; aa_x0 = aa_x1; aa_x1 = aa_tmp;
    aa_tmp = aa_y0; aa_y0 = aa_y1; aa_y1 = aa_tmp;
  }
  aa_run = aa_x1 - aa_x0;
  if aa_run == 0 {
    // Single pixel
    self.set_pixel(ax0, ay0, color);
    return;
  }
  // Fixed-point gradient: rise * 256 / run.  `?? 0` suppresses the
  // div-by-zero lint — `aa_run == 0` is the vertical-line case
  // handled above with `set_pixel(...); return;`.  Parens scope `??`
  // to the div so the parser's null-fallback swap recognises it.
  aa_rise = aa_y1 - aa_y0;
  aa_grad256 = (aa_rise * 256 / aa_run) ?? 0;
  // y in fixed-point (8 fractional bits)
  aa_yf = aa_y0 * 256;
  aa_cr = graphics::color_r(color);
  aa_cg = graphics::color_g(color);
  aa_cb = graphics::color_b(color);
  for aa_xi in aa_x0..aa_x1 + 1 {
    aa_yi = aa_yf / 256;
    aa_frac = aa_yf - aa_yi * 256;
    if aa_frac < 0 { aa_frac += 256; aa_yi -= 1; }
    aa_a1 = 255 - aa_frac;
    aa_a2 = aa_frac;
    aa_c1 = graphics::rgba(aa_cr, aa_cg, aa_cb, aa_a1);
    aa_c2 = graphics::rgba(aa_cr, aa_cg, aa_cb, aa_a2);
    if aa_steep {
      self.blend_pixel(aa_yi, aa_xi, aa_c1);
      if aa_a2 > 0 { self.blend_pixel(aa_yi + 1, aa_xi, aa_c2); }
    } else {
      self.blend_pixel(aa_xi, aa_yi, aa_c1);
      if aa_a2 > 0 { self.blend_pixel(aa_xi, aa_yi + 1, aa_c2); }
    }
    aa_yf += aa_grad256;
  }
}

// --- GL2.5: Triangle fill (scanline) ---

// Fill a triangle with vertices (tx0,ty0), (tx1,ty1), (tx2,ty2).
// Uses flat-top/flat-bottom decomposition with scanline fill.
pub fn fill_triangle(self: Canvas, tx0: integer, ty0: integer, tx1: integer, ty1: integer, tx2: integer, ty2: integer, color: integer) {
  // Sort vertices by y: ta_y <= tb_y <= tc_y
  ta_x = tx0; ta_y = ty0;
  tb_x = tx1; tb_y = ty1;
  tc_x = tx2; tc_y = ty2;
  if ta_y > tb_y { tr_t = ta_x; ta_x = tb_x; tb_x = tr_t; tr_t = ta_y; ta_y = tb_y; tb_y = tr_t; }
  if tb_y > tc_y { tr_t = tb_x; tb_x = tc_x; tc_x = tr_t; tr_t = tb_y; tb_y = tc_y; tc_y = tr_t; }
  if ta_y > tb_y { tr_t = ta_x; ta_x = tb_x; tb_x = tr_t; tr_t = ta_y; ta_y = tb_y; tb_y = tr_t; }
  if ta_y == tc_y { return; }  // degenerate
  for tr_y in ta_y..tc_y + 1 {
    // x along edge A→C (the long edge, always valid).
    //
    // MULTIPLY BEFORE DIVIDING.  These are integers, so
    // `(tr_y - ta_y) / (tc_y - ta_y)` on its own is 0 on every
    // scanline but the last — which collapses the whole fill to a
    // vertical line at the apex plus the base row.  Scaling the run
    // first keeps the ratio's precision inside the integer divide.
    //
    // `?? 0` suppresses the div lint — `tc_y - ta_y != 0` is
    // guaranteed by the degenerate-triangle early-return above.
    // Parens scope `??` to just the div so the parser's null-fallback
    // swap fires.
    tr_xac = ta_x + ((tc_x - ta_x) * (tr_y - ta_y) / (tc_y - ta_y) ?? 0);
    // x along the short edge (A→B or B→C depending on scanline).
    // Both branches gate their divisor explicitly with the AND-side
    // `!= ta_y` / `!= tb_y` check, so `?? 0` is lint suppression.
    tr_xother = tr_xac;
    if tr_y < tb_y and tb_y != ta_y {
      tr_xother = ta_x + ((tb_x - ta_x) * (tr_y - ta_y) / (tb_y - ta_y) ?? 0);
    }
    if tr_y >= tb_y and tc_y != tb_y {
      tr_xother = tb_x + ((tc_x - tb_x) * (tr_y - tb_y) / (tc_y - tb_y) ?? 0);
    }
    if tr_y >= tb_y and tc_y == tb_y {
      tr_xother = tb_x;
    }
    tr_left = if tr_xac < tr_xother { tr_xac } else { tr_xother };
    tr_right = if tr_xac > tr_xother { tr_xac } else { tr_xother };
    self.hline(tr_left, tr_right + 1, tr_y, color);
  }
}

/// A point on the canvas, in pixels.
///
/// Exists because a polygon is a LIST of them and `fill_triangle`'s six loose
/// integers do not generalise — six is already the edge of what a caller gets
/// right in order, and a polygon has no fixed count.
///
/// NOT called `Point`: `mesh3d::LightType` has a `Point` variant and `graphics`
/// depends on mesh3d, so the name is taken and the collision is a hard error
/// ("struct 'Point' conflicts with a enumvalue of the same name"). `Vertex` is
/// mesh3d's too. Reach for `Coord` in 2-D graphics code and the 3-D names stay
/// where they belong.
pub struct Coord {
  pub px: integer,
  pub py: integer,
}

/// Fill a closed polygon under the EVEN-ODD rule.
///
/// The polygon closes itself: the last point joins the first, so a triangle is
/// three points and not four. Fewer than three points draws nothing.
///
/// Even-odd means a point is inside when a ray from it crosses the outline an odd
/// number of times, so a self-intersecting outline leaves its overlap EMPTY — the
/// classic five-point star is a pentagon-shaped hole with five filled arms. That
/// is a choice, not a bug: the alternative (non-zero winding) fills the middle,
/// and the two disagree on exactly the shapes people draw deliberately.
///
/// Matches `fill_triangle` pixel for pixel on a triangle, which is the reason the
/// row rule below is inclusive rather than the half-open rule a scanline filler
/// usually takes. See the note on `polygon_crossings`.
// Example: @GFX-006 — the star's hollow middle, and the triangle agreement.
pub fn fill_polygon(self: Canvas, pts: const vector<Coord>, color: integer) {
  fp_n = len(pts);
  if fp_n < 3 { return; }
  fp_top = pts[0]?.py;
  fp_bot = fp_top;
  for p in pts {
    if p.py < fp_top { fp_top = p.py; }
    if p.py > fp_bot { fp_bot = p.py; }
  }
  if fp_top < 0 { fp_top = 0; }
  if fp_bot >= self.height { fp_bot = self.height - 1; }
  for fp_y in fp_top..=fp_bot {
    fp_xs = polygon_crossings(pts, fp_y, fp_y == fp_bot);
    fp_i = 0;
    while fp_i + 1 < len(fp_xs) {
      // Inclusive span, like `fill_triangle`: `hline` takes a half-open end, so
      // the right edge is +1.
      self.hline(fp_xs[fp_i]?, fp_xs[fp_i + 1]? + 1, fp_y, color);
      fp_i += 2;
    }
  }
}

/// Where the outline crosses scanline `y`, left to right.
///
/// The rule is HALF-OPEN on an edge's lower end (`ylo <= y < yhi`) and that is
/// what makes even-odd work: a vertex the outline passes straight through belongs
/// to exactly one of its two edges, so it counts once. Count it twice — the
/// obvious inclusive rule — and a through-vertex yields two crossings at the same
/// x, which pair with each other and fill a single pixel where a whole span
/// belonged.
///
/// The cost is that the polygon's LOWEST row loses every edge, so `closing` turns
/// the rule inclusive for exactly that row. It is safe there and nowhere else: the
/// half-open rule exists to disambiguate a vertex the outline passes THROUGH, and
/// the extreme row has none — every edge meeting it goes back up, so no crossing
/// is counted twice. Measured: left half-open throughout, a triangle loses its
/// bottom vertex (1 px) or its whole base (34 px on a 34-wide one), which was the
/// entire `fill_triangle` disagreement.
fn polygon_crossings(pc_pts: const vector<Coord>, pc_y: integer,
                     closing: boolean) -> vector<integer> {
  pc_out: vector<integer> = [];
  pc_n = len(pc_pts);
  for i in 0..pc_n {
    pc_a = pc_pts[i]?;
    // `% pc_n` types nullable because a zero divisor answers null; `?? 0` names the
    // wrap target, which is where the last edge closes anyway.  The loop does not run
    // at all when `pc_n` is 0, so the default is unreachable rather than chosen.
    pc_b = pc_pts[(i + 1) % pc_n ?? 0]?;
    pc_ylo = if pc_a.py < pc_b.py { pc_a.py } else { pc_b.py };
    pc_yhi = if pc_a.py < pc_b.py { pc_b.py } else { pc_a.py };
    // A horizontal edge crosses no scanline: its endpoints are already carried by
    // the two edges that meet it, and counting it would flip parity along a row it
    // only touches.
    if pc_ylo == pc_yhi { continue }
    if pc_y < pc_ylo { continue }
    if pc_y > pc_yhi { continue }
    if pc_y == pc_yhi && !closing { continue }
    // Interpolate from the edge's TOP end, and multiply before dividing — the
    // same integer-precision rule `fill_triangle` documents.
    pc_ty = if pc_a.py < pc_b.py { pc_a } else { pc_b };
    pc_by = if pc_a.py < pc_b.py { pc_b } else { pc_a };
    pc_out += [pc_ty.px + ((pc_by.px - pc_ty.px) * (pc_y - pc_ty.py) / (pc_by.py - pc_ty.py) ?? 0)];
  }
  // Insertion sort: a crossing list is a handful of numbers, and a fresh vector
  // per scanline would cost more than the compare.
  for i in 1..len(pc_out) {
    pc_v = pc_out[i]?;
    pc_j = i;
    while pc_j > 0 && pc_out[pc_j - 1]? > pc_v {
      pc_out[pc_j] = pc_out[pc_j - 1]?;
      pc_j -= 1;
    }
    pc_out[pc_j] = pc_v;
  }
  pc_out
}

// ── Resampling ──────────────────────────────────────────────────────

/// Fixed-point fraction bits for resample weights — Pillow's `PRECISION_BITS`.
RESAMPLE_PREC = 22;
RESAMPLE_PI = 3.14159265358979323846;
BICUBIC_A = -0.5;

fn sinc_at(x: float) -> float {
  if x == 0.0 { return 1.0 }
  sc_xp = x * RESAMPLE_PI;
  (sin(sc_xp) / sc_xp)?
}

/// Pillow's bicubic kernel — the Keys cubic with `a = -0.5`, support 2.
///
/// The two branches are one polynomial each and the constant is the whole
/// identity of the filter: `a = -0.5` is Catmull-Rom, and another `a` is a
/// different picture, not a rounding difference.
fn bicubic_at(bc_x0: float) -> float {
  bc_x = if bc_x0 < 0.0 { -bc_x0 } else { bc_x0 };
  if bc_x < 1.0 { return ((BICUBIC_A + 2.0) * bc_x - (BICUBIC_A + 3.0)) * bc_x * bc_x + 1.0 }
  if bc_x < 2.0 { return (((bc_x - 5.0) * bc_x + 8.0) * bc_x - 4.0) * BICUBIC_A }
  0.0
}

/// The Lanczos-3 kernel: `sinc(x) * sinc(x/3)` inside a radius of 3, else 0.
fn lanczos_at(lz_x0: float) -> float {
  lz_x = if lz_x0 < 0.0 { -lz_x0 } else { lz_x0 };
  if lz_x < 3.0 { return sinc_at(lz_x) * sinc_at(lz_x / 3.0) }
  0.0
}

/// One axis of Pillow's `precompute_coeffs`, flattened into three parallel
/// vectors: each output index gets a window START, a TAP COUNT, and that many
/// fixed-point weights appended to `kk`.
///
/// The weights are normalised to sum to 1 in floating point and only then scaled
/// to integers, rounding AWAY from zero — both filters here have negative lobes,
/// and rounding them the same direction as the positive ones is what keeps the
/// taps summing back to `1 << RESAMPLE_PREC`.
///
/// `support0` and `filt` are the ONLY things that differ between Pillow's
/// filters, which is why they are parameters rather than two copies of this
/// function: the window arithmetic, the normalisation and the fixed-point
/// rounding are one derived fact and belong in one place.
fn resample_coeffs(in_size: integer, out_size: integer, support0: float,
                   filt: fn(float) -> float, starts: &vector<integer>,
                   counts: &vector<integer>, kk: &vector<integer>) {
  rc_scale = ((in_size as float) / (out_size as float))?;
  // Upscaling does not widen the kernel: the filter scale floors at 1.
  rc_fscale = if rc_scale < 1.0 { 1.0 } else { rc_scale };
  rc_support = support0 * rc_fscale;
  rc_ss = (1.0 / rc_fscale)?;
  for xx in 0..out_size {
    rc_centre = ((xx as float) + 0.5) * rc_scale;
    rc_min = (rc_centre - rc_support + 0.5) as integer;
    if rc_min < 0 { rc_min = 0; }
    rc_max = (rc_centre + rc_support + 0.5) as integer;
    if rc_max > in_size { rc_max = in_size; }
    rc_max -= rc_min;
    rc_row: vector<float> = [];
    rc_ww = 0.0;
    for x in 0..rc_max {
      rc_w = filt((((x + rc_min) as float) - rc_centre + 0.5) * rc_ss);
      rc_row += [rc_w];
      rc_ww += rc_w;
    }
    for x in 0..rc_max {
      rc_k = rc_row[x]?;
      if rc_ww != 0.0 { rc_k = (rc_k / rc_ww)?; }
      rc_scaled = rc_k * ((1 << RESAMPLE_PREC) as float);
      kk += [if rc_k < 0.0 { (rc_scaled - 0.5) as integer }
             else { (rc_scaled + 0.5) as integer }];
    }
    starts += [rc_min];
    counts += [rc_max];
  }
}

/// Fixed-point accumulator to a byte: shift the fraction off and clamp.
fn resample_clip(rq_v: integer) -> integer {
  rq_s = rq_v >> RESAMPLE_PREC;
  if rq_s < 0 { return 0 }
  if rq_s > 255 { return 255 }
  rq_s
}

/// Resample this canvas to `ow` x `oh` with a Lanczos-3 filter.
///
/// Byte-identical to Pillow's `Image.resize(..., Image.LANCZOS)`, which is the
/// point: the `.draw` corpus renders at 3x and downscales with exactly that, so a
/// renderer that resamples any other way cannot be pixel-compared against it
/// however good it looks (@PLN146 W0 finding 5).
///
/// **Alpha is premultiplied across the resample and undone after**, because
/// Pillow defines `resize` on an image with alpha as
/// `convert("RGBa") -> resize -> convert("RGBA")`. That is a contract, not an
/// optimisation: resampling straight RGBA lets a transparent texel's colour bleed
/// into its neighbours, and the two disagree on any edge where alpha varies.
/// Both roundings are Pillow's and neither is the obvious one — `(v*a + 127)/255`
/// going in, a TRUNCATING divide coming out, and alpha 0 passes its colour
/// through untouched rather than going black.
// Example: @GFX-007 — why a 3x supersample plus this is not the same picture as
// drawing once at final size.
pub fn resize_lanczos(self: const Canvas, ow: integer, oh: integer) -> Canvas {
  resample(self, ow, oh, 3.0, lanczos_at)
}

/// Resample with a BICUBIC filter — Pillow's `Image.resize` default.
///
/// The default is the reason this exists: `resize(size)` with no `resample=`
/// argument is bicubic, and code that builds a small image and enlarges it (a
/// gradient computed at 100x100, say) takes that path without naming it. Read
/// the call site's filter off the ARGUMENT LIST and it looks like there isn't
/// one.
///
/// ⚠ Bicubic has negative lobes, so an ENLARGEMENT overshoots: a hard 40→200
/// step upscaled 4x spans 28..212 in Pillow and here alike. That is the filter,
/// not a defect — clamping it away would be the defect.
pub fn resize_bicubic(self: const Canvas, ow: integer, oh: integer) -> Canvas {
  resample(self, ow, oh, 2.0, bicubic_at)
}

/// Pillow's two-pass resample, with the filter left to the caller.
///
/// One body, because the passes, the premultiply and the fixed-point
/// accumulation are the same derived fact for every filter — only the kernel and
/// its support differ.
fn resample(self: const Canvas, ow: integer, oh: integer, support0: float,
            filt: fn(float) -> float) -> Canvas {
  if ow < 1 || oh < 1 || self.width < 1 || self.height < 1 {
    return canvas(if ow < 1 { 1 } else { ow }, if oh < 1 { 1 } else { oh }, 0);
  }
  rl_iw = self.width;
  rl_ih = self.height;
  // Premultiplied channel planes, in Pillow's RGBA byte order.
  rl_pre: vector<integer> = [];
  for i in 0..(rl_iw * rl_ih) {
    rl_c = self.data[i]?;
    rl_a = (rl_c >> 24) & 255;
    rl_pre += [(((rl_c >> 16) & 255) * rl_a + 127) / 255 ?? 0,
               (((rl_c >> 8) & 255) * rl_a + 127) / 255 ?? 0,
               ((rl_c & 255) * rl_a + 127) / 255 ?? 0,
               rl_a];
  }
  hs: vector<integer> = []; hc: vector<integer> = []; hk: vector<integer> = [];
  resample_coeffs(rl_iw, ow, support0, filt, hs, hc, hk);
  rl_mid: vector<integer> = [];
  for _ in 0..(ow * rl_ih * 4) { rl_mid += [0]; }
  rl_base = 0;
  for xx in 0..ow {
    rl_xmin = hs[xx]?;
    rl_n = hc[xx]?;
    for yy in 0..rl_ih {
      for ch in 0..4 {
        rl_acc = 1 << (RESAMPLE_PREC - 1);
        for x in 0..rl_n {
          rl_acc += rl_pre[(yy * rl_iw + rl_xmin + x) * 4 + ch]? * hk[rl_base + x]?;
        }
        rl_mid[(yy * ow + xx) * 4 + ch] = resample_clip(rl_acc);
      }
    }
    rl_base += rl_n;
  }
  vs: vector<integer> = []; vc: vector<integer> = []; vk: vector<integer> = [];
  resample_coeffs(rl_ih, oh, support0, filt, vs, vc, vk);
  rl_out = canvas(ow, oh, 0);
  rl_od = &rl_out.data;
  rl_vbase = 0;
  for yy in 0..oh {
    rl_ymin = vs[yy]?;
    rl_n = vc[yy]?;
    for xx in 0..ow {
      rl_ch: vector<integer> = [];
      for ch in 0..4 {
        rl_acc = 1 << (RESAMPLE_PREC - 1);
        for y in 0..rl_n {
          rl_acc += rl_mid[((rl_ymin + y) * ow + xx) * 4 + ch]? * vk[rl_vbase + y]?;
        }
        rl_ch += [resample_clip(rl_acc)];
      }
      // Undo the premultiply and repack to 0xAARRGGBB.
      rl_a = rl_ch[3]?;
      rl_rgb: vector<integer> = [];
      for ch in 0..3 {
        rl_v = rl_ch[ch]?;
        if rl_a == 0 { rl_rgb += [rl_v]; }
        else {
          rl_u = (rl_v * 255) / rl_a ?? 0;
          rl_rgb += [if rl_u > 255 { 255 } else { rl_u }];
        }
      }
      rl_od[yy * ow + xx] = (rl_a << 24) | (rl_rgb[0]? << 16) | (rl_rgb[1]? << 8) | rl_rgb[2]?;
    }
    rl_vbase += rl_n;
  }
  rl_out
}

// Native: write packed pixel data to a PNG file.
fn save_png_raw(path: text, width: integer, height: integer, data: const vector<integer>) -> boolean;
#native "loft_save_png"

// Save canvas as a PNG file. Automatically uses RGBA if any pixel has alpha < 255,
// otherwise uses RGB. Returns true on success.
// Example: @GFX-005 — the choice is read off the pixels, so ONE alpha-0 pixel
// (a hand-written hex literal — @GFX-001) makes the whole file RGBA and that
// pixel a transparent hole.
pub fn save_png(self: const Canvas, path: text) -> boolean {
  save_png_raw(path, self.width, self.height, self.data)
}

// Capture the current GL back-buffer to an RGB PNG.  Call after a frame's
// draw calls and BEFORE gl_swap_buffers (reads GL_BACK).  Works on a
// headless / Wayland desktop where the window itself can't be grabbed.
pub fn gl_screenshot(width: integer, height: integer, path: text) -> boolean;
#native "loft_gl_screenshot"

// --- OpenGL (GL5) ---
// Native OpenGL functions for window management and rendering.
// Names match the symbols registered via loft_register_v1 in the cdylib.

// Create a window with an OpenGL 3.3 context. Returns true on success.
pub fn gl_create_window(width: integer, height: integer, title: text) -> boolean;
#native "loft_gl_create_window"

// Open a borderless fullscreen window at the primary monitor's native
// resolution. Returns true on success. Read the actual viewport size
// afterwards with `gl_window_width` / `gl_window_height` if you need
// to set up an aspect-aware camera.
pub fn gl_create_fullscreen_window(title: text) -> boolean;
#native "loft_gl_create_fullscreen_window"

// Toggle fullscreen on the existing window (runtime flip, cheaper
// than recreating the GL context — textures / VAOs / shaders
// survive).  Pass `true` for borderless fullscreen, `false` for
// windowed.  Browsers (WASM) require a user gesture to enter
// fullscreen; calling outside one is non-fatal.
pub fn gl_set_fullscreen(on: boolean);
#native "loft_gl_set_fullscreen"

// Current window inner size in physical pixels.  Query after creating a
// (especially fullscreen) window so projection / 2D ortho / overlays use
// the real resolution rather than a windowed hint.
pub fn gl_window_width() -> integer;
#native "loft_gl_window_width"
// And its height — the pair is what a projection or a 2-D ortho is built from.
pub fn gl_window_height() -> integer;
#native "loft_gl_window_height"

// Poll window events. Returns false when the window should close.
pub fn gl_poll_events() -> boolean;
#native "loft_gl_poll_events"

// Swap buffers (present the frame).
pub fn gl_swap_buffers();
#native "loft_gl_swap_buffers"

// Clear the screen with an RGBA color (packed as 0xRRGGBBAA).
pub fn gl_clear(color: integer);
#native "loft_gl_clear"

// Destroy the window and OpenGL context.
pub fn gl_destroy_window();
#native "loft_gl_destroy_window"

// Compile and link a shader program. Returns the program ID (0 on failure).
pub fn gl_create_shader(vertex_source: text, fragment_source: text) -> integer;
#native "loft_gl_create_shader"

// Use a shader program for subsequent draw calls.
pub fn gl_use_shader(program: integer);
#native "loft_gl_use_shader"

// Draw a VAO with vertex_count vertices as triangles.
pub fn gl_draw(vao: integer, vertex_count: integer);
#native "loft_gl_draw"

// Upload a vector<single> as a vertex buffer. Returns VAO handle.
// stride = floats per vertex (3=pos, 6=pos+normal, 10=pos+normal+color).
// Native codegen: loft_gl_upload_vertices(data_ptr: *const f32, count: u32, stride: i32) -> i32
pub fn gl_upload_vertices(data: vector<single>, stride: integer) -> integer;
#native "loft_gl_upload_vertices"

// ── Instanced rendering ───────────────────────────────────────────────────
// Draw one base mesh many times in a single call, each instance pulling
// per-instance attributes from a SECOND buffer. The contract: vertex
// attributes occupy locations 0-4 (per-vertex, divisor 0, via gl_upload_*);
// instance attributes occupy locations >=5 (divisor 1). The CALLER owns the
// instance layout (component count + stride + offset, in floats) and must
// match the shader's `layout(location=N)` — explicit, so no heuristic.

// Upload per-instance data to a DYNAMIC_DRAW buffer. Returns the VBO handle
// (pass it to gl_instance_attrib). DYNAMIC because instances change per frame.
pub fn gl_upload_instance_buffer(data: vector<single>) -> integer;
#native "loft_gl_upload_instance_buffer"

// Bind instance VBO `ivbo`'s field to attribute `location` on `vao`, advancing
// once per INSTANCE (VertexAttribDivisor=1). components = floats in the field
// (2=vec2, 4=vec4); stride_floats = floats per instance record; offset_floats =
// this field's start within the record. Use locations >=5 to clear the vertex attrs.
pub fn gl_instance_attrib(vao: integer, ivbo: integer, location: integer, components: integer, stride_floats: integer, offset_floats: integer);
#native "loft_gl_instance_attrib"

// Draw vertex_count vertices of `vao` as triangles, instance_count times.
pub fn gl_draw_instanced(vao: integer, vertex_count: integer, instance_count: integer);
#native "loft_gl_draw_instanced"

// ── Dynamic buffer update + index buffers ─────────────────────────────────

// Orphan + re-upload an existing VBO (returned by gl_upload_vertices /
// gl_upload_instance_buffer) with new data, DYNAMIC_DRAW — per-frame updates
// without recreating the buffer.
pub fn gl_update_buffer(vbo: integer, data: vector<single>);
#native "loft_gl_update_buffer"

// Upload triangle indices as an element (index) buffer bound to `vao`, so
// gl_draw_elements(vao, index_count, mode) draws indexed. Returns the EBO handle.
pub fn gl_upload_indices(vao: integer, data: vector<integer>) -> integer;
#native "loft_gl_upload_indices"

// ── Per-group VBO set — a reusable multi-VBO renderer ─────────────────────
//
// A `GroupVboSet` keeps one independently-uploadable VBO per "group" (keyed by
// an integer group key), so a consumer that partitions its world into render
// groups (e.g. gridmesh's `all_groups` / `collect_dirty_groups`) can RE-UPLOAD
// ONLY the groups whose geometry changed (`group_vbos_upsert` on the dirty
// groups) while every other group keeps its cached VBO — turning a per-edit
// O(N) full re-upload into O(dirty).  Generic: keyed by an integer, holds the
// baked `vector<single>` the consumer produced; it knows nothing about the
// consumer's mesh type.  Each group also stores its world-space XZ bounds so a
// frustum-cull draw can be layered on later (the projector / moros payoff).
//
// One consumer is the audience projector (per-group crystal + ground VBOs); the
// moros terrain renderer is the next.  GL calls cannot run headless, so this is
// validated by those consumers, not a unit test.
struct GroupVbo {
  const gk:    integer,   // group key (NOT 'key' — reserved in hash-value structs)
  const vao:   integer,
  const count: integer,   // vertices = floats / stride
  const min_x: single, const min_z: single, const max_x: single, const max_z: single,   // world bounds (future cull)
}

// The vertex buffers of a grouped mesh: one `GroupVbo` per group key in `slots`, all
// sharing one vertex layout (`stride` floats per vertex) and one `draw_mode`.
pub struct GroupVboSet {
  pub slots: hash<GroupVbo[gk]>,   // not const: reassigned (`set.slots = []`) + grown via `+=`
  const stride:    integer,   // floats per vertex (e.g. 14 crystal, 10 ground)
  const draw_mode: integer,   // DRAW_TRIANGLES / DRAW_LINES / …
}

// Create an empty set for a fixed vertex stride + draw mode.
pub fn group_vbos_new(stride: integer, draw_mode: integer) -> GroupVboSet {
  GroupVboSet{ slots: [], stride: stride, draw_mode: draw_mode }
}

// Upload (or RE-upload) one group's baked vertices: delete the group's old VAO
// if present, upload the new data, and record the handle + vertex count + world
// bounds.  Call this only for the DIRTY groups each edit; untouched groups keep
// their cached VBOs.
pub fn group_vbos_upsert(set: GroupVboSet, gk: integer, verts: vector<single>,
                         min_x: single, min_z: single, max_x: single, max_z: single) {
  old = set.slots[gk];
  if old != null { gl_delete_vao(old.vao); set.slots[gk] = null; }
  vao = gl_upload_vertices(verts, set.stride);
  set.slots += [GroupVbo{ gk: gk, vao: vao, count: (len(verts) / set.stride) ?? 0,
                          min_x: min_x, min_z: min_z, max_x: max_x, max_z: max_z }];
}

// (An emptied group is handled by `group_vbos_upsert` with zero vertices: it
// stores a count-0 slot that `group_vbos_draw_all` skips.  A dedicated
// `group_vbos_remove` that frees a single empty group's VAO via a keyed remove
// (`set.slots[gk] = null`) is now unblocked — the @P320 false "never modified"
// rejection of a `&`-param whose only mutation is a keyed remove was fixed
// 2026-05-23 — but is not yet needed, so it stays unwritten.)

// Draw every group's cached VBO with the set's draw mode.  (Per-group frustum
// culling — skip groups whose world bounds fall outside the view — is a future
// addition; the bounds are already stored.)
pub fn group_vbos_draw_all(set: const GroupVboSet) {
  for gv in set.slots {
    if gv.count > 0 { gl_draw_mode(gv.vao, gv.count, set.draw_mode); }
  }
}

// Free every group's VAO and clear the set (call on teardown / world reset).
pub fn group_vbos_destroy(set: GroupVboSet) {
  for gvd in set.slots { gl_delete_vao(gvd.vao); }
  set.slots = [];
}

// Set a mat4 uniform on a shader program. mat is a Mat4.m vector (16 floats).
// Native codegen: loft_gl_set_mat4(program: i32, name_ptr, name_len, mat_ptr: *const f64, count: u32)
pub fn gl_set_uniform_mat4(program: integer, name: text, mat: const vector<float>);
#native "loft_gl_set_mat4"

// --- Uniforms ---

// Set a float uniform.
pub fn gl_set_uniform_float(program: integer, name: text, val: float);
#native "loft_gl_set_uniform_float"

// Set an integer uniform (also used for sampler2D texture unit bindings).
pub fn gl_set_uniform_int(program: integer, name: text, val: integer);
#native "loft_gl_set_uniform_int"

// Set a vec2 uniform (e.g. screen size, texel size, a 2D offset).
pub fn gl_set_uniform_vec2(program: integer, name: text, x: float, y: float);
#native "loft_gl_set_uniform_vec2"

// Set a vec3 uniform (e.g. light position, color).
pub fn gl_set_uniform_vec3(program: integer, name: text, x: float, y: float, z: float);
#native "loft_gl_set_uniform_vec3"

// Set a vec4 uniform (e.g. an RGBA color, a rect x/y/w/h).
pub fn gl_set_uniform_vec4(program: integer, name: text, x: float, y: float, z: float, w: float);
#native "loft_gl_set_uniform_vec4"

// --- GL state ---

// Capability constants for gl_enable/gl_disable:
pub const GL_DEPTH_TEST = 1;
pub const GL_BLEND = 2;
pub const GL_CULL_FACE = 3;
pub const GL_SCISSOR_TEST = 4;

// Enable a GL capability (GL_DEPTH_TEST, GL_BLEND, GL_CULL_FACE, GL_SCISSOR_TEST).
pub fn gl_enable(cap: integer);
#native "loft_gl_enable"

// Disable a GL capability.
pub fn gl_disable(cap: integer);
#native "loft_gl_disable"

// Blend factor constants for gl_blend_func:
pub const BLEND_ZERO = 0;
pub const BLEND_ONE = 1;
pub const BLEND_SRC_ALPHA = 2;
pub const BLEND_ONE_MINUS_SRC_ALPHA = 3;
pub const BLEND_DST_ALPHA = 4;
pub const BLEND_ONE_MINUS_DST_ALPHA = 5;

// Set blend function (e.g. gl_blend_func(BLEND_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA)).
pub fn gl_blend_func(src: integer, dst: integer);
#native "loft_gl_blend_func"

// Set which face to cull (0=back, 1=front).
pub fn gl_cull_face(face: integer);
#native "loft_gl_cull_face"

// Enable/disable depth buffer writing.
pub fn gl_depth_mask(write: boolean);
#native "loft_gl_depth_mask"

// Block until every GL command issued so far has completed.
//
// The call that makes a read-back trustworthy: `gl_screenshot` and any other
// framebuffer read otherwise race the driver, so the same program can produce a
// complete frame or an empty one from run to run.  Costs a stall by definition —
// use it in a test or a screenshot path, never in a frame loop.
pub fn gl_finish();
#native "loft_gl_finish"

// Set the viewport rectangle (used for FBO render passes).
pub fn gl_viewport(x: integer, y: integer, w: integer, h: integer);
#native "loft_gl_viewport"

// Set the scissor box — clips rendering to this rect (origin bottom-left, like
// the viewport). Takes effect only while gl_enable(GL_SCISSOR_TEST) is set; use
// it for partial-damage redraw (re-render just a changed region).
pub fn gl_scissor(x: integer, y: integer, w: integer, h: integer);
#native "loft_gl_scissor"

// --- Framebuffer objects ---

// Create a framebuffer object. Returns FBO handle.
pub fn gl_create_framebuffer() -> integer;
#native "loft_gl_create_framebuffer"

// Bind a framebuffer (0 = default screen framebuffer).
pub fn gl_bind_framebuffer(fbo: integer);
#native "loft_gl_bind_framebuffer"

// Attach a texture to an FBO (attachment: 0=color, 1=depth).
pub fn gl_framebuffer_texture(fbo: integer, attachment: integer, tex: integer);
#native "loft_gl_framebuffer_texture"

// Create a depth-only texture for shadow mapping.
pub fn gl_create_depth_texture(width: integer, height: integer) -> integer;
#native "loft_gl_create_depth_texture"

// Create an empty RGBA texture for render-to-texture.
pub fn gl_create_color_texture(width: integer, height: integer) -> integer;
#native "loft_gl_create_color_texture"

// Set a texture's filtering: nearest = crisp pixel-art, else linear/smooth.
pub fn gl_texture_filter(tex: integer, nearest: boolean);
#native "loft_gl_texture_filter"

// Generate mipmaps + trilinear minification for `tex` (after its pixels are
// uploaded) — keeps minified sprites / atlas pages clean.
pub fn gl_generate_mipmap(tex: integer);
#native "loft_gl_generate_mipmap"

// Upload a sub-region of RGBA pixels (Canvas data, 0xAARRGGBB) into an existing
// texture at (x,y) sized w*h — incremental atlas packing without re-uploading.
pub fn gl_texture_subimage(tex: integer, x: integer, y: integer, w: integer, h: integer, data: vector<integer>);
#native "loft_gl_texture_subimage"

// Draw a fullscreen quad (for post-processing). Uses built-in VAO with UV coords.
// Vertex shader receives: layout(location=0) vec2 aPos, layout(location=1) vec2 aUV.
pub fn gl_draw_fullscreen_quad();
#native "loft_gl_draw_fullscreen_quad"

// --- Draw modes ---

// Draw mode constants for gl_draw_mode and gl_draw_elements:
pub const DRAW_TRIANGLES = 0;
pub const DRAW_LINES = 1;
pub const DRAW_POINTS = 2;

// Draw a VAO with explicit mode (DRAW_TRIANGLES, DRAW_LINES, DRAW_POINTS).
pub fn gl_draw_mode(vao: integer, vertex_count: integer, mode: integer);
#native "loft_gl_draw_mode"

// Draw using an index buffer (EBO). mode: DRAW_TRIANGLES, DRAW_LINES, DRAW_POINTS.
pub fn gl_draw_elements(vao: integer, index_count: integer, mode: integer);
#native "loft_gl_draw_elements"

// Set line width for DRAW_LINES rendering.
pub fn gl_line_width(width: float);
#native "loft_gl_line_width"

// Set point size for DRAW_POINTS rendering.
pub fn gl_point_size(size: float);
#native "loft_gl_point_size"

// --- Input ---

// Key code constants for gl_key_pressed:
pub const KEY_W = 119;
pub const KEY_A = 97;
pub const KEY_S = 115;
pub const KEY_D = 100;
pub const KEY_Q = 113;
pub const KEY_E = 101;
pub const KEY_SPACE = 32;
pub const KEY_ESCAPE = 27;
pub const KEY_UP = 128;
pub const KEY_DOWN = 129;
pub const KEY_LEFT = 130;
pub const KEY_RIGHT = 131;
pub const KEY_SHIFT = 132;
pub const KEY_CTRL = 133;

// Initiative 03 Phase 1: extra keys for the editor hotkey set.
// Digits route through ASCII (`gl_key_pressed(KEY_1)` etc).
pub const KEY_0 = 48;
pub const KEY_1 = 49;
pub const KEY_2 = 50;
pub const KEY_3 = 51;
pub const KEY_4 = 52;
pub const KEY_5 = 53;
pub const KEY_6 = 54;
pub const KEY_7 = 55;
pub const KEY_8 = 56;
pub const KEY_9 = 57;

// Common editor hotkey letters (lowercase ASCII; `gl_key_pressed` is
// case-insensitive — the native key_index lowercases).
pub const KEY_O = 111;  // occlusion toggle
pub const KEY_R = 114;  // raise-layer
pub const KEY_F = 102;  // lower-layer
pub const KEY_Z = 122;  // undo (with Ctrl)
pub const KEY_Y = 121;  // redo (with Ctrl)

// Bracket keys for wall-direction cycling.
pub const KEY_LBRACKET = 91;   // [
pub const KEY_RBRACKET = 93;   // ]

// Tab for camera-mode toggle.
pub const KEY_TAB = 9;

// F-key range for save / load / fullscreen-toggle.  Values match
// `lib/graphics/native/src/lib.rs::key_index` mapping of
// `NamedKey::F1..F12` → 135..146.
pub const KEY_F1  = 135;
pub const KEY_F2  = 136;
pub const KEY_F3  = 137;
pub const KEY_F4  = 138;
pub const KEY_F5  = 139;
pub const KEY_F6  = 140;
pub const KEY_F7  = 141;
pub const KEY_F8  = 142;
pub const KEY_F9  = 143;
pub const KEY_F10 = 144;
pub const KEY_F11 = 145;
pub const KEY_F12 = 146;

// Returns true if the key is currently pressed (use KEY_* constants).
pub fn gl_key_pressed(key_code: integer) -> boolean;
#native "loft_gl_key_pressed"

// Mouse position X (pixels from left edge of window).
pub fn gl_mouse_x() -> float;
#native "loft_gl_mouse_x"

// Mouse position Y (pixels from top edge of window).
pub fn gl_mouse_y() -> float;
#native "loft_gl_mouse_y"

// Mouse button bitmask: 1=left, 2=right, 4=middle.
pub fn gl_mouse_button() -> integer;
#native "loft_gl_mouse_button"

// Scroll-wheel delta accumulated since the last call (positive = up).
// Reset on read.  Use per-frame to drive the editor's `InputState.in_wheel`
// or any other scroll-driven UI.  Pixel-delta trackpad scrolling is
// quantised at 20 px/line.
pub fn gl_mouse_wheel() -> integer;
#native "loft_gl_mouse_wheel"

// --- Input events (Gap 01): an ordered, drained-per-frame event queue ---
//
// The polling API above loses text, key-repeat, per-event modifiers, and event
// ORDER.  After gl_poll_events(), drain the queue: call gl_next_event()
// repeatedly (it returns an EV_* tag, or EV_NONE when empty) and read the
// current event's fields with the gl_event_* accessors below.  Delivers text /
// IME, key repeat, per-event modifiers, the named keys the polling API drops,
// and multitouch — in arrival order.  Example:
//   while gl_poll_events() {
//     t = gl_next_event();
//     while t != EV_NONE {
//       if t == EV_TEXT { type_text(gl_event_text()); }
//       else if t == EV_KEY_DOWN { key(gl_event_key(), gl_event_mods()); }
//       t = gl_next_event();
//     }
//     // ... render ...
//   }

// Event type tags returned by gl_next_event().
pub const EV_NONE = 0;
pub const EV_KEY_DOWN = 1;
pub const EV_KEY_UP = 2;
pub const EV_TEXT = 3;
pub const EV_MOUSE_DOWN = 4;
pub const EV_MOUSE_UP = 5;
pub const EV_MOUSE_MOVE = 6;
pub const EV_WHEEL = 7;
pub const EV_TOUCH_BEGIN = 8;
pub const EV_TOUCH_MOVE = 9;
pub const EV_TOUCH_END = 10;
pub const EV_RESIZE = 11;

// Modifier bitmask for gl_event_mods().
pub const MOD_SHIFT = 1;
pub const MOD_CTRL = 2;
pub const MOD_ALT = 4;
pub const MOD_SUPER = 8;

// Named keys the event queue reports (extend the KEY_* set above).
pub const KEY_ENTER = 13;
pub const KEY_BACKSPACE = 8;
pub const KEY_DELETE = 147;
pub const KEY_INSERT = 148;
pub const KEY_HOME = 149;
pub const KEY_END = 150;
pub const KEY_PAGEUP = 151;
pub const KEY_PAGEDOWN = 152;

// Pop the next queued input event and latch it; returns its EV_* tag, or
// EV_NONE when the queue is drained.  Call after gl_poll_events().
pub fn gl_next_event() -> integer;
#native "loft_gl_next_event"

// Named/keycode of the latched key event (the KEY_* constants).
pub fn gl_event_key() -> integer;
#native "loft_gl_event_key"

// Modifier bitmask of the latched event (MOD_SHIFT | MOD_CTRL | MOD_ALT | MOD_SUPER).
pub fn gl_event_mods() -> integer;
#native "loft_gl_event_mods"

// True if the latched key-down is an auto-repeat.
pub fn gl_event_repeat() -> boolean;
#native "loft_gl_event_repeat"

// UTF-8 text of the latched EV_TEXT event ("" otherwise).
pub fn gl_event_text() -> text;
#native "loft_gl_event_text"

// X position (pixels) of the latched mouse/touch event; width for EV_RESIZE.
pub fn gl_event_x() -> float;
#native "loft_gl_event_x"

// Y position (pixels) of the latched mouse/touch event; height for EV_RESIZE.
pub fn gl_event_y() -> float;
#native "loft_gl_event_y"

// Button of the latched mouse event (1=left, 2=right, 4=middle).
pub fn gl_event_button() -> integer;
#native "loft_gl_event_button"

// Wheel delta of the latched EV_WHEEL event (positive = up).
pub fn gl_event_wheel() -> integer;
#native "loft_gl_event_wheel"

// Stable finger id of the latched EV_TOUCH_* event.
pub fn gl_event_touch_id() -> integer;
#native "loft_gl_event_touch_id"

// --- Text rendering (GL3) ---

// Native font loader — reads `path` straight from the filesystem (relative to
// the process cwd).  Use the `gl_load_font` wrapper below, which resolves the
// path program-relative first.
fn gl_load_font_raw(path: text) -> integer;
#native "loft_gl_load_font"

// Load a font from a file path. Returns a font handle (>= 0) or null on error.
//
// #255: a RELATIVE path resolves against the program's OWN directory
// (`source_dir()` — the source dir under `--interpret`, the executable's dir
// under `--native`), so a bundled font travels with the program and loads
// regardless of the launch directory (the symptom #255 hit: a font addressed
// relative to the source missed under `--native`, which runs from a temp dir,
// and text rendered invisible).  An ABSOLUTE path is used verbatim.  This
// matches loft's program-relative file-I/O default (`file()` / `read_file`).
pub fn gl_load_font(path: text) -> integer {
  if path.starts_with("/") { return gl_load_font_raw(path); }
  dir = source_dir();
  if dir == "" { return gl_load_font_raw(path); }
  return gl_load_font_raw("{dir}/{path}");
}

// Measure text width in pixels at the given font size.
pub fn gl_measure_text(font: integer, content: text, size: float) -> float;
#native "loft_gl_measure_text"

// Return the line height in pixels for a font at the given size.
pub fn gl_text_height(font: integer, size: float) -> integer;
#native "loft_text_height"

// @P340: return the font ASCENT in pixels (baseline -> top of glyphs) from the
// font's real metrics.  gl_draw_text(x, y) anchors by the TOP, placing the
// baseline at y + gl_font_ascent(font, size); to baseline-align mixed sizes,
// draw each at y = baseline - gl_font_ascent(font, size_i).
pub fn gl_font_ascent(font: integer, size: float) -> float;
#native "loft_gl_font_ascent"

// Rasterize text into a pre-allocated integer buffer of alpha values (0-255).
fn rasterize_text_into(font: integer, content: text, size: float, buf: vector<integer>) -> integer;
#native "loft_rasterize_text_into"

// Rasterise text into the canvas at (x, y), anchored by the TOP-left.
//
// ⚠ NEEDS THE NATIVE RASTERISER, so this is one of the canvas routines that
// does NOT work headless: without it the call is a no-op and the canvas keeps
// whatever was under the text.  `text2d` exists for exactly that case — it
// carries a baked face and draws through `set_pixel`, so text always appears.
pub fn draw_text(self: Canvas, font: integer, content: text, size: float,
                 dt_x: integer, dt_y: integer, color: integer) {
  dt_tw = gl_measure_text(font, content, size) as integer + 1;
  dt_th = gl_text_height(font, size);
  if dt_tw <= 0 or dt_th <= 0 { return; }
  dt_buf = filled(dt_tw * dt_th, 0);
  dt_bw = rasterize_text_into(font, content, size, dt_buf);
  if dt_bw <= 0 { return; }
  dt_cr = color_r(color);
  dt_cg = color_g(color);
  dt_cb = color_b(color);
  for dt_by in 0..dt_th {
    for dt_bx in 0..dt_bw {
      dt_idx = dt_by * dt_bw + dt_bx;
      if dt_idx >= dt_buf.len() { break; }
      // `dt_idx` is computed (not a `for` index), so loft can't prove the read
      // fit — discharge at the source. The `>=` guard above keeps it in bounds,
      // so `?? 0` never actually fires.
      dt_a = dt_buf[dt_idx] ?? 0;
      if dt_a > 0 {
        self.blend_pixel(dt_x + dt_bx, dt_y + dt_by, rgba(dt_cr, dt_cg, dt_cb, dt_a));
      }
    }
  }
}

// --- Textures (GL5.5) ---

// Load an image file (PNG, JPG) and upload it as a GL texture.
// Returns the texture ID (0 on failure).
pub fn gl_load_texture(path: text) -> integer;
#native "loft_gl_load_texture"

// Upload Canvas pixel data as a GL texture. Returns the texture ID.
// Converts 0xAARRGGBB packed integers to RGBA bytes for OpenGL.
pub fn gl_upload_canvas(data: const vector<integer>, width: integer, height: integer) -> integer;
#native "loft_gl_upload_canvas"

// Bind a texture to a texture unit (0-based) for rendering.
pub fn gl_bind_texture(texture_id: integer, unit: integer);
#native "loft_gl_bind_texture"

// Delete a texture.
pub fn gl_delete_texture(texture_id: integer);
#native "loft_gl_delete_texture"

// --- GPU resource cleanup ---

// Delete a shader program.
pub fn gl_delete_shader(program: integer);
#native "loft_gl_delete_shader"

// Delete a vertex array object.
pub fn gl_delete_vao(vao: integer);
#native "loft_gl_delete_vao"

// Delete a framebuffer object.
pub fn gl_delete_framebuffer(fbo: integer);
#native "loft_gl_delete_framebuffer"

// ── G1/G2: Sprite Sheet API ─────────────────────────────────────────

// Vertex shader for textured 2D quads. Uses the unit quad positions (0-1)
// to interpolate UVs between uU0,uV0 and uU1,uV1.
SPRITE_VERT = `
#version 330 core
layout (location = 0) in vec3 aPos;
uniform mat4 uMVP;
uniform float uU0;
uniform float uV0;
uniform float uU1;
uniform float uV1;
out vec2 vUV;
void main() {{
    gl_Position = uMVP * vec4(aPos, 1.0);
    vUV = vec2(mix(uU0, uU1, aPos.x), mix(uV0, uV1, aPos.y));
}}
`;

// Fragment shader — samples the atlas texture.
SPRITE_FRAG = `
#version 330 core
in vec2 vUV;
uniform sampler2D uTex;
out vec4 FragColor;
void main() {{
    vec4 c = texture(uTex, vUV);
    if (c.a < 0.01) discard;
    FragColor = c;
}}
`;

/// A sprite sheet backed by a Canvas atlas uploaded as a GL texture.
/// Sprites are arranged in a grid of `ss_cols` x `ss_rows` cells.
pub struct SpriteSheet {
  pub const ss_tex: integer,  // GL texture handle
  const ss_shader: integer,   // textured quad shader
  const ss_vao: integer,      // unit quad VAO (shared)
  const ss_cols: integer,
  const ss_rows: integer,
  const ss_cell_w: integer,
  const ss_cell_h: integer,
}

/// Create a sprite sheet from a Canvas atlas.
/// The canvas is divided into a grid of `cols` x `rows` cells.
/// Sprite index 0 is top-left, incrementing left-to-right then top-to-bottom.
pub fn create_sprite_sheet(atlas: const Canvas, cols: integer, rows: integer, vao: integer) -> SpriteSheet {
  ss_shader = gl_create_shader(SPRITE_VERT, SPRITE_FRAG);
  ss_tex = gl_upload_canvas(atlas.data, atlas.width, atlas.height);
  SpriteSheet {
    ss_tex: ss_tex,
    ss_shader: ss_shader,
    ss_vao: vao,
    ss_cols: cols,
    ss_rows: rows,
    ss_cell_w: atlas.width / cols ?? 0,
    ss_cell_h: atlas.height / rows ?? 0,
  }
}

/// Draw sprite at `index` (0-based, row-major).
/// `mvp` is the pre-multiplied projection * model matrix (16 singles).
/// The caller builds the MVP for the desired screen position and size.
pub fn draw_sprite(sheet: const SpriteSheet, mvp: const vector<float>, sp_idx: integer) {
  // `?? 0` on each div is lint suppression — `ss_cols` / `ss_rows`
  // are construction-time positive (zero would mean an empty atlas
  // with no sprites to draw).
  sp_col = (sp_idx % sheet.ss_cols) ?? 0;
  sp_row = (sp_idx / sheet.ss_cols) ?? 0;
  sp_u0 = ((sp_col as float) / (sheet.ss_cols as float)) ?? 0.0;
  sp_v0 = ((sp_row as float) / (sheet.ss_rows as float)) ?? 0.0;
  sp_u1 = (((sp_col + 1) as float) / (sheet.ss_cols as float)) ?? 0.0;
  sp_v1 = (((sp_row + 1) as float) / (sheet.ss_rows as float)) ?? 0.0;
  gl_use_shader(sheet.ss_shader);
  gl_bind_texture(sheet.ss_tex, 0);
  gl_set_uniform_int(sheet.ss_shader, "uTex", 0);
  gl_set_uniform_float(sheet.ss_shader, "uU0", sp_u0);
  gl_set_uniform_float(sheet.ss_shader, "uV0", sp_v0);
  gl_set_uniform_float(sheet.ss_shader, "uU1", sp_u1);
  gl_set_uniform_float(sheet.ss_shader, "uV1", sp_v1);
  gl_set_uniform_mat4(sheet.ss_shader, "uMVP", mvp);
  gl_draw(sheet.ss_vao, 6);
}

// ── G3: Painter2D — ergonomic 2D draw helpers ───────────────────────
//
// Painter2D bundles a flat-color shader, a textured-quad shader, a shared
// unit-quad VAO, and an orthographic projection sized for the window. It
// lets 2D games draw rectangles, sprites, and textures with (x, y, w, h)
// screen coordinates without hand-building MVP matrices.
//
// Screen-space origin: top-left. Y increases downward (pixel-style).
// All draw helpers assume the unit quad is at Z=0.

// Flat-color vertex shader — transforms the unit quad by uMVP.
FLAT_VERT_2D = `
#version 330 core
layout (location = 0) in vec3 aPos;
uniform mat4 uMVP;
void main() {{ gl_Position = uMVP * vec4(aPos, 1.0); }}
`;

// Flat-color fragment shader — uColor (vec3) + uAlpha (float).
FLAT_FRAG_2D = `
#version 330 core
uniform vec3 uColor;
uniform float uAlpha;
out vec4 FragColor;
void main() {{ FragColor = vec4(uColor, uAlpha); }}
`;

// Textured quad vertex shader — samples the full texture with identity UV.
// `glTexImage2D` stores canvas-top at TC.y=0 and the 2D ortho projection
// maps top-left screen coords onto clip-space, so no per-shader V flip is
// needed.  PNG-loaded textures sample the same way.
TEX_VERT_2D = `
#version 330 core
layout (location = 0) in vec3 aPos;
uniform mat4 uMVP;
out vec2 vUV;
void main() {{
    gl_Position = uMVP * vec4(aPos, 1.0);
    vUV = vec2(aPos.x, aPos.y);
}}
`;

// Textured quad fragment shader — alpha-discards fully transparent pixels.
TEX_FRAG_2D = `
#version 330 core
in vec2 vUV;
uniform sampler2D uTex;
out vec4 FragColor;
void main() {{
    vec4 c = texture(uTex, vUV);
    if (c.a < 0.01) discard;
    FragColor = c;
}}
`;

/// A 2D painter bundling shaders, a unit-quad VAO, and an orthographic
/// projection. Create once per window with `create_painter_2d`, then use
/// `draw_rect_at`, `draw_sprite_at`, and `draw_texture_at` to render.
pub struct Painter2D {
  p2_flat: integer,        // flat color shader
  pub p2_tex: integer,     // textured quad shader (V-flipped)
  pub p2_vao: integer,     // shared unit-quad VAO
  pub p2_proj: vector<float>,           // orthographic projection (16 floats)
}

/// Create a Painter2D for a window of size `screen_w` x `screen_h`.
/// Compiles the flat and textured shaders, uploads the unit-quad VAO, and
/// builds an orthographic projection with the origin at the top-left.
/// Call once after `gl_create_window`.
pub fn create_painter_2d(screen_w: float, screen_h: float) -> Painter2D {
  cpn_flat = gl_create_shader(FLAT_VERT_2D, FLAT_FRAG_2D);
  cpn_tex = gl_create_shader(TEX_VERT_2D, TEX_FRAG_2D);
  // Unit quad — two triangles from (0,0) to (1,1), z=0, in f32.
  cpn_quad = [
    0.0f, 0.0f, 0.0f,  1.0f, 0.0f, 0.0f,  1.0f, 1.0f, 0.0f,
    0.0f, 0.0f, 0.0f,  1.0f, 1.0f, 0.0f,  0.0f, 1.0f, 0.0f
  ];
  cpn_vao = gl_upload_vertices(cpn_quad, 3);
  // `?? 0.0` is lint suppression — both screen_w and screen_h are
  // construction-time positive (caller passes window dimensions).
  cpn_proj = [
    2.0 / screen_w ?? 0.0, 0.0, 0.0, 0.0,
    0.0, -2.0 / screen_h ?? 0.0, 0.0, 0.0,
    0.0, 0.0, -1.0, 0.0,
    -1.0, 1.0, 0.0, 1.0
  ];
  Painter2D {
    p2_flat: cpn_flat,
    p2_tex: cpn_tex,
    p2_vao: cpn_vao,
    p2_proj: cpn_proj,
  }
}

/// Return the unit-quad VAO owned by the painter, so it can be shared with
/// `create_sprite_sheet` instead of uploading a second copy.
pub fn painter_vao(self: const Painter2D) -> integer { self.p2_vao }

// Build an MVP = proj * translate(x, y, 0) * scale(w, h, 1) without going
// through the generic math::mat4_mul path. The model matrix is sparse, so
// this collapses to 4 column updates on the 16-float projection.
fn build_mvp_2d(proj: const vector<float>, x: float, y: float, w: float, h: float) -> vector<float> {
  bmn_mvp = [
    // column 0 = proj.col0 * w
    proj[0] * w,  proj[1] * w,  proj[2] * w,  proj[3] * w,
    // column 1 = proj.col1 * h
    proj[4] * h,  proj[5] * h,  proj[6] * h,  proj[7] * h,
    // column 2 = proj.col2 (z untouched)
    proj[8],      proj[9],      proj[10],     proj[11],
    // column 3 = proj.col0 * x + proj.col1 * y + proj.col3
    proj[0] * x + proj[4] * y + proj[12],
    proj[1] * x + proj[5] * y + proj[13],
    proj[2] * x + proj[6] * y + proj[14],
    proj[3] * x + proj[7] * y + proj[15]
  ];
  bmn_mvp
}

/// Draw a filled rectangle at screen position (x, y) with size (w, h).
/// Colour channels are in 0.0..1.0. Uses the painter's flat-color shader.
pub fn draw_rect_at(painter: const Painter2D, x: float, y: float, w: float, h: float,
                    r: float, g: float, b: float, a: float) {
  drn_mvp = build_mvp_2d(painter.p2_proj, x, y, w, h);
  gl_use_shader(painter.p2_flat);
  gl_set_uniform_mat4(painter.p2_flat, "uMVP", drn_mvp);
  gl_set_uniform_vec3(painter.p2_flat, "uColor", r, g, b);
  gl_set_uniform_float(painter.p2_flat, "uAlpha", a);
  gl_draw(painter.p2_vao, 6);
}

/// Draw a sprite from `sheet` at screen position (x, y) with size (w, h).
/// `sp_idx` is the 0-based sprite index (row-major) in the sheet.
/// This is a one-liner replacement for `make_mvp` + `draw_sprite`.
pub fn draw_sprite_at(sheet: const SpriteSheet, painter: const Painter2D,
                      x: float, y: float, w: float, h: float, sp_idx: integer) {
  dsn_mvp = build_mvp_2d(painter.p2_proj, x, y, w, h);
  draw_sprite(sheet, dsn_mvp, sp_idx);
}

/// Draw an arbitrary GL texture as a screen-space quad at (x, y, w, h).
/// Uses the painter's textured shader, which flips V to match canvas origin.
/// Suitable for textures created with `create_text_texture` or `gl_upload_canvas`.
pub fn draw_texture_at(painter: const Painter2D, tex: integer,
                       x: float, y: float, w: float, h: float) {
  dxn_mvp = build_mvp_2d(painter.p2_proj, x, y, w, h);
  gl_use_shader(painter.p2_tex);
  gl_bind_texture(tex, 0);
  gl_set_uniform_int(painter.p2_tex, "uTex", 0);
  gl_set_uniform_mat4(painter.p2_tex, "uMVP", dxn_mvp);
  gl_draw(painter.p2_vao, 6);
}

/// Rasterize `content` with `font` at `size` pixels, upload the glyph bitmap
/// as a GL texture, and return the texture ID. The texture is sized to fit
/// the measured text plus a small padding; pair with `draw_texture_at` to
/// render. Caller owns the texture — call `gl_delete_texture` when done.
/// Returns 0 if the text cannot be measured.
pub fn create_text_texture(font: integer, content: text, size: float, color: integer) -> integer {
  ctn_pad = 2;
  ctn_tw = gl_measure_text(font, content, size) as integer + ctn_pad * 2 + 1;
  ctn_th = gl_text_height(font, size) + ctn_pad * 2;
  if ctn_tw <= 0 or ctn_th <= 0 { return 0; }
  ctn_cv = canvas(ctn_tw, ctn_th, 0);
  ctn_cv.draw_text(font, content, size, ctn_pad, ctn_pad, color);
  gl_upload_canvas(ctn_cv.data, ctn_tw, ctn_th)
}

// --- G5: Audio ---
// Load an audio clip (WAV or OGG). Returns handle (>= 0) or null on failure.
pub fn audio_load(path: text) -> integer;
#native "loft_audio_load"
// Play a loaded clip.  Returns a playback handle, or -1 when it will not play.
//
// `volume` is 0.0-1.0, `looping` repeats the clip until it is stopped, `pan`
// places it across the stereo field (-1 left, 0 centre, 1 right), and `start`
// begins that many seconds in.  Everything past `volume` has a default, so an
// existing `audio_play(clip, 0.8)` keeps meaning what it meant.
//
// `start` skips into the FIRST pass only: a looping clip then repeats whole,
// which is what a browser's `start(when, offset)` with `loop` does.
//
// A handle is never handed out twice.  When a clip finishes its slot is reused,
// but the handle carries which use it belongs to, so an `audio_stop` on a
// finished sound stops nothing instead of stopping whatever took its place.
pub fn audio_play(clip: integer, volume: float, looping: boolean = false,
                  pan: float = 0.0, start: float = 0.0) -> integer;
#native "loft_audio_play"
// Stop a playing clip by its playback handle.
pub fn audio_stop(sink: integer);
#native "loft_audio_stop"
// Stop every playing clip — a pause menu, a scene change, a game over.
pub fn audio_stop_all();
#native "loft_audio_stop_all"
// Set volume of a playing clip (0.0-1.0).
pub fn audio_set_volume(sink: integer, volume: float);
#native "loft_audio_set_volume"
// Move a playing clip across the stereo field: -1 left, 0 centre, 1 right.
//
// The law is Web Audio's `StereoPannerNode`, equal-power for a mono clip: a
// sweep holds its loudness through the middle rather than dipping.  A stereo
// clip is narrowed toward the near side rather than having the far one muted.
pub fn audio_set_pan(sink: integer, pan: float);
#native "loft_audio_set_pan"
// Jump a playing clip to `seconds` from its start.  Answers whether it moved.
//
// A LOOPING clip cannot seek — repeating needs a buffered source, which has no
// earlier position to go back to — and this answers false rather than leaving
// the caller believing a jump happened.
pub fn audio_seek(sink: integer, seconds: float) -> boolean;
#native "loft_audio_seek"
// Play raw PCM samples (mono, values -1.0 to 1.0) at the given sample rate.
// Returns playback handle, or null on failure.
pub fn audio_play_raw(samples: vector<single>, sample_rate: integer, volume: float) -> integer;
#native "loft_audio_play_raw"

// --- Procedural audio synthesis (chiptune) ---

SFX_RATE = 22050;

// Square wave sample: phase 0.0-1.0, duty 0.0-1.0.
fn sfx_sq(sfx_sq_phase: single, sfx_sq_duty: single) -> single {
  if sfx_sq_phase < sfx_sq_duty { return 1.0f; }
  return -1.0f;
}
// Triangle wave sample: phase 0.0-1.0.
fn sfx_tri(sfx_tri_p: single) -> single {
  if sfx_tri_p < 0.5f { return sfx_tri_p * 4.0f - 1.0f; }
  return 3.0f - sfx_tri_p * 4.0f;
}
// Sawtooth wave sample: phase 0.0-1.0.
fn sfx_saw(sfx_saw_p: single) -> single {
  return sfx_saw_p * 2.0f - 1.0f;
}
// Linear attack-decay envelope: returns 0.0-1.0.
fn sfx_env(sfx_env_t: single, sfx_env_atk: single, sfx_env_dur: single) -> single {
  // `?? 0.0f` is lint suppression — the attack branch only fires when
  // `sfx_env_t < sfx_env_atk`, which transitively implies atk > 0
  // unless sfx_env_t is negative (caller invariant).
  if sfx_env_t < sfx_env_atk { return (sfx_env_t / sfx_env_atk) ?? 0.0f; }
  sfx_env_rem = sfx_env_dur - sfx_env_t;
  if sfx_env_rem < 0.0f { return 0.0f; }
  sfx_env_dec = sfx_env_dur - sfx_env_atk;
  if sfx_env_dec <= 0.0f { return 0.0f; }
  // `?? 0.0f` is lint suppression — `sfx_env_dec > 0.0f` is enforced
  // by the early-return guard above.
  return (sfx_env_rem / sfx_env_dec) ?? 0.0f;
}

// Short percussive beep — brick hit, UI click.
pub fn sfx_beep(sb_freq: single, sb_dur: single, sb_vol: single) -> integer {
  sb_n = (sb_dur * SFX_RATE as single) as integer;
  sb_buf: vector<single> = [for sb_i in 0..sb_n {
    sb_t = sb_i as single / SFX_RATE as single;
    sb_p = (sb_t * sb_freq) % 1.0f;
    sfx_sq(sb_p, 0.5f) * sfx_env(sb_t, 0.005f, sb_dur) * sb_vol
  }];
  return audio_play_raw(sb_buf, SFX_RATE, 1.0);
}

// Descending tone — life lost, negative event.
pub fn sfx_descend(sd_f0: single, sd_f1: single, sd_dur: single, sd_vol: single) -> integer {
  sd_n = (sd_dur * SFX_RATE as single) as integer;
  sd_ph = 0.0f;
  sd_buf: vector<single> = [for sd_i in 0..sd_n {
    sd_t = sd_i as single / SFX_RATE as single;
    sd_f = sd_f0 + (sd_f1 - sd_f0) * ((sd_t / sd_dur) ?? 0.0f);
    sd_ph = (sd_ph + sd_f / SFX_RATE as single) % 1.0f;
    sfx_saw(sd_ph) * sfx_env(sd_t, 0.01f, sd_dur) * sd_vol
  }];
  return audio_play_raw(sd_buf, SFX_RATE, 1.0);
}

// Rising chirp — pickup collected, positive event.
pub fn sfx_chirp(sc_f0: single, sc_f1: single, sc_dur: single, sc_vol: single) -> integer {
  sc_n = (sc_dur * SFX_RATE as single) as integer;
  sc_ph = 0.0f;
  sc_buf: vector<single> = [for sc_i in 0..sc_n {
    sc_t = sc_i as single / SFX_RATE as single;
    sc_f = sc_f0 + (sc_f1 - sc_f0) * ((sc_t / sc_dur) ?? 0.0f);
    sc_ph = (sc_ph + sc_f / SFX_RATE as single) % 1.0f;
    sfx_tri(sc_ph) * sfx_env(sc_t, 0.005f, sc_dur) * sc_vol
  }];
  return audio_play_raw(sc_buf, SFX_RATE, 1.0);
}

// White noise burst — percussion, explosion, brick break.
pub fn sfx_noise(sn_dur: single, sn_vol: single) -> integer {
  sn_n = (sn_dur * SFX_RATE as single) as integer;
  sn_seed = 12345;
  sn_buf: vector<single> = [for sn_i in 0..sn_n {
    sn_t = sn_i as single / SFX_RATE as single;
    sn_seed = (sn_seed * 1103515245 + 12345) % 2147483647;
    sn_rnd = (sn_seed as single / 1073741824.0f) - 1.0f;
    sn_rnd * sfx_env(sn_t, 0.002f, sn_dur) * sn_vol
  }];
  return audio_play_raw(sn_buf, SFX_RATE, 1.0);
}

// Paddle bounce — low square wave thud with pitch drop.
pub fn sfx_bounce(sp_freq: single, sp_vol: single) -> integer {
  return sfx_beep(sp_freq, 0.08f, sp_vol);
}

src/render.loft

// Copyright (c) 2026 Jurjen Stellingwerff
// SPDX-License-Identifier: LGPL-3.0-or-later
// High-level renderer — scene-driven PBR with shadows.
// One call to render_frame() handles shadow pass, color pass, and buffer swap.
// Design: doc/claude/RENDERER.md
use graphics::*;
use mesh3d::*;

// ── Built-in shaders ─────────────────────────────────────────────────────

SHADOW_VERT = `
#version 330 core
layout (location = 0) in vec3 aPos;
uniform mat4 uModel;
uniform mat4 uLightVP;
void main() {{ gl_Position = uLightVP * uModel * vec4(aPos, 1.0); }}
`;

SHADOW_FRAG = `
#version 330 core
void main() {{}}
`;

PBR_VERT = `
#version 330 core
layout (location = 0) in vec3 aPos;
layout (location = 1) in vec3 aNormal;
uniform mat4 uModel;
uniform mat4 uView;
uniform mat4 uProj;
uniform mat4 uLightVP;
out vec3 vWorldPos;
out vec3 vNormal;
out vec4 vLightSpacePos;
void main() {{
    vec4 worldPos = uModel * vec4(aPos, 1.0);
    vWorldPos = vec3(worldPos);
    vNormal = mat3(transpose(inverse(uModel))) * aNormal;
    vLightSpacePos = uLightVP * worldPos;
    gl_Position = uProj * uView * worldPos;
}}
`;

PBR_FRAG = `
#version 330 core
in vec3 vWorldPos;
in vec3 vNormal;
in vec4 vLightSpacePos;
out vec4 FragColor;
uniform vec3 uCamPos;
uniform vec3 uLightDir;        // world-space direction the light travels
uniform vec3 uLightColor;      // directional light colour × intensity
uniform vec3 uPointLightPos;   // world-space point-light position
uniform vec3 uPointLightColor; // point-light colour × intensity (0,0,0 = off)
uniform int uHasPointLight;
uniform vec3 uColor;
uniform float uMetallic;
uniform float uRoughness;
uniform sampler2D uShadowMap;
uniform int uHasShadow;
float shadow_calc(vec4 lsp) {{
    vec3 proj = lsp.xyz / lsp.w;
    proj = proj * 0.5 + 0.5;
    if (proj.z > 1.0) return 0.0;
    float closest = texture(uShadowMap, proj.xy).r;
    float current = proj.z;
    float bias = max(0.005 * (1.0 - dot(normalize(vNormal), normalize(-uLightDir))), 0.001);
    return current - bias > closest ? 0.6 : 0.0;
}}
void main() {{
    vec3 N = normalize(vNormal);
    vec3 V = normalize(uCamPos - vWorldPos);
    float rough_pow = mix(8.0, 128.0, 1.0 - uRoughness);
    float fresnel = pow(1.0 - max(dot(N, V), 0.0), 5.0);
    vec3 F0 = mix(vec3(0.04), uColor, uMetallic);
    float shadow = 0.0;
    if (uHasShadow == 1) shadow = shadow_calc(vLightSpacePos);

    // Directional light — scaled by its colour × intensity (uLightColor).
    vec3 L = normalize(-uLightDir);
    vec3 H = normalize(V + L);
    float diff = max(dot(N, L), 0.0);
    float spec = pow(max(dot(N, H), 0.0), rough_pow);
    float shade = 1.0 - shadow;
    vec3 diffuse  = uColor * uLightColor * diff * (1.0 - uMetallic * 0.7) * shade;
    vec3 specular = F0 * uLightColor * spec * (1.0 + fresnel) * shade;

    // Point light — quadratic attenuation, no shadow.  Skipped when the
    // scene has no point light (uHasPointLight == 0).
    if (uHasPointLight == 1) {{
        vec3 Pd = uPointLightPos - vWorldPos;
        float dist = length(Pd);
        vec3 PL = Pd / max(dist, 0.0001);
        vec3 PH = normalize(V + PL);
        float atten = 1.0 / (1.0 + 0.1 * dist + 0.01 * dist * dist);
        float pdiff = max(dot(N, PL), 0.0);
        float pspec = pow(max(dot(N, PH), 0.0), rough_pow);
        diffuse  += uColor * uPointLightColor * pdiff * (1.0 - uMetallic * 0.7) * atten;
        specular += F0 * uPointLightColor * pspec * (1.0 + fresnel) * atten;
    }}

    vec3 ambient = uColor * mix(0.15, 0.08, uMetallic);
    vec3 result = ambient + diffuse + specular;
    // Tone mapping + gamma
    result = result / (result + vec3(1.0));
    result = pow(result, vec3(1.0 / 2.2));
    FragColor = vec4(result, 1.0);
}}
`;

// ── Renderer struct ──────────────────────────────────────────────────────

// A window with the 3D renderer's GL state: its size, the PBR and shadow shaders, the
// shadow-map framebuffer and texture, and the vertex arrays `upload_scene` filled.
// `create_renderer` makes one.
pub struct Renderer {
  const width: integer,
  const height: integer,
  const pbr_shader: integer,
  const shadow_shader: integer,
  const shadow_fbo: integer,
  const shadow_tex: integer,
  const shadow_size: integer,
  const start_tick: integer,
  const vaos: vector<integer>,          // const: contents grown via `+=` in upload_scene
  const vert_counts: vector<integer>,   // const: contents grown via `+=` in upload_scene
  uploaded: boolean               // not const: genuinely reassigned (`self.uploaded = true`)
}

// Create a renderer with a window.  Compiles built-in shaders, allocates
// shadow map FBO.  Returns null on failure (no display).
pub fn create_renderer(rw: integer, rh: integer, title: text) -> Renderer {
  if !graphics::gl_create_window(rw, rh, title) {
    return Renderer {};
  }
  rr_pbr = graphics::gl_create_shader(PBR_VERT, PBR_FRAG);
  rr_shadow = graphics::gl_create_shader(SHADOW_VERT, SHADOW_FRAG);
  rr_sz = 1024;
  rr_dtex = graphics::gl_create_depth_texture(rr_sz, rr_sz);
  rr_fbo = graphics::gl_create_framebuffer();
  graphics::gl_framebuffer_texture(rr_fbo, 1, rr_dtex);
  Renderer {
    // ⚠ THE SURFACE'S SIZE, NOT THE ONE WE ASKED FOR.  `gl_window_width` is
    // documented as the inner size in PHYSICAL pixels precisely so a projection
    // or a restored viewport uses the real resolution rather than a windowed
    // hint — and on a high-density display, or fullscreen, the two differ.
    // Reusing `rw`/`rh` as the colour pass's viewport (below) then renders the
    // scene into a fraction of the surface.
    width: graphics::gl_window_width(), height: graphics::gl_window_height(),
    pbr_shader: rr_pbr, shadow_shader: rr_shadow,
    shadow_fbo: rr_fbo, shadow_tex: rr_dtex, shadow_size: rr_sz,
    start_tick: ticks(),
    uploaded: false
  }
}

// Seconds since the renderer was created.
pub fn elapsed(self: const Renderer) -> float {
  (ticks() - self.start_tick) as float / 1000000.0
}

// Upload all meshes in the scene to GPU VAOs.
pub fn upload_scene(self: Renderer, sc: const scene::Scene) {
  for up_m in sc.meshes {
    up_data = mesh::mesh_to_floats(up_m);
    up_nv = up_data.len() / 6;
    up_vao = graphics::gl_upload_vertices(up_data, 6);
    self.vaos += [up_vao];
    self.vert_counts += [up_nv];
  }
  self.uploaded = true;
}

// Render one frame's 3D passes WITHOUT swapping buffers.  Callers
// that want to draw a 2D overlay between the 3D pass and the swap
// (e.g. the native Moros editor's panel) use this variant and
// invoke `graphics::gl_swap_buffers()` themselves after their
// overlay renders.  Returns false when close requested.
//
// Introduced by Initiative 03 Phase 3b (native moros editor
// panel overlay).  The existing `render_frame` wrapper below
// preserves backward compatibility with every current caller.
pub fn render_frame_no_swap(self: Renderer, sc: const scene::Scene,
                            cam: const scene::Camera) -> boolean {
  if !graphics::gl_poll_events() { return false; }
  if !self.uploaded { self.upload_scene(sc); }
  // Camera matrices
  rf_view = math::mat4_look_at(cam.position, cam.target, math::vec3(0.0, 1.0, 0.0));
  // `?? 1.0` is lint suppression — render targets always have a
  // positive height (zero would be a degenerate viewport).
  rf_proj = math::mat4_perspective(cam.fov * 0.01745, (self.width as float / self.height as float) ?? 1.0,
                                   cam.near, cam.far);
  rf_eye = cam.position;
  // Lighting — picks the first directional light (shadow caster) and
  // the first point light from the scene.  `intensity` is pre-folded
  // into the colour so the shader only reads one vec3 per light.
  // Defaults (no directional in scene): neutral white from upper-front.
  rf_has_shadow = 0;
  rf_light_dir = math::vec3(-1.0, -2.0, -1.0);
  rf_light_color = math::vec3(1.0, 1.0, 1.0);
  rf_light_vp = math::mat4_identity();
  for rl in sc.lights {
    if rl.light_type == scene::Directional {
      rf_light_dir = rl.direction;
      rf_light_color = math::vec3(
        rl.color_r * rl.intensity,
        rl.color_g * rl.intensity,
        rl.color_b * rl.intensity);
      // Orthographic light VP for shadow mapping.
      rf_light_eye = math::vec3(-rf_light_dir.x * 10.0, -rf_light_dir.y * 10.0, -rf_light_dir.z * 10.0);
      rf_light_view = math::mat4_look_at(rf_light_eye, math::vec3(0.0, 0.0, 0.0), math::vec3(0.0, 1.0, 0.0));
      rf_light_proj = math::mat4_ortho(-12.0, 12.0, -12.0, 12.0, 0.1, 30.0);
      rf_light_vp = math::mat4_mul(rf_light_proj, rf_light_view);
      rf_has_shadow = 1;
      break;
    }
  }
  rf_has_point = 0;
  rf_point_pos = math::vec3(0.0, 0.0, 0.0);
  rf_point_color = math::vec3(0.0, 0.0, 0.0);
  for rpl in sc.lights {
    if rpl.light_type == scene::Point {
      rf_point_pos = rpl.position;
      rf_point_color = math::vec3(
        rpl.color_r * rpl.intensity,
        rpl.color_g * rpl.intensity,
        rpl.color_b * rpl.intensity);
      rf_has_point = 1;
      break;
    }
  }
  // Shadow pass
  if rf_has_shadow == 1 {
    graphics::gl_viewport(0, 0, self.shadow_size, self.shadow_size);
    graphics::gl_bind_framebuffer(self.shadow_fbo);
    graphics::gl_clear(graphics::rgba(0, 0, 0, 255));
    graphics::gl_use_shader(self.shadow_shader);
    graphics::gl_set_uniform_mat4(self.shadow_shader, "uLightVP", rf_light_vp.m);
    rf_vaos = self.vaos;
    rf_vcs = self.vert_counts;
    for rn in sc.nodes {
      graphics::gl_set_uniform_mat4(self.shadow_shader, "uModel", rn.transform.m);
      rn_mi = rn.mesh_idx;
      if rn_mi >= 0 and rn_mi < len(rf_vaos) and rn_mi < len(rf_vcs) {
        graphics::gl_draw(rf_vaos[rn_mi], rf_vcs[rn_mi]);
      }
    }
    graphics::gl_bind_framebuffer(0);
    graphics::gl_viewport(0, 0, self.width, self.height);
  }
  // Color pass
  graphics::gl_clear(graphics::rgba(20, 20, 25, 255));
  graphics::gl_use_shader(self.pbr_shader);
  graphics::gl_set_uniform_mat4(self.pbr_shader, "uView", rf_view.m);
  graphics::gl_set_uniform_mat4(self.pbr_shader, "uProj", rf_proj.m);
  graphics::gl_set_uniform_mat4(self.pbr_shader, "uLightVP", rf_light_vp.m);
  graphics::gl_set_uniform_vec3(self.pbr_shader, "uCamPos", rf_eye.x, rf_eye.y, rf_eye.z);
  graphics::gl_set_uniform_vec3(self.pbr_shader, "uLightDir", rf_light_dir.x, rf_light_dir.y, rf_light_dir.z);
  graphics::gl_set_uniform_vec3(self.pbr_shader, "uLightColor", rf_light_color.x, rf_light_color.y, rf_light_color.z);
  graphics::gl_set_uniform_vec3(self.pbr_shader, "uPointLightPos",
    rf_point_pos.x, rf_point_pos.y, rf_point_pos.z);
  graphics::gl_set_uniform_vec3(self.pbr_shader, "uPointLightColor",
    rf_point_color.x, rf_point_color.y, rf_point_color.z);
  graphics::gl_set_uniform_int(self.pbr_shader, "uHasPointLight", rf_has_point);
  graphics::gl_set_uniform_int(self.pbr_shader, "uHasShadow", rf_has_shadow);
  if rf_has_shadow == 1 {
    graphics::gl_bind_texture(self.shadow_tex, 1);
    graphics::gl_set_uniform_int(self.pbr_shader, "uShadowMap", 1);
  }
  rp_vaos = self.vaos;
  rp_vcs = self.vert_counts;
  rp_mats = sc.materials;
  for rn in sc.nodes {
    rn_mi2 = rn.mesh_idx;
    rn_mati = rn.material_idx;
    if rn_mi2 >= 0 and rn_mi2 < len(rp_vaos) and rn_mi2 < len(rp_vcs) and rn_mati < len(rp_mats) {
      rm = rp_mats[rn_mati];
      graphics::gl_set_uniform_mat4(self.pbr_shader, "uModel", rn.transform.m);
      graphics::gl_set_uniform_vec3(self.pbr_shader, "uColor", rm.base_color_r, rm.base_color_g, rm.base_color_b);
      graphics::gl_set_uniform_float(self.pbr_shader, "uMetallic", rm.metallic);
      graphics::gl_set_uniform_float(self.pbr_shader, "uRoughness", rm.roughness);
      graphics::gl_draw(rp_vaos[rn_mi2], rp_vcs[rn_mi2]);
    }
  }
  true
}

// Render one frame (3D passes + buffer swap).  Convenience wrapper
// for callers that don't need a 2D overlay between the 3D pass and
// the swap — brick-buster, 24-renderer-demo, and every other current
// consumer.  Returns false when close requested.
pub fn render_frame(self: Renderer, sc: const scene::Scene,
                    cam: const scene::Camera) -> boolean {
  if !self.render_frame_no_swap(sc, cam) { return false; }
  graphics::gl_swap_buffers();
  true
}

// Convenience: render loop until close.
pub fn render_loop(self: Renderer, sc: const scene::Scene, cam: const scene::Camera) {
  for _ in 0..1000000 {
    if !self.render_frame(sc, cam) { break; }
  }
}

// Destroy GPU resources and close the window.
pub fn destroy(self: Renderer) {
  for rv in self.vaos {
    graphics::gl_delete_vao(rv);
  }
  graphics::gl_delete_shader(self.pbr_shader);
  graphics::gl_delete_shader(self.shadow_shader);
  graphics::gl_delete_texture(self.shadow_tex);
  graphics::gl_delete_framebuffer(self.shadow_fbo);
  graphics::gl_destroy_window();
}