Graphics backends

CNA snapshot 3b43bd86  ·  Development › Graphics internals  ·  source links pinned to 3b43bd86

CNA declares 10 public renderer identities at this snapshot, implemented by 8 families under modules/renderers (plus one shared helper directory, common/mojoshader, added only when a selected family needs MojoShader). An identity in the registry is evidence of selectable wiring, not of feature completeness. This page is the family map for maintainers: where each family lives, what its descriptor asks of the platform, what gates its build, and which families have a source tour in the Development area.

Start with an implementation, not an identity name

A bug report names an identity; the code to read is a family. Three identities share EasyGL, so the mapping is not one-to-one. The identity-to-accessor table with C ABI values is generated on Selection axes: renderer identities; the tables below are the family-first view. “Window” is the descriptor's RendererWindowKind and the platform service it requests; maturity is CNA's own declaration in GraphicsRendererMaturity.hpp, not a measurement.

Families with an internals page

These five families have source tours that identify what the code at this snapshot executes and where its tests stop. A tour is not a parity certificate.

Families without an internals page yet

For these three families the Development area has no source tour. What is known about them from the source at this snapshot is on the user-level pages linked in the last column; start there, then read the family directory directly.

The window kinds and services above come from each family's *RendererDescriptor.cpp; platform gates from cmake/RendererSelection.cmake and cmake/RendererCombinations.cmake; the two SDL3-only families (sdl-gpu, fna3d) set the REQUIRES_PLATFORM SDL3 target property in their own CMakeLists.txt. Capability answers per identity are in the capability matrix and are not repeated here.

Contract notes for FNA3D

FNA3D has no source tour yet. The notes below were checked by reading the TARGET source at 3b43bd86 (not executed) and name what a maintainer is most likely to break.

FNA3D: native handles outlive the draw, targets finalise on unbind

FNA3D is one CNA identity even though the library picks its own driver at run time; the driver is an implementation detail, pinned in tests with FNA3D_FORCE_DRIVER (Tutorial 108). Every wrapper in Fna3dResources.cpp (textures, render targets and their renderbuffers, vertex and index buffers) and every effect wrapper releases its native handle through FNA3D's own deferred-disposal queue — FNA3D_AddDisposeTexture, FNA3D_AddDisposeRenderbuffer, FNA3D_AddDisposeVertexBuffer, FNA3D_AddDisposeEffect — and only while the owning device is still live. A handle that a queued batch still references is therefore freed by FNA3D after its command stream is done with it, not at C++ destruction time. Fna3dRenderer::UnbindTargetsEXT first binds no targets, then calls FNA3D_ResolveTarget for every previously bound target that is multisampled or mipped: that call is where FNA3D resolves MSAA and builds the mip chain, so a later draw samples finished contents. A PbrEffect or SkinnedPbrEffect draw selects CNA's own compiled CnaPbrEffect or CnaSkinnedPbrEffect blob, committed beside the XNA stock effects in modules/renderers/fna3d/effects, and the stock-effect selection names the vertex inputs each needs (normal, tangent, texture coordinates, and blend indices and weights for the skinned variant) before anything is bound (Fna3dDraw.cpp). The resolve-on-unbind step lives in Fna3dResources.cpp.

How to determine actual state

1. Find the identity in cmake/RendererIdentities.cmake and its declared maturity and category in GraphicsRendererMaturity.hpp and GraphicsRendererCategory.hpp.
2. Find its arm in cna_configure_renderer_identity() (cmake/RendererSelection.cmake): host gates, dependencies, compile options; then any rule in cmake/RendererCombinations.cmake.
3. Find its row in cmake/RendererRegistry.cmake and read the family's descriptor: window kind, services, pre-window request, adapter hooks.
4. Trace the resource methods, present and resize (OnSurfaceChanged, GetDefaultViewportRect), looking for refusal branches: HandleUnsupported3DCall and Ensure3DSupported, NotYetImplemented() from NotYetImplemented.hpp (used by the DirectX 9 family), null render-target factories, and capability switches with a default: return true arm.
5. Find its focused and conformance tests in modules/renderers/<family>/examples/CMakeLists.txt and tests/, and the CI workflow that runs them on a host that really has the API (Verification: CI).

Only after all five should documentation call a feature supported. File presence alone is insufficient, and a registered test is not a passing one.

Common implementation obligations

Every family implements the same IGraphicsRenderer contract. The obligations that recur in every source tour, with the hook that carries each:

• Translate public formats, states, primitive topology and shader binding consistently: ClassifySurfaceFormatEXT and ClassifyRenderTargetFormatEXT (no classifier means Color only), the normalised state ordinals from XnaStateConversion.hpp, GpuDrawParams.
• Create resources on the required device or context thread and destroy them before that device or context. EasyGL, the only family that returns a lease from AcquireThreadContextLeaseEXT, serialises cross-thread work through it; a family whose resource objects can outlive it (retained ITextureRenderer copies, compiled effects) must release their native handles and detach them in its own destructor, as SDL_GPU does (SdlGpuRenderer.cpp).
• Separate logical window size from drawable pixel size: RendererSurfaceInfo carries drawableSize and displayScale; GetViewportSize() is logical, GetDefaultViewportRect() physical.
• Handle zero-sized or minimised surfaces without presenting invalid extents (SDL_GPU, for example, clamps the drawable size to zero in OnSurfaceChanged and, when a minimised window acquires no swapchain texture, still submits the frame but presents nothing).
• Keep render-target and back-buffer transitions and coordinate conventions consistent: SetRenderTargets(nullptr, 0) returns to the back buffer; EasyGL stores render targets bottom-up and corrects for it when sampling and reading back.
• Report unsupported capabilities honestly rather than silently succeeding: answer SupportsCapability without a permissive default arm, return false from EXT hooks, and refuse 3D work through Ensure3DSupported or HandleUnsupported3DCall (which honours Unsupported3DGraphicsCallBehavior).

Contract comments that lag the code

The renderer headers carry many design notes, and most of them are accurate. A few, read at 3b43bd86, describe an earlier state. A maintainer should trust the code over these comments:

• SetDepthTestEnabled. The @note in IGraphicsRenderer.hpp says only EasyGL honours the toggle and that other renderers throw on first 3D use. The method is pure virtual, like SetDepthWriteEnabled, so every family defines it (the blend toggle is not a renderer virtual at this snapshot: GraphicsDevice::SetBlendEnabled installs a BlendState equation itself, the fix for CNA-DEMOS-ISSUE-066, which CNA’s repair matrix records as validated on a complete checkpoint): EasyGL, DirectX 9 and FNA3D apply it to the native depth state, SDL_GPU, WebGPU and Software store it for their draw paths, Headless counts and traces it, and only Stub ignores it.
• The DirectX 9 default list. DirectX9Renderer.hpp says CreateOcclusionQuery and CreateTexture3D are "left un-overridden here on purpose", yet the same header overrides both. The principle stated in that comment still holds, and every family follows it: "inheriting 'throws' is fine, only inheriting silence is the trap".
• Where FNA3D's stock effects come from. The CNA_RENDERER_FNA3D comment in RendererSelection.cmake says the stock-effect blobs are fetched from a pinned FNA checkout. ThirdPartyFNA3D.cmake declares a single fetch, of FNA3D itself, and states that modules/renderers/fna3d/effects holds the binaries. Those binaries are committed, with their provenance in that directory's README.
• The split depth/stencil queries. The documentation of HasRealBackBufferDepthBuffer motivates the split with a graphics API that CNA does not ship, and the neighbouring SupportsStencilBuffer comment says that no renderer in the tree answers SupportsDepthBuffer and SupportsStencilBuffer differently today. That is out of date: SDL_GPU answers depth from the depth format it created and stencil only when that format has a stencil plane (SdlGpuRenderer.hpp), so a depth-only back buffer reports depth without stencil. The comment's reason for keeping the split still stands: the single-argument Clear(Color) must keep an available depth clear and leave out a stencil plane that does not exist.

Validation by backend

Use the API's own validation where the family wires it, but keep it supplementary to CNA's conformance tests:

Run window and GPU tests through tools/platform/run_gpu_tests_private.sh: it starts a private headless Weston plus a rootful Xwayland with DRI3 on the real GPU, points DISPLAY and WAYLAND_DISPLAY at them, and runs ctest (or one command with --exec), so nothing appears on the desktop; it exits 77 when no compositor is available and refuses a build tree that forces its own test display. Compare a second family to separate a shared-layer bug from one translation layer.

What these pages do not establish

This page routes; it is not a renderer-parity certificate. The Development area has source tours for 5 of the 8 families; the other 3 are listed above with the user-level sections that describe them. There is no feature-by-feature evidence matrix for all 10 identities here: capability answers are code-derived, test registrations are not results, and the Windows paths (DIRECTX9 through DXVK, SDL_GPU on SDL's Direct3D 12 driver through vkd3d-proton) are chiefly exercised under Wine and in CI lanes that were not examined for this page. Before a risky change, inspect the chosen family's build wiring, tests and a host that can actually run it.

Read in this order

1. RendererIdentities.cmake and RendererRegistry.cmake: the 10 identities and the 8 families behind them.
2. modules/renderers: one family directory, its CMakeLists.txt, src/*RendererDescriptor.cpp and examples/CMakeLists.txt.
3. IGraphicsRenderer.hpp: the contract and its defaults, before reading any override.
4. GlStockShaderSources.hpp and GlPresentationSurfaceState.hpp: EasyGL's single GLSL ES 3.00 stock-shader corpus (adapted per profile) and its presentation transform, before reading a GL draw or present path.
5. run_gpu_tests_private.sh: how GPU tests are run without touching the desktop.