CNA-PLAT-017: FNA3D has no occlusion queries on its SDL_GPU driver, the driver FNA3D tries first and the one it runs on Apple

CNA snapshot c1c316b9  ·  Known Issues › Platform limitations  ·  source links pinned to c1c316b9

Fna3dRenderer probes queries only on FNA3D's OpenGL and Direct3D 11 drivers; on its SDL_GPU driver (FNA3D's first choice, and its Metal route on Apple) OcclusionQuery is reported unsupported and its constructor refuses, because SDL3's GPU API has no queries.

Identifier

CNA-PLAT-017

Category

Platform limitation

Subsystem

Graphics & renderers

Status

Open

Verified against

CNA c1c316b9 (c1c316b9c7a846ce8002809c151fcd1af14942c9)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

OcclusionQuery and GraphicsCapability::OcclusionQuery on the FNA3D renderer

Expected behaviour

XNA 4.0 offers OcclusionQuery on every HiDef device. Where a backend cannot count samples, CNA's rule is to say so: the capability answers false and the constructor refuses by name rather than returning a fabricated count.

Actual behaviour at TARGET

FNA3D chooses its driver at run time in the order SDL_GPU, Direct3D 11, OpenGL (fna3d-renderer.md). At device creation Fna3dRenderer (Fna3dRenderer.cpp) probes query support with FNA3D_CreateQuery only when the chosen driver is not SDL_GPU; on the SDL_GPU driver supportsOcclusionQueries_ stays false, SupportsCapability(OcclusionQuery) answers false and Fna3dRenderer::CreateOcclusionQuery (Fna3dResources.cpp) returns no renderer, so the public OcclusionQuery constructor refuses with NotSupportedException. SDL3's GPU API has no occlusion-query commands (the same reason CNA's own SDL_GPU renderer refuses them). On Apple FNA3D runs that driver on Metal, so FNA3D has no occlusion queries there; elsewhere it has none unless FNA3D falls back to, or is pinned (FNA3D_FORCE_DRIVER) to, OpenGL or Direct3D 11.

Source locations

• modules/renderers/fna3d/src/Fna3dRenderer.cpp — device creation: the FNA3D_CreateQuery probe skipped for FNA3D_RENDERER_TYPE_SDL_GPU_EXT; SupportsCapability(OcclusionQuery)
• modules/renderers/fna3d/src/Fna3dResources.cpp — Fna3dRenderer::CreateOcclusionQuery returns null without query support
• docs/fna3d-renderer.md — driver order SDL_GPU, Direct3D 11, OpenGL; OcclusionQuery device-dependent, false for the SDL_GPU driver
• docs/apple-platforms.md — LensFlare is RENDERER_UNSUPPORTED on FNA3D's Metal driver
• modules/graphics/tests/Microsoft/Xna/Framework/Graphics/GraphicsDeviceCapabilityTests.cpp — SupportsOcclusionQuery: the FNA3D arm requires the capability to agree with the OcclusionQuery constructor (AM4-189)

Evidence

Read at c1c316b9: the probe, CreateOcclusionQuery, the capability test's FNA3D arm and CNA's FNA3D and Apple documentation; not executed. CNA's own records measured the consequence on Apple: AM4-189 found FNA3D selecting its SDL_GPU driver on Metal, where the capability is false, and the cna-samples matrix reports LensFlare as RENDERER_UNSUPPORTED on FNA3D's Metal driver (AM4-182, AM4-208). Before AM4-189 the capability answered true on every driver. CNA's registered FNA3D tests pin FNA3D_FORCE_DRIVER (OpenGL on Linux, Metal on Apple), so a default run on Linux or Windows was not observed here.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

GraphicsDeviceCapabilityTest.SupportsOcclusionQuery (GraphicsDeviceCapabilityTests.cpp) requires the FNA3D capability to match what the OcclusionQuery constructor does on a HiDef device; Fna3d_Smoke accepts either a real query or the refusal, depending on the driver.

Regression test

None needed while SDL3's GPU API has no queries; the capability test already keeps the answer truthful.

Blast radius

FNA3D games that use OcclusionQuery (lens flares, visibility culling): on Apple they cannot create one; on other platforms only when FNA3D picks, or is pinned to, its SDL_GPU driver. FNA3D's OpenGL and Direct3D 11 drivers and the other CNA renderers are unaffected.

Workaround

Check GraphicsCapability::OcclusionQuery before creating a query, or pin FNA3D to its OpenGL or Direct3D 11 driver with the FNA3D_FORCE_DRIVER hint where those drivers exist.