trx-rs/aidocs/WEBGL.md

Canvas2D to WebGL Transition Plan

Goal

• Replace all runtime Canvas2D rendering in the frontend with WebGL.
• Remove Canvas2D code paths after feature parity is reached.
• Keep existing interaction behavior (zoom/pan/tune/BW drag/tooltips/overlays) intact.

Scope

• src/trx-client/trx-frontend/trx-frontend-http/assets/web/app.js
  • overview-canvas
  • spectrum-canvas
  • signal-overlay-canvas
• src/trx-client/trx-frontend/trx-frontend-http/assets/web/plugins/cw.js
  • cw-tone-waterfall
• New shared WebGL utility module:
  • assets/web/webgl-renderer.js

Non-Goals

• No Canvas2D fallback path.
• No feature redesign outside rendering internals.

Constraints

• Must preserve existing data flow and event wiring.
• Must keep map/decoder/bookmark integrations unchanged.
• Must remain dependency-free (no external rendering libraries).

2-Phase Migration

1. Phase 1 (Rendering engine insertion)

• Add shared WebGL renderer utility (primitives + textures + color parsing).
• Keep existing business logic and interaction handlers untouched.
• Swap draw targets from 2D contexts to WebGL primitives.

2. Phase 2 (Canvas2D removal and parity closure)

• Remove getContext("2d") usage from app and plugins.
• Remove obsolete 2D-specific cache paths.
• Validate behavior on resize/theme/style/stream reconnect/decoder mode changes.

Parallel Workstreams ("Agents")

1. Agent A: Shared WebGL core

• Build webgl-renderer.js with:
  • HiDPI resize handling
  • Solid/gradient rects
  • Polyline/segment/fill primitives
  • RGBA texture upload + blit
  • CSS color parser helpers

2. Agent B: Main spectrum/overview migration

• Port drawSpectrum, drawHeaderSignalGraph, drawSignalOverlay, and clear paths.
• Replace 2D offscreen waterfall cache with WebGL texture updates.
• Keep frequency axis/bookmark axis DOM behavior unchanged.

3. Agent C: CW tone picker migration

• Port drawCwTonePicker primitives to WebGL.
• Preserve auto/manual tone interactions and mode gating.

Acceptance Criteria

• No frontend getContext("2d") usage remains.
• All four canvases render using WebGL and respond to resize/DPR changes.
• Spectrum interactions still work:
  • wheel zoom
  • drag pan
  • BW edge drag
  • click tune
• Overview strip continues showing waterfall/history.
• CW tone picker remains interactive and reflects current spectrum/tone.

Verification Checklist

• Static:
  • rg -n 'getContext\\("2d"\\)' src/trx-client/trx-frontend/trx-frontend-http/assets/web
• Runtime smoke:
  • Open main tab: verify overview + spectrum + overlay.
  • Toggle theme/style.
  • Resize window and spectrum grip.
  • Enable CW decoder and validate tone picker updates/click-to-set.
  • Confirm no rendering exceptions in browser console.

Rollout Notes

• Initial rollout is WebGL-only.
• If a browser lacks WebGL, canvases remain blank by design until a dedicated fallback policy is defined.