pcbjam/docs/features/fork-cleanup/10-3d-viewer.md

# 10 — Re-enable the 3D viewer

> **Verdict: port — and there's a cheap first step.** KiCad ships *two* 3D renderers: an
> OpenGL one (pure fixed-function GL 1.x — far from WebGL2) and a **pure-CPU raytracer that
> needs zero OpenGL**. The fork currently nulls the raytracer out. Turning 3D on via the
> raytracer (**Route C**) is low-risk and brings the render-to-PNG job and VRML export back
> nearly free; a WebGL2 port of the interactive renderer (**Route B**) is the follow-up.

## Why it's off (timeline, with primary sources)

| Date | Commit (kicad) | What |
|---|---|---|
| 2025-12-21 | `46bb16e86b` | "Enable 3D viewer build for WASM with OpenGL stubs" — compiled *only* so headers resolve. Message: "OpenGL rendering won't work at runtime … avoids complex stubbing." |
| 2026-01-03 | `a61d2ea406` | OpenGL GAL on `-sLEGACY_GL_EMULATION`; added the +190-line `kiglew.h` `__EMSCRIPTEN__` branch (display lists + lighting as **no-ops**). 3D "built" but couldn't draw. |
| 2026-01-10 | `d8a9ac4304` | "Disable 3D viewer functionality for WASM builds" — same day `WEBGL_GAL` landed and the build swapped emulation → `-sFULL_ES3`. Message: 3D "require[s] native OpenGL rendering (not WebGL)". Built with `KICAD_BUILD_3D_VIEWER_WASM=OFF`. |
| 2026-03-20 | `4ddb9b47f5` | "Migrate to pure WebGL 2.0 without FULL_ES3 emulation" — 2D GAL goes pure WebGL2; the only GL link flag today is `-sMAX_WEBGL_VERSION=2`. |

Recorded rationale: `features/gl-article/README.md:274-276,421-422` — the 3D viewer is "a
separate legacy-GL renderer, not GAL" needing "GLU + fixed-function", declared out of scope
when the strategy became "progressively remove the Emscripten crutch." So it was a deliberate
scoping decision when the emulation layer it depended on was removed — not a crash.

## What the OpenGL renderer actually uses

`3d-viewer/3d_rendering/opengl/` = 6 files, **4,555 lines**. It's pure GL 1.x fixed-function:

- **Immediate mode** — 153 tokens (`glBegin`/`glEnd` ×28, `glVertex*`/`glNormal3*`/`glTexCoord2*`).
- **Display lists** — 36 refs in 2 files, and they're the **primary board-geometry path**:
  `layer_triangles.cpp:582-714` bakes every layer's triangles into `glGenLists`/`glNewList`
  wrapping a `glDrawArrays`; `render_3d_opengl.cpp:1303-1315` for the grid.
- **Fixed-function matrix/lighting** — ~117 tokens (`glMaterialfv`, `glLightfv`,
  `glMatrixMode`/`glPush/PopMatrix`, `GL_LIGHTING`, …).
- **Client-state arrays** — 49 tokens. **GLU** — 36 (`gluNewQuadric`/`gluCylinder`/`gluSphere`
  for vias/pads).
- **Modern** — zero shaders, zero VAOs; only `3d_model.cpp` uses VBOs (GL 1.5 style).

Structurally friendlier than the raw counts suggest: geometry already lives in CPU triangle
containers, display lists are thin `glDrawArrays` wrappers, `3d_model.cpp` is already VBO,
camera/transforms are already glm.

## Route A — LEGACY_GL_EMULATION for the 3D viewer: REJECTED

- The flag is **module-global at link**: `GLEmulation.init()` replaces the module-wide JS
  bindings (`glDrawArrays`, `glEnable`, `glBindBuffer`, `glGetString`, …) for *all* contexts,
  including the flagship 2D `WEBGL_GAL`'s. Concretely it corrupts the GAL's ES3 shaders —
  emscripten prepends `#extension GL_OES_standard_derivatives` to any fragment shader using
  `dFdx` (`kicad_frag.glsl:138` does), and prepending anything before `#version 300 es` is a
  guaranteed ES3 compile error. Separate canvases/contexts do **not** isolate this (hooks are
  per-module).
- Even ignoring that: emscripten never implemented display lists (issue #688 — the main board
  path draws nothing), GLU quadrics are absent, lighting emulation has `throw 'TODO'` holes.
  You'd rewrite the display-list and quadric paths anyway (the hard half of Route B) while
  regressing 2D and re-adding ~200 KB of the fragility the project already escaped. **Reject.**

## Route C — CPU raytracer + blit (do this first, low risk)

`RENDER_3D_RAYTRACE_RAM` (`render_3d_raytrace_ram.cpp`, 159 lines) is **100% GL-free**: it
renders into a plain `uint8_t` RGBA buffer (`initPbo()` is just `new uint8_t[w*h*4]`) and
exposes `GetBuffer()`. It's **progressive by design** — each `Redraw()` traces blocks up to a
400/750 ms budget then yields, so a serial browser loop still animates. Both existing
consumers already convert buffer → `wxImage` with no GL (`eda_3d_viewer_frame.cpp:846-866`
screenshot; `pcbnew_jobs_handler.cpp:817-885` render job).

Recipe:

1. `KICAD_BUILD_3D_VIEWER_WASM=ON`, and **genex-out the GL renderer TUs**
   (`render_3d_opengl.cpp`, `layer_triangles.cpp`, …) the same way `render_3d_raytrace_gl.cpp`
   is already excluded (`3d-viewer/CMakeLists.txt:49`) — this sidesteps the legacy-GL link
   errors entirely. The raytracing subtree (12,232 lines) has no GL.
2. Have `EDA_3D_CANVAS` instantiate `RENDER_3D_RAYTRACE_RAM` under `__EMSCRIPTEN__` (it's
   renderer-agnostic via `RENDER_3D_BASE`), and **blit** the buffer — either a plain wxWindow
   painting the `wxImage` through the wx-wasm 2D canvas DC (zero GL), or a ~100-line WebGL2
   textured quad (infra exists in `common/gal/webgl/fullscreen_quad.cpp`).
3. **Delete the fork gates** — they're keyed on `__EMSCRIPTEN__`, *not* the CMake option, so
   flipping the flag alone isn't enough: `eda_3d_canvas.cpp` (raytracer nulled, raytracing
   request early-returned), `pcbnew/pcbnew.cpp` (3D settings panels — see the
   `PANEL_TOOLBAR_CUSTOMIZATION` bug in [07](07-native-build-bugs-and-tooling.md)),
   `pcbnew_jobs_handler.cpp`/`.h` (render job), and `exporter_vrml.cpp` (in-file stub). Delete
   the three big stub TUs too (`wasm/stubs/3d_viewer_stub.cpp`, `3d_canvas_stub.cpp`,
   `3d_scenegraph_stub.cpp`, ~1,200 lines).

Caveats: main tracing runs **serial** under the `bs_thread_pool` inline patch (still usable,
because progressive); the preview / SSAO / DLAA passes use raw `std::thread` + a `sleep_for`
spin-wait — pthreads *are* enabled in the build (`-pthread -sUSE_PTHREADS=1
-sPTHREAD_POOL_SIZE=…`), so they run, but the spin-wait blocks the browser main thread per
pass and is worth reviewing for jank.

## Route B — WebGL2 port of the interactive renderer (follow-up)

Scope is ~4,555 lines / 6 files — roughly **1/5 of the 2D GAL port** and far less novel (no
compositor, no multi-FBO juggling). The work: display-list → VBO (mechanical, the lists wrap
`glDrawArrays` of CPU triangle containers), client-state arrays → generic vertex attribs,
fixed-function transforms → a small matrix-stack helper (already glm), ~2 shader pairs
(Phong-lit per-material + flat), GLU quadrics → a triangle helper (small; vias/pads/gizmo).
Reuse `common/gal/webgl/`'s shader infra + `convert_glsl_es3.py`.

Divergence: mirror the 2D precedent — new files (`3d_rendering/webgl/`), swapped via a CMake
genex like the existing `render_3d_raytrace_gl.cpp` exclusion. Near-zero upstream-file diff
beyond the swap + un-gating. Gives the **interactive** GPU-speed orbit/pan view. Risk: medium
(GPU correctness; the e2e screenshot harness pattern exists). Prereq: model loading (below).

## Model loading (needed for both B and C to show components)

Upstream loads `plugins/3d/{vrml,oce,idf}` as **runtime DSOs** —
`S3D_PLUGIN_MANAGER::loadPlugins()` scans a directory and `wxDynamicLibrary`-loads each. There
is **no static-registration path upstream**, and `wasm/stubs/3d_scenegraph_stub.cpp` (440
lines) currently stubs the whole `S3D_CACHE` + scenegraph + `S3D::WriteVRML`.

Static linking entails: compiling the plugin sources into the binary with **per-plugin symbol
prefixes** (they export identical C ABI names — `Load`, `GetFileFilter`, … — so they collide;
wrap each TU with `-Dname=vrml_name` or a wrapper), plus a small `__EMSCRIPTEN__` path (or a
subclassed `KICAD_PLUGIN_LDR_3D`) with a 3-entry static registry — cleanest as one new
wasm-layer file. Sizes: **vrml** (VRML1/2 + X3D, fully in-tree, **no external deps**) = 17,835
lines; **oce** (STEP/IGES — needs OCC, which **is already built for wasm**: OCC 7.8 via
`--with-occ`, verified `libTK*.a` in the sysroot) = 1,407; **idf** = 931. `kicad_3dsg` must
become STATIC for wasm (it's `add_library(SHARED)` today). Plus: ship 3D model assets to the
FS (models are *referenced*, not embedded — see
[`../libraries/0001-library-management.md`](../libraries/0001-library-management.md)).

Start with the VRML plugin (no deps) for `.wrl` models; add OCE for STEP once VRML works.

## Render job & VRML export — free with either route

Both only need the 3D model cache / scenegraph / raytracer, **not** the GL renderer:

- `JobExportRender` (`pcbnew_jobs_handler.cpp:641-898`) is `RENDER_3D_RAYTRACE_RAM` +
  `BOARD_ADAPTER` + 3d_cache → board-render-to-PNG/JPEG works as soon as 3d-viewer links.
- `exporter_vrml.cpp`'s real implementation needs `S3D_CACHE` + the SGNODE/IFSG API — un-stub
  by **deleting** the fork's `#else` block (a divergence *reduction*). Board-only export works
  immediately; embedding component models additionally needs the static VRML plugin above.

## Sequencing

**C first** (working 3D view + render job + VRML export, low risk, mostly deletes gates) →
**B second** (interactive upgrade) → **A never**.