Shader

--- name: shader-web description: Getting a shader onto a page - the WebGL bootstrap, uniform plumbing, device pixel ratio, resize, pause on hidden tab, reduced motion, the drop-in HTML file, parameter updates over postMessage, and embedding it without a framework. Read this when the shader has to run in a browser. whenToUse: When deploying a shader to a web page, embedding it as a background, wiring up controls, or debugging a page where the canvas is black but the shader compiles. --- # Shaders on the web `shader_target target=web` writes one self-contained HTML file: no framework, no build step, no request. That is the deployment model the Radiant corpus uses, and it is the right default because a page that needs nothing cannot break because something is missing. ## The bootstrap, in full Everything a fragment shader page needs, and nothing else: ```html Shader

``` Every part of that is load-bearing: - **`preserveDrawingBuffer`** is not set here. Leave it off for animation (it costs performance); turn it ON if you need `toDataURL()` or a screenshot. - **DPR capped at 2.** `canvas.width = clientWidth * devicePixelRatio` uncapped renders four times the pixels on a 2x display for a difference nobody sees. - **`visibilitychange`.** A background tab that keeps drawing wastes a battery and is the most common complaint about shader backgrounds. - **`resize` sets `canvas.width`**, which resets the drawing buffer - so the viewport must be set again in the same handler, after the size. - **The error is thrown with the log.** A black canvas with nothing in the console is the worst outcome, and it is always avoidable. ## Two contexts, two dialects | dialect | context | extra | |---|---|---| | `es100` (gl_FragColor) | `getContext('webgl')` | call `getExtension('OES_standard_derivatives')` before compiling if you use `fwidth` | | `es300` (`#version 300 es`) | `getContext('webgl2')` | none | | `shadertoy` / `shader-skills` | `getContext('webgl2')` | the page must supply `iResolution`, `iTime`, `iMouse`, `iFrame` | A WebGL 1 context rejects a `#version 300 es` shader with `unsupported shader version 300` - which reads like a shader bug and is a context bug. `shader_target target=web` picks the right one for you. ## Driving it from outside: the postMessage contract A drop-in page has no API, so it takes parameter updates over `postMessage`. This is Radiant's own shape, and pages this row emits accept exactly it: ```js // on the parent page const frame = document.querySelector('iframe'); frame.contentWindow.postMessage({ type: 'param', name: 'SPEED', value: 0.8 }, '*'); ``` The page listens: ```js window.addEventListener('message', (event) => { const data = event.data; if (!data || data.type !== 'param') return; if (data.name === 'SPEED') speed = data.value; }); ``` Match on the **parameter name** (`SPEED`, as declared in `// @param SPEED ...`), not on the uniform name. The page owns the translation to `u_speed`. ## Embedding it as a background ```html ``` Three habits: `aria-hidden="true"` (it is decoration, not content), `z-index: -1` with the content above it, and **no pointer events** - an iframe over the page eats every click. If it must sit behind text, put it in a container with `pointer-events: none`. Do not put a shader behind text without checking contrast: a moving background behind body copy is a readability failure waiting to happen. Either keep it behind a scrim (`background: rgba(0,0,0,.55)` over the canvas) or keep it in a hero band. ## Inline instead of an iframe If the page already has a canvas, the bootstrap above drops in directly: keep the program in a module, expose `setParam(name, value)` and `resize()`. The iframe is only needed when the shader is a *file* - which is the case for a drop-in background, and which is why the emitted artefact is a whole page. ## Reduced motion is not optional ```js const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches; const time = reduced ? 0 : (now - start) / 1000; ``` An animation that ignores this preference is an accessibility defect, not a feature. The page this row emits freezes time at 0 when the preference is set, so the shader still shows its picture, unmoving. ## What to check before you ship it 1. It renders **at the size it will be used at** - not at 800x600. 2. No console output. Warnings are still read as errors by people who look. 3. It stops when the tab is hidden (watch `requestAnimationFrame` in the profiler). 4. It survives a resize and a device rotation. 5. It costs what you think: on a 4K display a heavy raymarcher is 8.3M pixels per frame. `shader_render` at your intended size is the honest measurement. 6. Nothing reaches the network. A shader needs no font, no image, no CDN. `shader_verify` proves the GLSL; the page is where the driver, the DPR and the resize behaviour get their say. Test it in the browser you are shipping to.