Tutorial 105: Browser-Native Renderers

CNA Tutorials  ·  Renderers

Alongside WEBGL1 and WEBGL2, CNA has three browser renderers that do not use WebGL at all. They draw with the browser's own 2D primitives: a Canvas 2D context, CSS-composited DOM elements, or real SVG nodes.

All three are Emscripten-only and refuse to configure for a native target with a FATAL_ERROR, because a CanvasRenderingContext2D, an HTMLDivElement and the SVG namespace only exist inside a browser. All three are 2D-only: every 3D entry point they override throws deterministically rather than silently doing nothing.

What each one puts on the page

In all three cases SDL3 still owns the real <canvas> element — it stays in the layout, hidden, because SDL keeps sizing it and delivering input through it. The DOM and SVG renderers create their own surface over the top of it.

The decisive difference: backbuffer readback

The workaround is the same on both: render into a RenderTarget2D and read that. Render targets on both renderers are backed by a real off-screen canvas, so their readback is a genuine getImageData. If your game takes screenshots, runs a pixel-comparison test, or samples the frame for any reason, plan for that indirection — or choose CANVAS.

Performance shapes, not a ranking

HTML_DOM exists because CSS transform and opacity are compositor-only properties: a frame in which sprites merely move triggers no layout and no repaint. Sprite n of a frame always lands on pool element n, each element caches its last applied style values, and a whole batch crosses the WebAssembly-to-JavaScript boundary in one call. A frame in which nothing changes performs zero CSS property writes.

The cost sits somewhere else entirely:

The rule of thumb: HTML_DOM rewards static sprite sheets and moving sprites, and punishes dynamic pixel data. If your game calls Texture2D::SetData every frame on a texture it also draws, use CANVAS or a WebGL profile instead.

The one live capability query in CNA

HTML_DOM and SVG_DOM report false for every GraphicsCapability except one. AdditiveBlending is answered by asking the running browser, once, whether it supports the CSS value these renderers map BlendState::Additive onto:

// Answers from a memoised CSS.supports('mix-blend-mode', 'plus-lighter')
if (device.SupportsCapability(CNA::GraphicsCapability::AdditiveBlending))
    DrawGlowPass();
else
    DrawGlowFallback();

That matters because of what happens otherwise:

Every other blend behaviour on these renderers fails loudly instead: only the four standard presets exist in CSS compositing, so any custom BlendState throws, as does a non-default ColorWriteChannels or MultiSampleMask.

A real divergence worth knowing

For NonPremultiplied and Additive, XNA's own blend equation squares the source alpha's contribution to the result alpha. CSS compositing has no per-channel blend-factor model that can reproduce that. The consequence is precise and bounded:

• Colour channels are always exact on both renderers.
• The alpha channel is exact only when the source is fully opaque, where the squared and unsquared formulas coincide.

You will never see this drawing opaque sprites to the screen. You will see it if you draw translucent content into a RenderTarget2D and read the raw RGBA back. It is a documented architectural limit, measured against real translucent data rather than assumed.

Where SVG_DOM differs

SVG_DOM shares the DOM renderers' shape but draws a narrower boundary in one place: an out-of-bounds source rectangle under TextureAddressMode::Clamp, and mixed per-axis addressing, both throw. Wrap and symmetric Mirror work through a <pattern> fill. HTML_DOM handles the Clamp overflow case with a cached edge-extended texture variant; SVG_DOM has not built that yet and refuses rather than cropping silently.

What SVG_DOM gives you in exchange is a genuinely vector output tree: real, inspectable SVG nodes with real clip paths, which is useful when the page itself is the artefact.

How much of this is actually exercised in a browser

That difference is worth respecting when choosing. HTML_DOM is the browser renderer whose behaviour is continuously re-checked against a real engine.

Three traps that apply to all three

There is no save persistence on the web. SDL_GetPrefPath under Emscripten resolves to volatile MEMFS; CNA mounts no IDBFS and never calls FS.syncfs. Every save is silently discarded on page reload.

There is no video. The video translation units are excluded from web builds, so Video and VideoPlayer compile against their still-present headers and then fail to link.

Building

emcmake cmake -S . -B build-canvas  -DCNA_GRAPHICS_RENDERER=CANVAS
emcmake cmake -S . -B build-htmldom -DCNA_GRAPHICS_RENDERER=HTML_DOM
emcmake cmake -S . -B build-svgdom  -DCNA_GRAPHICS_RENDERER=SVG_DOM

cmake --build build-htmldom -j3

# Drive the HTML_DOM browser suite in headless Chromium
scripts/run-htmldom-test-suite.sh build-htmldom

Choosing between them

Where to go next

• Tutorial 81: Building for the Web
• Tutorial 102: The OpenGL family
• Tutorial 106: 2D vector renderers
• Tutorial 101: Querying renderer capabilities