OptionalantialiasRequest multisampled anti-aliasing (§45). A hint: a backend that cannot honour it reports so through RendererCapabilities, and never fails initialization over it.
OptionalcanvasThe surface to draw into.
Deliberately typed unknown, not HTMLCanvasElement | OffscreenCanvas
(decision, WP-3.4). This package compiles with no DOM lib: @fourjs/render
is the backend-independent layer and must be usable — and type-checkable —
in Node, in a worker, and in a headless test, where those DOM types do not
exist. Naming them here would drag lib.dom into every consumer of the
logical renderer interface, which is the dependency §61 forbids in
spirit.
Each backend narrows it at the point where it can actually validate it:
the WebGL 2 backend (WP-3.5) accepts a canvas and fails with
RENDERER_INITIALIZATION_FAILED (§89) if what it got is not one. The type
is therefore unknown rather than any on purpose — an implementation
must narrow before touching it, so the check cannot be skipped by accident.
Absent means the backend supplies or needs no surface, which is the headless case.
Optionalcapabilities§62's required/optional capability declaration (WP-R1.9) — see
RendererCapabilityDeclaration for the selection rule and the
tri-state honesty rule. Validated per §85 before anything is constructed;
an unknown name, a non-array half, or a name declared in both halves is
refused with a RangeError at the resolve call, never discovered as a
capability that silently matched nothing.
OptionalonCalled once per declared capability a tried backend did not answer true
(WP-R1.9): for every required shortfall of a backend "auto" skips —
beside its RendererResolveOptions.onFallback report — and for
every optional shortfall of the backend actually selected, whichever
way it was selected. Required shortfalls of an explicitly named backend
are thrown rather than reported, RendererResolveOptions.onFallback's
rule. A throwing listener propagates — this is the application's own code.
OptionalonCalled once per backend "auto" skips, in the order they were tried
(§62's diagnostics event; see the module header for why it is a callback).
Never called for an explicit selection: naming a backend means it must work, so its failure is thrown rather than reported. A throwing listener propagates — this is the application's own code.
OptionalstencilRequest a stencil buffer on the drawing surface (§67, R-7); false by
default.
§57's Material.stencil describes a stencil test; this is the buffer that
test reads and writes. The two are separate because they are separately
costly: a material's stencil state costs nothing until a draw uses it,
while the buffer is memory the surface carries for its lifetime and a
clear every view issues — so a renderer asks for it once, up front, and a
scene that never masks never pays.
A hint in §45's sense, like RendererOptions.antialias: a backend that cannot provide one still initializes and still draws, with masking materials drawing unmasked rather than not at all (§61 forbids failing a frame over render state).
Masking into an off-screen surface asks the render target instead —
RenderTargetOptions.stencil — and leaves this false.
RendererOptions plus the §62 fallback report — what resolveRenderer takes, and what it forwards to both RendererRegistration.create and Renderer.initialize.