Lay a shader over a camera's whole picture (#299)

A shader so far worked only on its own wearer. Effects over the whole
game picture, such as a vignette, grey, scanlines or a red flash on a
hit, had no place to live. A camera now wears one, drawn the way a
field shader of a particle source is (#170).

- The camera gets a Shader row and, while one is picked, a Shader
  resolution row. The shader's properties follow as camera rows. They
  load, animate and appear in a Properties node under Type Camera.
- Every view keeps masks and objects in one container. CameraShade
  renders it into the camera's picture, cleared to the background,
  and draws the shader over the frame. Game tab and play.html take
  the container off the stage while the picture stands in for it.
- Screen pixels gives the picture as many pixels as it covers on
  screen. Camera pixels uses View width x View height and scales up
  without smoothing.
- A pixel counts as a camera pixel in both (the user's choice). The
  uniform uPixelScale makes Texture size read View width x View
  height, so a Blur keeps its reach at any game scale.
- Each camera wears its own shader, overlay cameras included. A red
  flash on the game camera leaves the HUD of an overlay camera alone.
- The scene view's eye has a Shader switch on the Camera row, off by
  default. With it on, the main camera's shader lies over its frame,
  below symbols and gizmos, and the world around it stays drawn.
- New tool tools/perf-camera-shader.mjs measures the cost.

Measured on stein2 (HD 630, Game tab at Fit 1310x679): a camera
shader that hands the picture through stays inside the scene's own
spread of 3 to 5 fps between runs. A Blur of 4 cost 4 to 8 fps.

Tests:
- Gate on melektaus-atx: 227 files, 3497 tests (3487 + 10).
- e2e 63 alone: 11 checks (6 + 5), e2e sum 1725 counted.
- 63e-63i: pass-through is byte-equal and upright at 100%, flat red
  reaches the corners while the overlay keeps its green, Texture
  size reads 640 x 360 in both resolutions at Fit, no shader draws
  as before, and the scene view shows it only with the switch on.
- Counter-checks: a camera left out of the shader wearers fails 1
  unit test. Counting screen pixels fails 63g with #ab6000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/editor/debug/renderHooks.ts

@@ -194,6 +194,9 @@ export function renderHooks({ app, state, editor }: HookContext) {
     /** The device pixels of a source's field-shader picture, null while none is drawn (#170). */
     fieldPixels: (objectId: string, where: 'scene' | 'game' = 'scene') =>
       (where === 'game' ? gameView : viewport).fieldPixels(objectId),
+    /** The pixels of the camera shader's picture, null while none is laid over the view (#299). */
+    cameraShaderPixels: (where: 'scene' | 'game' = 'game') =>
+      (where === 'game' ? gameView : viewport).cameraShaderPixels(),
     /** Graphs compiled so far; a moved node must not add one (#65). */
     shaderCompiles: () => shaderLibrary.compiles,
     /** Which views redraw every tick because a Time shader is on screen. */

src/editor/inspector/portSection.ts

@@ -96,10 +96,11 @@ export function buildPropertyPortSection(
   }
   if (target !== 'behavior') {
     const owner = `a ${targetLabel(target)}`;
-    // A sprite's or text's rows go on with the parameters of the shader it wears – any shader, the node
-    // cannot know which, so each entry says whose it is. Keyed by the def itself: a shader parameter and
-    // a property of the type may share a name, and only the shader's entry earns the note.
-    const shaderRows = target === 'sprite' || target === 'text' ? allShaderParamRows(host.state.project) : [];
+    // A sprite's, text's or camera's rows go on with the parameters of the shader it wears – any shader,
+    // the node cannot know which, so each entry says whose it is. Keyed by the def itself: a shader
+    // parameter and a property of the type may share a name, and only the shader's entry earns the note.
+    const wears = target === 'sprite' || target === 'text' || target === 'camera';
+    const shaderRows = wears ? allShaderParamRows(host.state.project) : [];
     const from = new Map(shaderRows.map((row) => [row.def, row.shaders.join(', ')]));
     buildPickedPortSection(host, assetId, node, {
       noun: 'Property',

src/editor/panels/SceneVisibilityPopup.ts

@@ -5,8 +5,15 @@ import type { EditorState } from '../state';
 import { ASSET_ICON_SVG } from './assetIcons';
 import { VISIBILITY_ICON_SVG } from './toolbarIcons';
 
-const PARTS: readonly VisibilityPart[] = ['symbol', 'label', 'shape'];
-const PART_CAPTIONS: Record<VisibilityPart, string> = { symbol: 'Symbol', label: 'Name', shape: 'Shape' };
+const PARTS: readonly VisibilityPart[] = ['symbol', 'label', 'shape', 'shader'];
+const PART_CAPTIONS: Record<VisibilityPart, string> = {
+  symbol: 'Symbol',
+  label: 'Name',
+  shape: 'Shape',
+  shader: 'Shader',
+};
+/** Switches only a few types have: the others leave the column empty rather than greyed out. */
+const RARE_PARTS: ReadonlySet<VisibilityPart> = new Set(['shape', 'shader']);
 /** One column per switch, wide enough for its caption. */
 const COLUMN = 44;
 const NAME_WIDTH = 90;
@@ -20,9 +27,9 @@ function gap(w: number): Spacer {
 
 /**
  * The eye in the scene tab's header: every type that can be placed, and per type a switch for its symbol, its
- * name and – a collider only – its outline in the scene view. A switch a type does not have is
- * greyed out, or missing where no other type has it either. Clicks keep it open: one usually
- * switches several.
+ * name, – a collider only – its outline in the scene view and – a camera only – its shader (#299). A
+ * switch a type does not have is greyed out, or missing where no other type has it either. Clicks keep
+ * it open: one usually switches several.
  */
 export class SceneVisibilityPopup extends Popup {
   private readonly switches = new Map<string, Button>();
@@ -45,7 +52,7 @@ export class SceneVisibilityPopup extends Popup {
     row.add(new Label(ASSET_TYPE_LABELS[type], { width: NAME_WIDTH }));
     const parts = visibilityParts(type);
     for (const part of PARTS) {
-      if (part === 'shape' && !parts.includes(part)) {
+      if (RARE_PARTS.has(part) && !parts.includes(part)) {
         row.add(gap(COLUMN));
         continue;
       }

src/editor/panels/toolbarIcons.ts

@@ -8,6 +8,7 @@ import menu from './icons/menu.svg?raw';
 import pause from './icons/pause.svg?raw';
 import play from './icons/play.svg?raw';
 import redo from './icons/redo.svg?raw';
+import shader from './icons/shader.svg?raw';
 import showLabel from './icons/show-label.svg?raw';
 import showShape from './icons/show-shape.svg?raw';
 import showSymbol from './icons/show-symbol.svg?raw';
@@ -16,9 +17,10 @@ import undo from './icons/undo.svg?raw';
 
 export const TOOLBAR_ICON_SVG = { menu, undo, redo, eye, play, pause, stop };
 
-/** The switches behind the eye: a type's symbol, its name, a collider's outline. */
+/** The switches behind the eye: a type's symbol, its name, a collider's outline, a camera's shader. */
 export const VISIBILITY_ICON_SVG: Record<VisibilityPart, string> = {
   symbol: showSymbol,
   label: showLabel,
   shape: showShape,
+  shader,
 };

src/editor/viewport/SceneViewport.ts

@@ -54,7 +54,7 @@ import { drawSymbolIcon, SYMBOL_GRID, SYMBOL_OUTLINE, type SymbolIcon } from '..
 import { type JointLink, jointLinkOf } from '../../viewport/jointLinks';
 import { type LabelBox, stackLabels, type WantedLabel } from '../../viewport/labelRows';
 import { layoutSymbols, type SymbolSpot } from '../../viewport/symbolLayout';
-import { cameraOfItems } from '../../viewport/activeCamera';
+import { type ActiveCamera, cameraOfItems } from '../../viewport/activeCamera';
 import { freeViewOfCamera, screenToWorld, type View, worldToScreen } from '../../viewport/view';
 import { type CastRay, RAY_SHOWN, type World } from '../../runtime/World';
 import { FreeViewport } from './FreeViewport';
@@ -176,9 +176,9 @@ export class SceneViewport extends FreeViewport {
 
   constructor(state: EditorState) {
     super(state);
-    // Grid behind the content, links below the symbols, gizmos above everything clipped.
+    // Grid behind the content, links below the objects, gizmos above everything clipped.
     this.addChildAt(this.grid, 1);
-    this.world.addChildAt(this.links, 1);
+    this.world.addChildAt(this.links, 0);
     this.content.addChild(this.gizmos);
     this.links.eventMode = 'none';
     this.labelLayer.eventMode = 'none';
@@ -278,6 +278,15 @@ export class SceneViewport extends FreeViewport {
     return Boolean(this.holder());
   }
 
+  /** The main camera's shader over its frame, while the eye's switch says so (#299); off by default. */
+  protected override shadingCamera(_main: ActiveCamera | null, items: DrawItem[]): ActiveCamera | null {
+    return shows(this.state.project.sceneVisibility, 'camera', 'shader') ? cameraOfItems(items) : null;
+  }
+
+  protected override keepsWorldAroundShader(): boolean {
+    return true;
+  }
+
   protected override get itemsInteractive(): boolean {
     return true;
   }