Immediate mode: why the canvas forgets everything you draw

Almost every surprising thing about the 2D canvas — why you can't move a circle after drawing it, why there's no onclick for a shape, why animation means clearing the whole surface and redrawing it sixty times a second — comes from one root fact that the API never states out loud. Learn it first and the rest of the canvas stops being a bag of quirks and becomes a single coherent design.

Here it is: the canvas has no memory of what you draw. Every drawing call paints pixels into a bitmap immediately and then forgets everything — there is no circle, no rectangle, no object left behind, only colored pixels. This is called immediate mode, and it is the opposite of how the DOM and SVG work. Everything in this lesson is that sentence, unpacked.

Two ways a graphics system can work

There are two fundamental designs for a graphics API, and it's worth naming both because the canvas only makes sense as a deliberate choice between them.

Retained mode is what the DOM and SVG do. When you create a <div> or an SVG <circle>, you hand the browser a description of an object, and the browser keeps that description. It maintains a tree of these objects (the DOM), and it takes responsibility for turning that tree into pixels — re-rendering when something changes, figuring out what you clicked, redrawing after a scroll. You mutate the model (circle.setAttribute('cx', 50)) and the browser re-derives the picture. The system retains your objects.

Immediate mode is what the canvas does. When you call ctx.fillRect(10, 10, 100, 50), the canvas does not create a rectangle object. It rasterizes a filled rectangle into its pixel buffer right now, at that instant, and retains nothing about it. A moment later those pixels are indistinguishable from any other pixels — the canvas could not tell you "there is a rectangle at (10,10)" because as far as it's concerned there isn't one; there are just pixels that happen to be that color. You issue a command, it paints, it forgets. The system draws immediately and moves on.

Neither is "better" — they're suited to different jobs, a tradeoff we'll settle at the end. But you cannot use the canvas correctly without knowing which world you're in, because immediate mode pushes a set of responsibilities onto you that retained mode handles silently.

Watch the forgetting happen

The clearest way to feel immediate mode is to issue commands one at a time and watch pixels accumulate in a buffer that has no idea what produced them. Each command below paints and returns; the canvas keeps only the growing image, never the list of what drew it.

Step through it and notice: after the third command, the surface doesn't "contain a rectangle, a line, and a circle." It contains a bitmap. If you wanted to erase just the rectangle, there is no "rectangle" to erase — you would have to clear the region and redraw everything else that was supposed to be there. That single limitation is the source of the three big consequences below.

Consequence 1: to change anything, you clear and redraw

Because there are no retained objects, there is no such thing as "moving" or "editing" a shape. If a ball is at x=100 and you want it at x=110, you cannot nudge it — there is no ball. What you actually do is erase the whole canvas and draw the entire scene again with the ball one step further along:

function frame() {
  ctx.clearRect(0, 0, canvas.width, canvas.height); // wipe everything
  x += 1;                                            // update your own state
  ctx.beginPath();
  ctx.arc(x, 100, 20, 0, Math.PI * 2);               // redraw from scratch
  ctx.fill();
  requestAnimationFrame(frame);                       // again next frame
}

This is why canvas animation is inseparable from the frame loop: every frame is a full repaint, not an edit. In retained mode the browser would diff and repaint only what changed; in immediate mode you are the render loop, and "the scene" exists only as your own JavaScript variables plus whatever you choose to redraw. The pixels are downstream of your state, never a store of it.

Consequence 2: there is no hit-testing — you own that too

Click a <button> and the browser knows which element you hit, because it retained the element and its geometry. Click on a canvas and the browser knows only that you clicked the canvas — a single element — at some (x, y). It cannot tell you that you clicked "the red circle," because there is no red circle in any model; there are pixels.

So if you want clickable shapes on a canvas, you maintain your own list of logical objects ({type:'circle', x, y, r}) in JavaScript, and on a click you do the geometry yourself — loop your objects, test whether the point falls inside each. The canvas draws them; you remember them. This is the recurring shape of canvas code: a data model you own, plus a draw function that projects it onto the immediate-mode surface each frame. The canvas is a projector, not a database.

Consequence 3: the context is a sticky state machine

There's a subtler consequence of "issue a command, it paints now." A command like ctx.fill() needs to know what color to fill with — but fill() takes no color argument. Instead the color lives in the context as state you set beforehand: ctx.fillStyle = 'red'. And that state is sticky — it stays set until you change it, affecting every subsequent draw.

ctx.fillStyle = 'red';
ctx.fillRect(0, 0, 50, 50);   // red
ctx.fillRect(60, 0, 50, 50);  // STILL red — fillStyle persisted
ctx.fillStyle = 'blue';
ctx.fillRect(120, 0, 50, 50); // blue

This is the same shape as the WebGL state machine from the graphics pipeline module: a small pile of current settings (fillStyle, strokeStyle, lineWidth, the current transform, the clip region) that every immediate command reads from. It follows directly from immediate mode — since each command paints instantly with no arguments for style, the style has to already be sitting in the context. Managing that sticky state (and the save()/restore() stack that tames it) is its own lesson, but the reason it works this way is the one you now hold.

When immediate mode is the right choice

Given all these responsibilities land on you, why ever choose the canvas over the DOM? Because retained mode has a cost that immediate mode doesn't: the browser must store, lay out, and manage every retained object. A DOM tree with 10,000 nodes is slow — each node carries style, layout, event, and memory overhead. But drawing 10,000 shapes on a canvas is just 10,000 paint commands into one bitmap, with no per-shape object kept around at all.

So the tradeoff is clean: retained mode (DOM/SVG) when you have a manageable number of elements that benefit from built-in layout, events, and accessibility; immediate mode (canvas) when you have a huge number of visual elements, or need per-pixel control, and are willing to own the state and hit-testing yourself. Games, data visualizations with tens of thousands of points, image editors, particle systems, and drawing apps all live in the second world. That's the canvas's home, and immediate mode is why it's fast there.

Where this goes next

If the canvas is "just a bitmap you paint into," the next question is literally what is that bitmap — how big is it in real device pixels, how do its coordinates map to the CSS size on screen, and why does canvas art so often come out blurry until you account for the device pixel ratio. The pixel backing store takes apart the surface itself: the raw pixel buffer every command in this lesson was painting into.