---
url: /guide/concepts/reactive-rendering.md
---
# About reactive rendering

Radiance does not run a game loop that redraws every frame. It draws when something changed, and stays idle the rest of the time. This page explains the model and when to step outside it.

## The idea

A render is a response to a change. Update a uniform, resize the canvas, finish loading a texture — each of those schedules a draw. If nothing happens, nothing is drawn, and the GPU stays quiet.

That matters because most canvases are not games. A still image, a gradient that only moves when the user drags a slider, or a shader that reacts to the pointer has no reason to run at 60 fps. Rendering on demand saves battery and leaves the frame budget to the rest of the page.

The example below demonstrates this behavior: the render counter only increments when you interact with the uniform-controlled slider, showing that renders are scheduled reactively rather than continuously.

::: example-editor {deps=tweakpane@^4.0.5}

```ts
import { glCanvas } from "@radiancejs/gl";
import { Pane } from "tweakpane";
import vertex from "./vertex.frag?raw";
import fragment from "./uniforms.frag?raw";
import "./styles.css";

const { uniforms, onAfterRender } = glCanvas({
  canvas: "#glCanvas",
  vertex,
  fragment,
  uniforms: {
    uWarp: 2.8,
    uLacunarity: 3.2,
    uScale: 1.4,
    uResolution: ({ canvasResolution }) => canvasResolution,
  },
});

const pane = new Pane({ title: "Uniforms" });

// updating the uniforms object will trigger a re-render
pane.addBinding(uniforms, "uWarp", { label: "Warp", min: 1, max: 5 });
pane.addBinding(uniforms, "uLacunarity", { label: "Lacunarity", min: 2, max: 4 });
pane.addBinding(uniforms, "uScale", { label: "Scale", min: 0.5, max: 4 });

const renderCount = document.querySelector("#renderCount")!;
onAfterRender(() => {
  renderCount.firstChild!.nodeValue = `${Number(renderCount.textContent) + 1}`;
});

```

```frag
in vec3 aPosition;
uniform vec2 uResolution;
out vec2 vUv;

void main() {
   vUv = (2.f * aPosition.xy - 1.f) * uResolution / uResolution.y;

   gl_Position = vec4(2.0f * aPosition - 1.0f, 1.0f);
}
```

```frag
varying vec2 vUv;
uniform float uScale;
uniform float uWarp;
uniform float uLacunarity;
uniform vec2 uResolution;

// hash & value noise
float hash(vec2 p) {
  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
}

float noise(vec2 p) {
  vec2 i = floor(p);
  vec2 f = fract(p);
  vec2 u = f * f * (3. - 2. * f);
  return mix(
    mix(hash(i), hash(i + vec2(1., 0.)), u.x),
    mix(hash(i + vec2(0., 1.)), hash(i + vec2(1., 1.)), u.x),
    u.y
  );
}

// fractal brownian motion
float fbm(vec2 p) {
  float value = 0.;
  float amplitude = .5;
  for (int i = 0; i < 5; i++) {
    value += amplitude * noise(p);
    p = p * uLacunarity + vec2(1.7, 9.2);
    amplitude *= .5;
  }
  return value;
}

// cosine color palette
vec3 palette(float t) {
  return vec3(.42, .36, .55) + vec3(.38, .34, .38) * cos(6.28318 * (vec3(1., .9, .7) * t + vec3(.1, .25, .55)));
}

void main() {
  vec2 uv = vUv;

  // domain-warped fbm: q warps r, r warps the final value
  vec2 q = vec2(fbm(uv * uScale), fbm(uv * uScale + vec2(5.2, 1.3)));
  vec2 r = vec2(
    fbm(uv * uScale + uWarp * q + vec2(1.7, 9.2)),
    fbm(uv * uScale + uWarp * q + vec2(8.3, 2.8))
  );
  float f = fbm(uv * uScale + uWarp * .8 * r);

  vec3 color = palette(f + .2 * length(q));
  color = mix(color, palette(f * f + .5), clamp(length(r.x), 0., 1.) * .5);

  // soft vertical falloff
  color *= smoothstep(.0, .5, gl_FragCoord.y / uResolution.y) * .6 + .5;

  gl_FragColor = vec4(color, 1.);
}

```

```css
html {
  color-scheme: light dark;
}

body {
  margin: 0;
}

canvas {
  width: 100svw;
  height: 100svh;
  display: block;
}

```

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>RadianceJS Example</title>
  </head>
  <body>
    <style>
      #renders {
        position: absolute;
        left: 1em;
        bottom: 1em;
        font-family: sans-serif;
        font-size: 1.5rem;
      }
    </style>
    <canvas id="glCanvas"></canvas>
    <div id="renders">Renders: <strong id="renderCount">0</strong></div>
    <script src="/index.ts"></script>
  </body>
</html>

```

:::

## What schedules a render

In the default `auto` mode, a render is requested when:

* A uniform value on any pass of the pipeline is updated (including effect uniforms).
* The canvas is resized (the resolution uniforms change too).
* A uniform source resolves later than the first render — a promise uniform that settles, for example a [texture](../essentials/load-textures) finishing its download.
* A video texture presents a new frame: Radiance listens to video frames and updates the uniform for you.

An identical assignment — the same number, or the same object reference — is ignored: the proxy compares for you. A fresh array or object with the same contents still counts as an update.

Several updates in the same tick are merged into a single draw. Updating ten uniforms in a row paints once, on the next animation frame.

## Render modes

Rendering policy is set with `renderMode` on `glCanvas`:

| Mode           | Behaviour                                                     | Use it for                                          |
| -------------- | ------------------------------------------------------------- | --------------------------------------------------- |
| `"auto"`       | Draw when something changes, at most once per animation frame | Static images, interactive pieces, UI-bound visuals |
| `"continuous"` | Draw every animation frame                                    | Anything driven by `uTime`                          |
| `"manual"`     | Draw only when you call `render()`                            | Sims you step yourself, canvas export, gated motion |

If you do not pass `renderMode`, Radiance infers it: `continuous` when one of the uniform functions has `time` in its name (`uTime`, `uElapsedTime`, …) AND is a function, `auto` otherwise. That is why adding

```ts
uniforms: {
  uTime: ({ time }) => time / 500,
}
```

to a shader starts a loop all by itself. It is also why the inference is easy to lose — rename the uniform to `uClock` and you fall back to `auto`, and the animation freezes until something else updates. When in doubt, pass `renderMode` explicitly.

In `continuous` mode the clock is a `loop` you can stop: `play()` and `pause()` control it, and `immediate: false` keeps it paused until you ask. See [Choose when to render](../essentials/render-modes) for the recipes.

## The cost of a frame

Rendering on demand is not free of scheduling — it is free of *unnecessary* scheduling. A render still costs the same: your fragment shader runs once per pixel of the canvas (times the device pixel ratio), plus every [post effect](../post-processing/effect-chain) in the chain. Reactivity decides *when* that cost is paid, not how large it is.

Two things have a bigger impact on the cost of a frame than anything else: the number of pixels (see [device pixel ratio](../essentials/resize-and-dpr)) and the number of full-screen passes (see [About performance](./performance)).

## Where the reactivity lives

The `uniforms` object returned by `glCanvas` (and by every pass) is a `Proxy`. Writing to it notifies the pass, the pass notifies the compositor, and the compositor requests a render. Nothing watches your shader or your scene: if a value never goes through `uniforms`, Radiance never learns about it.

The same mechanism runs through the whole chain. Updating `bloom.uniforms.uMix` or a custom `effectPass` uniform schedules a render just like the main pass does.

::: tip Silent updates
Only assignments to the `uniforms` object are observed. Mutating an array or texture in place (`uniforms.uOffset[0] = 1`) does not notify anything — assign a new value instead (`uniforms.uOffset = [1, 0]`).
:::

## See also

* [Choose when to render](../essentials/render-modes) — the `renderMode` recipes and the `loop` helper.
* [Update uniforms at runtime](../essentials/update-uniforms) — value, promise and function sources.
* [About the rendering pipeline](./rendering-pipeline) — what those renders actually execute.
* [About performance](./performance) — what a frame costs once it is scheduled.
