feat(3d): gl1 shim M4+M6+M7 — GLU quadrics, production link, stub retired; 47/47 parity

- gl1_glu: gluCylinder/gluDisk/gluSphere per the SGI GLU reference
  tessellation (sin/cos phase, strip emission order, pole fans — Apple's
  GLU derives from the same source, so vertices match the goldens);
  emission goes through the public glBegin/glVertex entry points so
  quadrics record into display lists
- glLineWidth>1 one-time warning (browsers clamp to 1; affected coverage
  stays under the parity floor — zero floors.json overrides needed)
- production link site: build-kicad-target.sh now compiles wasm/gl1 from
  sources.txt and applies wrapped_symbols.txt --wrap flags (same manifests
  as the test harness); kicad_editor's RENDER_3D_OPENGL links against the
  real emulation layer instead of no-ops
- wasm/stubs/gl_ffp_stub.c deleted (role fully superseded; history in git)
- docs: 3d-regression README port-status section (floor-blind small
  geometry + line-width caveats), harness comments de-red-stated

Parity: 47/47 under the 0.02 floor, zero overrides. Native golden path
byte-identical to bb0e238 (whose gate ran green) — scenarios/, native/,
baseline/, manifest, floors, spec all untouched by the port.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Istvan Matejcsok 2026-07-03 11:56:19 +02:00
commit 27992f4f18
8 changed files with 240 additions and 157 deletions

View file

@ -13,9 +13,10 @@ compiled two ways:
the vendored glad loader). Renders each scenario into a fixed 800×600
offscreen FBO (`GL_RGBA8` + `GL_DEPTH24_STENCIL8`, the
`EDA_3D_CANVAS::RenderToFrameBuffer` recipe) → **golden baselines**.
- **wasm/** — the same scenario TUs compiled with em++ (planned; red state
first: linked against `wasm/stubs/gl_ffp_stub.c` no-ops, every render blank
until the port makes them green).
- **wasm/** — the same scenario TUs compiled with em++, linked against the
**`wasm/gl1`** GL1→WebGL2 emulation layer (the port itself — see
`wasm/gl1/README.md`). Since the port landed, all 47 scenarios render under
the parity floor with zero per-scenario overrides.
## Directory layout
@ -74,13 +75,22 @@ every run, so a scenario registry change can't silently drift past the
baselines. Scenario names are append-only — never rename or renumber (they are
the PNG names and the WebGL test IDs).
## TDD red state
## Port status (was: TDD red state)
Once `wasm/` exists, the Playwright spec (`tests/e2e/3d-webgl.spec.ts`) is
capture-only and stays green; the red signal is `npm run 3d:check:parity`
reporting ~100% changed for every scenario. Port progress = scenarios dropping
out of that report. `glLineWidth > 1` (model bbox scenario) has no WebGL
equivalent — expect that one to need quad emulation to go green.
The suite drove the port TDD-style: the harness started against no-op FFP
stubs (~100% changed everywhere), and the `wasm/gl1` emulation layer ground
the parity report down milestone by milestone (substrate → lighting →
display lists/arrays → GLU quadrics). **Current state: 47/47 under the 0.02
parity floor, no floors.json overrides needed.**
Two caveats the parity floor cannot see (verified by eyeballing renders):
- Small-geometry scenarios (the GLU arrows, the spheres gizmo, sparse grids)
fit under the floor even when absent — a regression there needs the
triptych/eyeball check, not just the report.
- `glLineWidth > 1` is clamped to 1 by browsers (gizmo axes, native width
2–4 lines render thinner); the affected coverage is small enough to stay
under the floor.
## Scenario tiers (47 scenarios)

View file

@ -1,8 +1,8 @@
/**
* 3D-renderer WebGL test harness (WASM) — runs the shared scenarios
* (tests/3d-regression/scenarios/) in the browser. Today the legacy GL
* surface is wasm/stubs/gl_ffp_stub.c no-ops, so every scenario renders a
* black canvas: the TDD red state the WebGL port turns green.
* (tests/3d-regression/scenarios/) in the browser. The legacy GL surface is
* implemented by the wasm/gl1 GL1->WebGL2 emulation layer; the parity level
* (npm run 3d:check:parity) compares these renders against the native goldens.
*
* Unlike the GAL harness this needs no wx window: the renderer draws into
* whatever context is current, so a direct emscripten WebGL2 context on

View file

@ -1,11 +1,11 @@
# Makefile for the 3D-renderer WebGL test harness (WASM) — TDD RED STATE.
# Makefile for the 3D-renderer WebGL test harness (WASM).
#
# Compiles the SAME shared scenarios + real KiCad 3D-viewer TUs as the native
# golden generator (tests/3d-regression/native/CMakeLists.txt), but links the
# fixed-function GL surface against wasm/stubs/gl_ffp_stub.c no-ops — exactly
# how the production kicad build satisfies RENDER_3D_OPENGL's link today.
# Every scenario therefore renders BLANK until the WebGL port replaces those
# stubs; `npm run 3d:check:parity` is the port-progress meter.
# golden generator (tests/3d-regression/native/CMakeLists.txt), linking the
# fixed-function GL surface against the wasm/gl1 GL1->WebGL2 emulation layer —
# exactly how the production kicad build satisfies RENDER_3D_OPENGL's link.
# `npm run 3d:check:parity` compares the browser renders against the native
# goldens (47/47 under floor since the port).
#
# Usage:
# make # Build
@ -96,7 +96,7 @@ TESTIMPL_SRCS = ../native/board_adapter_test_impl.cpp \
../native/render3d_test_accessor.cpp
# Same real-KiCad TU list as the native CMakeLists (minus glad — Emscripten
# provides the modern GL surface, gl_ffp_stub.c the legacy one).
# provides the modern GL surface, wasm/gl1 the legacy one).
KICAD_3D_SRCS = \
$(KICAD_ROOT)/3d-viewer/common_ogl/ogl_utils.cpp \
$(KICAD_ROOT)/3d-viewer/3d_rendering/image.cpp \