Skip to content

feat(viewer): WebGL2 trace rendering (P2) - #108

Merged
neuromechanist merged 2 commits into
mainfrom
feat/viewer-webgl
Jun 3, 2026
Merged

neuromechanist merged 2 commits into
mainfrom
feat/viewer-webgl

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Summary

Moves the signal viewer's per-frame hot path from Canvas 2D to the GPU. Previously each visible channel was a stroked polyline (moveTo/lineTo + stroke) rebuilt on every pan/zoom/cursor-move; with 64 channels over a ~2000 px window that is hundreds of thousands of CPU line segments per frame. Now a WebGL2 canvas rasterizes the background + traces; a transparent 2D canvas on top carries only the chrome.

Design

  • Hybrid two-canvas stack inside a positioned .eegv__scope: .eegv__glcanvas (z0, background + traces) behind .eegv__canvas (z1, transparent: labels, slot dividers, event lines + codes, time axis, scale bar). Both fill the scope via inset:0, sized together.
  • 1 px LINE_STRIP per channel (WebGL lineWidth>1 is unsupported; 1 px matches the 2D renderer's lineWidth=1 exactly, so GL and fallback look the same). One draw call per channel with per-channel color/alpha uniforms; band channels use the same max/min zigzag as drawTrace.
  • Identical pixel math to render.ts (slot baseline, pxPerPhys, clip envelope, colToX, butterfly center slot) so the GPU output is pixel-equivalent to the 2D path.
  • Graceful fallback: createGlTraceRenderer returns null when WebGL2/shader compile is unavailable; the viewer then uses the existing all-2D renderFrame (glCanvas hidden). No behavior change where WebGL is off.

Files

  • gl-trace.ts (new): createGlTraceRenderer (WebGL2 program, VAO, blending, resize/draw/dispose) + pure buildTraceVertices / hexToRgb.
  • render.ts: renderChrome (chrome-only transparent overlay); extracted shared drawButterflyLegend (DRY).
  • viewer.ts: scope wrapper + glCanvas in buildDom; sizeCanvas sizes both canvases and calls glRenderer.resize; renderImpl picks GL+chrome vs 2D; dispose on cleanup.
  • BidsTree.astro: .eegv__scope frame + stacked-canvas CSS.
  • gl-trace.test.ts (new): 8 no-mock geometry tests (line edge x, baseline mapping, clip clamp, band zigzag, dim alpha, butterfly shared baseline, empty frame).

Verification

0 type errors, biome clean, 568 tests (8 new), build OK. Verified live against nm000132 (33 ch EEG+EOG) in headless WebGL2:

  • Stacked traces render crisply, chrome pixel-aligned (light theme).
  • Topo split-panel: GL canvas resizes 738x369 to 488x280 as the scope shrinks; topomap + traces coexist.
  • Dark theme: GL clear color tracks the --color-bg token.

Offload the per-frame hot path (one stroked polyline per channel, rebuilt on
every pan/zoom/cursor-move) from Canvas 2D to the GPU. A WebGL2 canvas draws the
background + signal as 1px LINE_STRIPs (identical pixel mapping to render.ts) and
a transparent 2D canvas on top carries the chrome (labels, dividers, events,
axis, scale bar). Graceful fallback to the all-2D renderFrame when WebGL2 is
unavailable.

- gl-trace.ts: createGlTraceRenderer + pure buildTraceVertices (slot/clip/band
  math mirrors drawTrace), hexToRgb; per-channel color/alpha uniforms, blending
- render.ts: renderChrome (chrome-only, transparent overlay); DRY butterfly legend
- viewer.ts: scope wrapper holds glCanvas (behind) + 2D canvas (front); sizeCanvas
  sizes both + resizes GL; renderImpl picks GL+chrome or 2D fallback; dispose on cleanup
- BidsTree.astro: .eegv__scope frame + stacked .eegv__glcanvas/.eegv__canvas CSS
- gl-trace.test.ts: 8 no-mock geometry tests (line/band/clip/butterfly/dim/empty)

Verified live on nm000132 (33ch): stacked, topo split-panel resize, dark theme.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jun 3, 2026 •

Copy link
Copy Markdown

Deploying nemar-website with  Cloudflare Pages  Cloudflare Pages

Latest commit: 175c1ef
Status:⚡️  Build in progress...

View logs

Addresses 3-agent review of #108:
- createGlTraceRenderer: re-callable init() so a lost context is rebuilt on
  webglcontextrestored; every init failure path frees its GL objects (no
  shader/program/buffer/VAO leaks); guard createBuffer/createVertexArray null +
  aPos==-1; draw/resize/clear no-op while the context is lost
- buildTraceVertices: clamp the band loop to the shortest of nCols/max/min so a
  boundary-truncated envelope never writes NaN vertices
- resize(): only touch the viewport on an actual buffer-size change
- clear(): wipe the GL canvas behind the loading/error overlay (no stale frame)
- viewer: clear the GL layer before painting the loading/unavailable message
@neuromechanist

Copy link
Copy Markdown
Contributor Author

Review findings addressed (commit 175c1ef)

Ran 3 review agents (pixel-fidelity, GL resource/correctness, integration/CSS). Pixel-fidelity came back clean (GL output is equivalent to the 2D fallback across stacked/butterfly/band/clip/colToX). Applied all real findings:

GL resource safety (gl-trace.ts)

  • init() is now re-callable: every failure path frees what it allocated (no leaked shaders on !vs||!fs, no leaked program/shaders on link failure), and createBuffer/createVertexArray null + aPos==-1 are guarded.
  • Context loss: added webglcontextlost (preventDefault + lost flag) and webglcontextrestored (rebuild program/buffer/VAO via init()). draw/resize/clear no-op while lost, so a lost context no longer spins the CPU or draws through stale handles.

Correctness

  • buildTraceVertices: band loop clamped to min(nCols, max.length, min.length) so a boundary-truncated envelope can't read past its data and write NaN vertices.
  • resize(): gl.viewport now only fires on an actual buffer-size change (was every render).
  • Stale-frame: added clear() and call it before the loading/unavailable overlay so the GL layer doesn't retain the prior frame under the transparent 2D chrome.

0 type errors, biome clean, 568 tests, build OK. Re-verified live on nm000132 (33 ch) — rendering unchanged.

@neuromechanist
neuromechanist merged commit fb58c56 into main Jun 3, 2026
1 check was pending
@neuromechanist
neuromechanist deleted the feat/viewer-webgl branch June 3, 2026 22:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant