Chapter 12 GraphicsDevice and the Rendering Pipeline

The private construction path is observable through its ordering:

1. 1.

   Initialize SDL video unless the compiled or requested path is windowless.

2. 2.

   Create a window, attach a caller-owned DeviceWindowHandle, or retain null. Both CNA-owned and attached windows are published to mouse and text-input services.

3. 3.

   Apply SDL window size/fullscreen state.

4. 4.

   Build GraphicsRendererCreateArgs and call the selected family factory.

5. 5.

   Normalize reported backbuffer/depth formats, query the renderer’s logical and physical viewport, and apply initial blend, depth/stencil, and rasterizer state.

An attached window is borrowed: CNA clears matching input handles at teardown but destroys the window only when ownsWindow_ is true. Chapter 19, §19.1.3, covers the remaining native-handle rules.

Both setters first ask the renderer to apply the value and then retain public state according to the individual setter’s success path. Scissor enable is a separate RasterizerState::ScissorTestEnable value. A useful test therefore draws across the boundary; property round trips alone are insufficient.

Three lifecycle rules define when CNA replaces custom rectangles:

• •

  Construction initializes the full logical viewport. Current resize handling also sets the scissor to full bounds after an actual logical or physical-viewport change.

• •

  Present() preserves custom state while the renderer’s logical size and physical default rectangle remain unchanged.

• •

  Every 2D, cube, MRT, or backbuffer target switch resets both to the first destination’s full bounds, even for a redundant binding.

Renderers may use a physical default viewport distinct from the logical public dimensions for letterbox or overscan. Chapter 19, §19.4.3, records draw-time coverage and exceptions.

ClearOptions is the bitwise combination of Target, DepthBuffer, and Stencil. Shared code validates a requested depth value, independently asks whether the active 2D/cube target or backbuffer has depth and stencil, masks only absent aspects, and selects one of seven non-empty renderer methods. A depth/stencil-only clear on an attachment with neither becomes a no-op, matching current FNA.

This independent aspect query is important for Depth16/Depth24 versus Depth24Stencil8 and for families with a standalone stencil plane. Family-specific ordering and remaining defects—notably EasyGL’s color-hook/depth coupling and D3D9’s additional backbuffer-format gate—are in §19.4.2.

All four reset overloads end in Reset(const PresentationParameters&, GraphicsAdapter*). The order is public behavior:

1. 1.

   Raise DeviceResetting; handlers still see the old adapter and parameters.

2. 2.

   Clone the request, normalize the renderer’s applied color/depth formats, store the adapter and logical size, and update touch dimensions.

3. 3.

   Apply window state and virtual resolution inside a rollback guard. A failure restores public presentation state, adapter, logical size, touch dimensions, and attempts to restore the former window state before rethrowing the original diagnostic.

4. 4.

   Apply/clamp MSAA and write the applied count back; forward swap interval and the presentation-format update hook.

5. 5.

   Refresh viewport/scissor and raise DeviceReset.

The rollback guard ends before MSAA, interval, and format hooks. A later exception can therefore leave earlier work applied and suppress DeviceReset. Successful completion establishes the shared route, not that a compositor accepted fullscreen or an interval request. Applied presentation values are stronger than the original request but still depend on each family’s truthful reporting; see §19.2.5 and §19.2.4.

FNA stores the new state before its resetting event and performs one FNA3D backbuffer reset, so event observations and native transaction shape differ.

A game-attached GraphicsDeviceManager registers the manager and device-service interfaces but does not own the game device. Initial CreateDevice() raises PreparingDeviceSettings, resets the existing device, subscribes to later device reset events, and then raises DeviceCreated. The initial settle-in reset is intentionally not forwarded as a manager reset pair. Subsequent ApplyChanges() reaches device reset; the manager forwards the device’s events once.

Edits made in PreparingDeviceSettings apply to that candidate only and are not copied back into preferred fields. The callback must retain a non-null adapter and must not re-enter ApplyChanges. Listener exceptions propagate and can interrupt the staged operation.

The manager subscribes to GameWindow::ClientSizeChanged with a lambda capturing raw this, discards the removal token, and removes only service registrations on disposal. Destroying or replacing a manager while its game window remains live can therefore leave a dangling resize callback. Normal member lifetime avoids a later resize during base destruction, but that ordering is not a general ownership guarantee.

Manager disposal raises DeviceDisposing even though it does not delete a game-owned device; Game uses that notification for UnloadContent. The disposed flag is set after the Disposed event, so a re-entrant or throwing listener remains another source-proven lifecycle hole.

Each public binding becomes a descriptor naming a 2D target or cube face, dimensions, and the renderer-applied sample count. The shared route enforces:

• •

  at most four bindings, with D3D9’s Reach profile narrowed to one;

• •

  non-null, non-disposed targets with a usable private renderer;

• •

  valid cube faces and zero for unsupported 2D array slices;

• •

  equal dimensions and applied sample counts;

• •

  no duplicate subresource, while distinct faces of one cube remain legal.

Native binding must succeed before public bindings and viewport/scissor are committed. CNA has no redundant-binding early return: rebinding the same target reaches the renderer, resets rectangles, and clears a DiscardContents destination again. Preserve and Platform usage retain content; discard requests a black clear of color and each reported depth/stencil aspect. The API does not guarantee that discarded content later reads as black.

The complete example is retained at tools/cna-screenshot-infra/rendertarget_roundtrip_demo.cpp. This excerpt shows the public sequence; it is adapted from that executable, with setup and triangle data omitted:

The readback probe is intentionally marked renderer-specific: some families read the active target, some always read the backbuffer, Headless synthesizes state, and others throw. Portable target verification uses RenderTarget2D::GetData where that family supports it.

The public call accepts up to four RenderTargetBinding entries. That shape does not establish that one draw writes all attachments. WebGPU rejects MRT; Software’s current route does not provide a portable multi-output stock-effect contract; diagnostic renderers may record only logical state. D3D12 can bind several RTVs while stock draws still target slot zero. Use MultipleRenderTargets as an initial query, then require a successful bind and a shader and pixel oracle that distinguish every output. Chapter 19, §19.4.1, owns the current qualifications.

Current CNA no longer forwards only one instance buffer. The same FillVertexStreamBindings() helper serves ordinary and instanced draws and copies up to sixteen slot-aligned descriptions into GpuDrawParams: renderer handle, declaration, stride, element offset, instance frequency, and count. Instanced validation applies the caller’s base vertex only to per-vertex streams and computes each instance stream’s required records as $1+\lfloor (n-1)/f\rfloor$.

Families still differ in accepted layouts and native divisor support. The complete current boundary is §19.3.2; a compile-successful two-stream call is not a portable arbitrary-effect claim.

Every shared draw starts World/View/Projection at identity, then uses dynamic_cast<const IEffectMatrices*> on the applied effect. Stock effects, ShaderEffect, and CNA’s current PBR effect implement that interface. A custom effect that deliberately omits it receives identity transforms instead of an exception; screen-space clip coordinates are a legitimate use of that fallback.

The CNAEXT PrimitiveVerts() helper converts a primitive count into the required vertex count and rejects unknown topology. It mirrors an internal FNA helper but is public in CNA.

GraphicsResource supplies device, disposed state, name, tag, event, and ToString. Its copy/move operations do not repair the device’s address registry. Texture2D is copyable and shares its renderer handle; several other resources are movable. A destination can therefore remain live but untracked after relocation. Keep live resources address-stable and within device lifetime; Chapter 19, §19.1.1, gives the ownership consequences.

getAdaptersProperty() lazily builds one adapter per SDL display and caches the owning unique_ptr vector. AdaptersChanged() destroys and rebuilds it; do not retain adapter references across that call. DefaultAdapter is the current first entry, not a separate GPU-selection service.

D3D9 is the only family whose IsProfileSupported, render-target format query, and backbuffer format query consult its native device caps. It combines profile whitelists with native format support and clamps samples per format. Other builds return true for either profile; render-target queries use a shared format list and report zero samples, while backbuffer queries select Color and zero samples. These methods therefore are not portable hardware probes.