Chapter 19 The Renderer Contract

A public GraphicsResource owns its renderer handle, normally through unique_ptr; Texture2D uses shared_ptr. The device owns neither. It records raw GraphicsResource addresses so it can dispose registered resources before destroying the renderer. GraphicsDevice::Dispose() moves and clears that list, calls each resource’s virtual Dispose(), raises Disposing, and then releases the renderer. Re-entrant deregistration therefore does not invalidate the iteration.

The registry follows object addresses, not renderer-handle ownership. The GraphicsResource copy and default move constructors carry the device pointer without registering the destination or replacing the source address. A Texture2D copy has its own disposed flag and shares the private handle; moving buffers, textures, or render targets can leave the device tracking the moved-from value. If a surviving untracked object outlives device disposal, its renderer resource may be released after the native context.

Chapter 12, §12.8, covers event ordering and the remaining constructor/destructor gaps. Figure 14.1 summarizes the ownership relation.

Null factory results do not share one public failure policy:

Software supplies 2D targets and cube-texture storage but still inherits the null factories for volume textures, cube targets, and occlusion queries; several 2D families inherit a wider subset. D3D9 can also return null according to device capabilities. A cube or volume texture passed to ShaderEffect remains a sharp edge because its CNAEXT renderer accessor assumes that the private owner exists. Construction alone therefore does not establish usable storage. No individual capability value covers every texture and target factory.

The framework needs one consistent source-level policy—early NotSupportedException, or explicit nullable availability plus guards throughout. This book records the current behavior and does not choose or implement that policy.

GetWindowInternal() and GetRendererInternal() are pure virtual because the shared game path needs a window, even though not every family has one. The returned pointers are borrowed:

• •

  ordinary windowed families return their current SDL_Window*;

• •

  HEADLESS, SOFTWARE, and D3D12 HeadlessEXT return null;

• •

  only SDL_RENDERER returns its own SDL_Renderer*; other families normally return null for that method;

• •

  GameWindow::GetNativeSdlWindowEXT() and the integer-shaped XNA Handle property expose the same window without transferring ownership.

Do not call SDL_DestroyWindow on either result or cache it across device disposal. Explicitly disposing the game-owned device does not invalidate the separate GameWindow wrapper, so later use of that wrapper can reach a destroyed SDL object.

PresentationParameters::DeviceWindowHandle is the inverse borrowed route. A nonzero value is reinterpreted as SDL_Window*; CNA does not validate or destroy it. The pinned implementation publishes an attached window to the global mouse and text-input services and, at teardown, clears either handle only if it still names that window. An embedding host must keep the window alive through renderer teardown. The global slots still have last-writer semantics, so two live devices can replace one another’s input target; the located tests do not cover that multi-device lifecycle.

Window-to-logical input uses three tiers: an associated SDL renderer; otherwise a static SDL_Window* to IGraphicsRenderer* registry; otherwise raw coordinates. The inverse mouse-warp route uses the same ordering. The compact matrix below names the current behavioral classes; family chapters retain the implementation detail.

An immediate Mouse::SetPosition/GetState test is weak because the setter first writes the requested logical value into InputManager; that round trip can pass even if the physical warp is wrong. The strongest located public evidence injects physical SDL motion into a scaled presentation and observes the converted logical point.

The second tier is one process-wide, unsynchronized unordered_map<SDL_Window*, IGraphicsRenderer*>. Registration overwrites by key and unregistration erases by window alone; neither operation checks ownership. EasyGL registers before several fallible constructor steps, so an exception can leave a dangling value. Two devices attached to the same borrowed window create another failure: the second replaces the first, then destruction of the first removes the second’s entry. Address reuse and concurrent lookup add equivalent hazards.

This requires an ownership and thread-affinity decision in CNA. Suitable designs include an RAII registration after fallible setup, owner-checked removal, and either rejecting duplicate devices or defining multi-device routing. No located test covers constructor failure after registration, duplicate attachment, window-address reuse, or concurrent access.

The CNAEXT PresentationMode property belongs to GraphicsDeviceManager. Direct device construction leaves the renderer-create argument at its fixed-height default. The manager route applies the mode before reset so implementations that derive a virtual width see the intended value.

Portable code should configure the manager before normal initialization and use NativeBackBuffer when physical readback coordinates matter. An enum round trip is not evidence that letterbox, crop, or stretch reached output.

Public conversion preserves Immediate=0, One=1, and Two=2, but families interpret them differently. The manager’s Boolean retrace property reaches only 0 or 1; 2 requires explicit PresentationParameters. Because Game constructs its first renderer before derived-game configuration, a family that consumes only the constructor argument can remain at the default interval.

No located timing test distinguishes half refresh from ordinary VSync on any family.

Reset first asks the renderer to normalize the requested color and depth formats, then stages the result as public state. Window resizing and virtual-resolution application form a rollback block: if either throws, CNA restores the prior presentation, adapter, touch dimensions, and window size before rethrowing. MSAA, interval, and the renderer’s presentation-format update occur afterward; they are not covered by that rollback. Only D3D9 overrides the final format-update hook. A family whose applied-format query inherits the identity default can therefore echo a request even when its native attachments use a fixed format.

An SDL fullscreen failure is cleared and ignored, so IsFullScreen is a request, not an actual-state query. D3D9 has the strongest located native format evidence; most other tests prove stored-field round trips or continued rendering.

The interface promises top-left RGBA8 data and throws by default. The public wrapper checks a null destination, positive in-bounds rectangles against the stored backbuffer dimensions, and elementCount < width*height. It does not reject a negative start index, account for remaining capacity after that offset, or guard the signed area multiplication against overflow.

Renderer behavior falls into four observable classes:

There is no capability query for this distinction. A portable test must name the selected family, source image, coordinate space, and oracle.

IRenderTargetRenderer::GetMultiSampleCount() defaults to zero, while HasRealDepthBuffer(requested) defaults to echoing the request. The first is conservative; the second can claim an attachment that the family never created. SDL Renderer overrides the depth answer to false. Applied sample count and actual attachment presence are therefore stronger facts than constructor arguments.

IOcclusionQueryRenderer itself is pure virtual, but its factory is optional. IEffectRenderer requires program compile/bind/status methods while many scalar, array, and texture setters have no-op defaults. A valid program can consequently discard selected parameters. Chapter 17 owns the renderer-specific matrix.

Dynamic buffer constructors currently use the same factory as static buffers; the constructor’s dynamic flag is ignored. Update options still have meaning on EasyGL, SDL GPU, D3D9, and D3D11, which map discard/no-overwrite to distinct native operations. Vulkan and BGFX inherit the option-discarding default; WebGPU, D3D12, Software, and Headless override it without preserving option identity. The options-taking public wrappers also fail to refresh the shared CPU shadow, so a later public GetData() can throw or return stale bytes.

The declaration route is stricter: SetVertexDeclaration() is pure virtual, and raw uploads send the complete declaration. A family may translate it, remember it for draw-time validation, or reject it. Chapter 18 defines the packed-stream contract.

Effect-aware DrawPrimitivesEx defaults can discard GpuDrawParams and enter a colored draw. The exhaustive family audit found DIRECTX10 as the consequential live inherited fallback: an effect request can become a plausible untextured colored result. Several families override the method but still use a colored fallback for unmatched layouts. Appendix B classifies inherited, hybrid, and renderer-owned routes.

Instancing has a throwing default. Shared code now transports up to sixteen bindings, preserving slot, renderer buffer, stride, vertex offset, instance frequency, and count. It rejects partially overlapping semantic declarations and validates per-vertex and per-instance ranges before submission. The broad portable subset is one vertex stream plus one instance stream; multiple streams of either rate additionally require MultiStreamVertexInput. EasyGL profiles with native support, Magnum, Vulkan, BGFX, WebGPU, and D3D11/12 have focused pixel evidence for specific layouts. D3D9 has a native step-frequency route but weaker shared-oracle coverage. Headless records counts, and SDL GPU inherits a default-true capability despite the throwing callback; neither establishes working instancing.

Every current 2D texture implementation overrides level-zero updates. The higher-mip default is still reachable on SDL GPU and silently discards the upload; Software explicitly discards higher levels, while SDL Renderer, Canvas, and free-direct throw. EasyGL, Vulkan, BGFX, WebGPU, and D3D9/11/12 implement higher-level storage. GPU-sampled or native-subresource tests, not public CPU-shadow round trips, establish those paths. WebGPU additionally regenerates the mip chain after level-zero writes, which can overwrite previously authored higher levels.

Volume and cube readback now returns a completion Boolean. Public wrappers convert results only after a true response; null/false raises NotSupportedException without modifying the destination. EasyGL, Vulkan, BGFX (when transfer capabilities exist), WebGPU, SDL GPU, D3D9/11/12, and LLGL have native transfer routes. Skia and selected Software cube paths use exact CPU storage. Headless refuses instead of manufacturing transparent pixels. The shared fixtures distinguish slices, faces, subrectangles, mips, and unchanged sentinel buffers.

RenderTargetCube inherits public texture upload methods, but most renderer-target objects explicitly refuse them; EasyGL and Skia are the notable storage implementations. Target transitions are a separate concern. Families with deferred work must finalize the outgoing face before another cube face, 2D target, MRT set, or backbuffer becomes active. D3D9/11/12, BGFX, WebGPU, SDL GPU, LLGL, and Vulkan have renderer-owned transition mechanisms. EasyGL retains per-face MSAA storage, but switching faces on the same cube can skip outgoing finalization; callers that need freshly resolved/sampleable faces should unbind between them.

Singular 2D and cube calls normalize into one descriptor list. Each descriptor names a 2D target or cube face, dimensions, and applied sample count. The first descriptor controls viewport, scissor, discard clearing, and usage policy. The shared layer rejects null/disposed targets, nonzero 2D slices, dimension or sample-count mismatches, duplicate subresources, and unsupported mixed/cube MRT shapes before native binding.

Three rules are cross-family:

1. 1.

   CNA has no FNA-style redundant-binding early return. Rebinding the same discard target clears it again and can repeat resolve/finalization work.

2. 2.

   PreserveContents and PlatformContents both pass the preserve Boolean; exact DiscardContents triggers the shared implicit clear.

3. 3.

   The discard mask includes color and each depth/stencil aspect the first descriptor reports as present. Backbuffer usage is outside this policy.

Focused fixtures distinguish discard from preserve/platform for major GPU families, including cube and depth/stencil cases. Software has CPU color, depth, and stencil storage; Headless reports trace changes, not preserved pixels. WebGPU and Software explicitly reject more than one target. D3D12 binds multiple RTVs, but current stock draws write target zero. A true MRT capability answer must therefore be paired with a successful multi-target bind and an oracle for the intended outputs.

GraphicsDevice converts color once, masks unavailable target aspects, and dispatches one of seven non-empty target/depth/stencil combinations. The significant remaining differences are concise:

• •

  Vulkan, BGFX, WebGPU, and SDL GPU preserve ordered clears across deferred pass segments; focused pixel suites cover masks, chronology, and several target kinds.

• •

  D3D11/12 issue native immediate clears. D3D9 further gates depth/stencil bits using its backbuffer format, even when a differently formatted target is active.

• •

  EasyGL’s color-only hook also includes the GL depth bit without forcing depth writes, so prior depth-mask state can change a nominal target-only clear.

• •

  SDL Renderer, Canvas, and free-direct mask depth/stencil away on their public 2D paths; their direct 3D hooks may throw but are not reached by the masked public call.

• •

  Software handles color, depth, and stencil in CPU arrays; Headless records trace identity without attachment semantics.

There is no capability value for aspect selectivity or same-pass ordering. Tests must observe the requested aspect after intervening work; an unchanged color pixel alone does not prove that a depth-only clear occurred.

The device calls each renderer hook before committing the corresponding public property, and scissor enable arrives separately through RasterizerState. A successful getter round trip therefore establishes accepted bookkeeping, not rasterization.

Vulkan, BGFX, WebGPU, and SDL GPU capture viewport/scissor per deferred command and have focused pixel evidence. EasyGL and D3D9/11 apply both through native state; EasyGL SpriteBatch resets the viewport to the full destination and does not restore it. D3D12 applies custom viewport and depth range but installs a full-target scissor on every draw. SDL Renderer applies a nonempty clip rectangle regardless of ScissorTestEnable and has no viewport hook. Software applies the rectangle and enable state to its 2D and 3D clip paths; its custom viewport is covered for SpriteBatch, while the 3D NDC mapping still spans the full framebuffer. Canvas, free-direct, and historical ASCII do not implement both semantics. Headless validates/traces but does not rasterize.

Target switches reset viewport and scissor to destination bounds. Construction establishes both full rectangles. Present and a same-size reset preserve custom values; a logical-size or physical default-viewport change resets both. No capability value reports either feature.

SetContextRecoveryEnabled() changes shared texture-shadow policy before invoking the renderer hook. Disabling it permits a successful full upload to discard CPU pixels, so later readback or a partial update can fail even when the family hook is empty. Re-enabling recovery does not reconstruct discarded data. Call it after device construction but before loading resources; the header’s “before device initialization” wording cannot be literal because the method belongs to an existing device.

F9 and F10 key-down events pass through input first, then call renderer loss/restore hooks. EasyGL uses them for desktop or browser context-loss routes. D3D9 exposes a staged lost/reset lifecycle with event and pixel coverage. Other audited families generally inherit no-ops. SetStringMarkerEXT() is also a no-op by default; Vulkan can queue a debug-utils marker when the extension function exists, while D3D9 throws. Successful submission is not proof that a native marker was emitted.