CNA-BUG-215: GraphicsRendererSelection::IsLatched() is documented to latch when the first GraphicsDevice begins construction; it latches only on successful resolution

CNA snapshot 009d40f5  ·  Known Issues › Current bugs  ·  source links pinned to 009d40f5

The header comment on IsLatched() says the selection latches when the first GraphicsDevice begins construction, but GraphicsDevice::resolveRenderer latches only after a renderer has been created, so a resolution that fails before any renderer exists leaves the choice open. (A constructor that fails after resolution has already latched: CNA-BUG-095.)

Identifier

CNA-BUG-215

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA 009d40f5 (009d40f5dd085c4e674d3479675fac84b12b3e0a)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

CNA::GraphicsRendererSelection::IsLatched() as documented in CNA/GraphicsRendererSelection.hpp

Expected behaviour

The implemented and intended rule, stated in the design note beside the latch call (RTR-P5-18) and in the C header's wording for cna_graphics_renderer_get_is_latched_ext ("once a renderer has been created"): the selection latches when a renderer has been successfully created, so a game whose GraphicsDevice resolution fails can reconfigure and try again.

Actual behaviour at TARGET

The Doxygen comment on IsLatched() in GraphicsRendererSelection.hpp says it "becomes true when the first GraphicsDevice begins construction"; its @brief, "Whether the selection can still be changed", is also inverted for a function that returns true once latched. GraphicsDevice::resolveRenderer in GraphicsDevice.cpp calls GraphicsRendererSelectionAccessEXT::Latch, the only production latch site, only after a candidate renderer has been created, and its comment explains that latching up front was the first design and was wrong. A reader of the header would conclude that a resolution that failed before creating any renderer froze the selection; it did not.

Source locations

• modules/core/include/CNA/GraphicsRendererSelection.hpp — the IsLatched() comment
• modules/graphics/src/Xna/GraphicsDevice.cpp — GraphicsDevice::resolveRenderer: Latch at the end of a successful resolution
• modules/core/src/GraphicsRendererSelection.cpp — GraphicsRendererSelectionAccessEXT::Latch
• modules/graphics/tests/CNA/GraphicsRendererFallbackTests.cpp — GraphicsRendererFallbackTest.AFailedResolutionDoesNotLatch pins the implemented rule

Evidence

Checked by reading at 009d40f5; nothing was built or executed for this entry. The contradiction is between the header comment and the single Latch call site; the implemented rule is pinned by a test. The runtime renderer selection guide already warns that the header comment is out of date.

Independently reported as CNA-BUG-219 (folded into this entry by the adversarial audit): The IsLatched() Doxygen says the selection latches when the first GraphicsDevice begins construction; GraphicsDevice::resolveRenderer latches only after a renderer was created successfully, so a failed construction leaves the selection changeable.

Independently reported as CNA-BUG-226 (folded into this entry by the adversarial audit): The public comment on IsLatched() says the selection latches when the first GraphicsDevice begins construction, but GraphicsDevice::resolveRenderer latches only after a candidate renderer was created, and a failed resolution deliberately leaves it open.

Focused reproduction

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

Current tests

GraphicsRendererFallbackTest.AFailedResolutionDoesNotLatch in GraphicsRendererFallbackTests.cpp pins the implemented behaviour; nothing checks the documentation.

Regression test

A documentation fix; the existing test already pins the behaviour the corrected comment should describe.

Blast radius

Documentation only (header, generated API documentation, IDE tooltips): game and binding authors deciding whether a retry after a failed GraphicsDevice construction is possible. The C ABI latch route behaves like the C++ function.

Workaround

Treat IsLatched() as true only once a GraphicsDevice has been created successfully.