Graphics backends

CNA snapshot 009d40f5  ·  Development › Graphics internals  ·  source links pinned to 009d40f5

CNA declares 25 public renderer identities at this snapshot, implemented by 21 families under modules/renderers (plus two shared helper targets, common/d3d and common/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. Five identities share EasyGL, and GDI recompiles the Software family's sources, 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 GraphicsBackendMaturity.hpp, not a measurement.

Families with an internals page

These seven 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 fourteen 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 four SDL3-only families 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.

OPENGL4 and EasyGL: separate families, shared GL semantics

OPENGL4 is not a sixth EasyGL profile. It has its own directory, target (cna_renderer_opengl4), namespace and descriptor (OpenGL4RendererDescriptor.cpp), and it does not use the easy-gl or meta-gl siblings:

• Its own platforms. CNA's own summary lists native X11 (GLX) and Wayland (EGL), neither using SDL, and SDL3; its only dependency is the platform's GL library, plus MojoShader when the compiled-effects option is on.
• Its own context request. OpenGL4Renderer.cpp asks the platform's GL context service for a 4.1 core context (the highest core version macOS offers), then reads back what it actually got and throws, naming the granted version, if it is below 4.1 or not a core profile. Newer facilities (compute on 4.3+, indirect draw, anisotropy) are discovered at run time behind live checks.
• Its own loader. GL4Loader.hpp resolves GL 1.2+ entry points at run time under gl4_-prefixed names; pre-1.2 functions link directly against the system GL library (its CMakeLists.txt prefers the window-system-neutral OpenGL::OpenGL and falls back to OpenGL::GL). Because those global gl* symbols are real, PORTABLEGL, which defines them itself, is refused beside OPENGL4 exactly as beside the EasyGL identities.
• Its own window contract. Unlike EasyGL's descriptor, OpenGL4's requests depth, stencil and double buffering before the window exists, because a GLX visual is fixed at window creation; it uses PlatformGlContextOwner from the shared header PlatformGlRendererState.hpp, which gained IsCurrent() and EnsureCurrent() so that each of several devices does its work in its own context.

What decides what XNA means is shared with EasyGL through two headers that moved into the graphics module shortly before this snapshot:

• GlStockShaderSources.hpp — the single GLSL ES 3.00 corpus for every stock program (BasicEffect, AlphaTest, DualTexture, EnvironmentMap, Skinned, PbrEffect, SkinnedPbrEffect, SpriteBatch), moved verbatim out of EasyGLRenderer.cpp. EasyGL adapts it per profile (GLSL 3.30 core, ES 1.00, or ES 3.00 as written); OpenGL4 rewrites #version 300 es to #version 410 core with AdaptGlslEs300ForDesktopCore and compiles it in OpenGL4StockDraw.cpp. The uniform and attribute names are a contract both renderers' binders depend on; a second hand-maintained GLSL copy had drifted, which is why there is one.
• GlPresentationSurfaceState.hpp — the platform-neutral presentation transform (logical versus drawable size, NativeBackBuffer, FixedHeightDynamicWidth, Stretch, Letterbox, Overscan, window-to-logical mapping), formerly EasyGL's own class; EasyGL keeps using EasyGLSurfaceState = GlPresentationSurfaceState.

The test relationship follows the same idea. EasyGLParityCorpus.cmake, generated by generate_easygl_parity_corpus.py, lists 346 renderer-neutral EasyGL registrations whose sources are rebuilt unchanged against OPENGL4 as OpenGL4_EasyGLParity_<name> (an entry that needs a library the configuration lacks, such as the gamer-services avatar tests, is left out); OpenGL4 also registers the 32 shared parity fixtures through the same list every other parity family uses. docs/opengl4-renderer.md is CNA's own summary: CNA's records there report the OpenGL4_ CTests at 407 of 407 on Wayland (EGL) and 406 of 406 on X11 (GLX), measured on one AMD Radeon 780M under Mesa through the private GPU test wrapper, with the remaining skips classified, and state that Windows and macOS remain unvalidated. Those results were not re-run for this page. RendererCombinations.cmake has no rule against OPENGL4 beside an EasyGL identity, and none of CNA's multi-renderer CI sets contains that pair; the evidence for it is a developer record, not CI: plan_opengl4_modern_graphics.md (GL4-0006) records a build with CNA_GRAPHICS_RENDERERS="OPENGL4;OPENGLES3;OPENGL33" on Wayland whose same test binaries were run against each of the three renderers, selected at run time, on one AMD Radeon 780M under Mesa. That GL4-0006 run is the baseline, measured before any renderer change (OPENGL4 283 of 405 corpus tests passing); the plan's later table “Results after GL4-0009..GL4-0018” records a rerun of the same three-renderer build (405 of 405 on OPENGL4; on the two EasyGL profiles the plan notes that no test which passed before fails). It shows that the pair links and runs in one binary, not that any of this is a CI gate (not re-run for this page). The internals are traced on OpenGL4 renderer internals.

Contract notes for FNA3D and the 2D families

These families have no source tour yet. The notes below were checked by reading the TARGET source at 009d40f5 (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 is refused by RequirePbrShadingSupportEXT before any buffer is bound (Fna3dDraw.cpp), because the stock-effect selection has no PBR case and used to fall through to BasicEffect or SkinnedEffect.

SDL_RENDERER, DIRECT2D, GDI and FREEDIRECT

• SDL_RENDERER uploads each texture as an SDL_PIXELFORMAT_RGBA32 SDL texture and draws sprites with SDL_RenderTexture, SDL_RenderTextureRotated and SDL_RenderTextureAffine; readback is SDL_RenderReadPixels (SdlRenderer.cpp).
• DIRECT2D draws through ID2D1DeviceContext on a private Direct3D 11 device that no application code sees (hardware, with a WARP path forced by CNA_DIRECT2D_FORCE_WARP). Public RGBA bytes become tight BGRA at the boundary (CopyRgbaToTightBgra, CopyBgraToTightRgba), bitmaps are bounded by GetMaximumBitmapSize(), and a mipmapped RenderTarget2D is refused by name (Direct2DRenderer.cpp).
• GDI presents its CPU-rasterised RGBA8 frame with SetDIBitsToDevice (StretchDIBits when the presentation scales), copying the full frame by default; it copies only the dirty band when CNA_GDI_DIRTY_PRESENTATION=1 is set and the frame is unscaled and needs no repair (GdiPresentation.cpp); no OpenGL or Direct3D device is involved.
• FREEDIRECT composites Clear and every sprite into a lockable off-screen shadow backbuffer sized to the logical resolution, because the free-direct primary surface never exposes a writable pointer; Present() is one identity Blt() from it, and readback locks whichever surface is active (FreeDirectRenderer.cpp).

The contract these four share is negative: ThreeD is false, 3D factories and draws fail at a predictable seam (throw by default, warn-and-stub only where honoured) and a draw is never accepted and silently discarded. Test that contract through the public resource and the public draw route, as the shared unsupported_3d_call_behavior_test.cpp fixture does (registered as a test for SDL_RENDERER and FREEDIRECT, built but not registered for CANVAS); a unit test of an internal format or state mapper proves nothing about whether GraphicsDevice refuses the call safely.

How to determine actual state

1. Find the identity in cmake/RendererIdentities.cmake and its declared maturity and category in GraphicsBackendMaturity.hpp and GraphicsBackendCategory.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, HTML DOM and SVG DOM families; DirectX 12 keeps a private DirectX12Renderer::NotYetImplemented of the same shape), 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. GL families serialise cross-thread work through AcquireThreadContextLeaseEXT; a family whose resource objects can outlive it (shared ITextureRenderer copies) must release and disconnect them in its own destructor, as Vulkan does.
• 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 (Vulkan, for example, recreates its swapchain in OnSurfaceChanged only for a positive drawable size).
• Keep render-target and back-buffer transitions and coordinate conventions consistent: SetRenderTargets(nullptr, 0) returns to the back buffer; GL families store render targets bottom-up and correct 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 009d40f5, now 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 SetBlendEnabled and SetDepthWriteEnabled, so every family defines it. Vulkan, OpenGL4, DirectX 11 and Software store or apply the value, and DirectX11Renderer.cpp records the silent cross-renderer divergence that existed before its override.
• 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 still uses a retired renderer family as its example of a back buffer with depth but no stencil. The neighbouring SupportsStencilBuffer comment says that no renderer in the tree answers SupportsDepthBuffer and SupportsStencilBuffer differently today. That is also out of date. GDI answers depth false and stencil true for its standalone CPU stencil plane. SDL_GPU answers depth from the depth format it created and stencil only when that format has a stencil plane, 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.
• A Metal test that nothing builds. metal_spritebatch_customeffect_test.cpp is referenced by no CMake file. It asserts a custom-effect path that MetalRenderer::CreateEffectRenderer refuses at this snapshot ("Metal custom effects are disabled until the adapted renderer has passing macOS shader and pixel evidence"). It is therefore neither evidence for that path nor a regression guard for it.

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 7 of the 21 families; the other 14 are listed above with the user-level sections that describe them. There is no feature-by-feature evidence matrix for all 25 identities here: capability answers are code-derived, test registrations are not results, and several families (the Direct3D and GDI families, Metal) are chiefly exercised on hosts or under Wine and 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 25 identities and the 21 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: what the two GL families share.
5. run_gpu_tests_private.sh: how GPU tests are run without touching the desktop.