CNA-BUG-224: GraphicsDevice's DeviceLost documentation and device-status comments still say only Direct3D 9 reports device loss

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

The DeviceLost Doxygen says the event is never raised on desktop, and three maintainer comments say only Direct3D 9 calls the device-event callback, while five renderer families raise DeviceLost from their real error paths at TARGET; a sixth, WebGPU, raises it only from its debug hooks.

Identifier

CNA-BUG-224

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

GraphicsDevice::DeviceLost and GraphicsDevice::getGraphicsDeviceStatusProperty() documentation

Expected behaviour

The public header says when DeviceLost is raised, and the maintainer comments on the device-status path say which renderers drive it, so a game can decide whether it must handle device loss on its target renderer.

Actual behaviour at TARGET

GraphicsDevice.hpp documents DeviceLost as "Raised when the device is lost (XNA compliance; never raised on desktop)", and the comment on deviceStatus_ says "Every renderer except D3D9 never calls that callback". GraphicsDevice.cpp repeats it in createRenderer ("Nine of the ten renderers never call this") and in the comment inside getGraphicsDeviceStatusProperty; the public documentation of getGraphicsDeviceStatusProperty() itself says only "Returns the current device status." At TARGET RendererDeviceEvent::Lost is raised from real error paths by five families: DirectX 9, DirectX 11 (DirectX11Renderer::CheckDeviceRemoved), DirectX 12 (DirectX12Renderer::CheckDeviceRemovedEXT), Direct2D (Direct2DRenderer::RecreateDeviceResourcesForRecovery) and Vulkan (VulkanRenderer::CheckDeviceLostEXT on VK_ERROR_DEVICE_LOST, a desktop path). WebGPU raises it only from its DebugSimulateContextLoss hook, because its native OnDeviceLost callback only logs (CNA-GAP-064). Resetting/Reset are raised around real recovery by DirectX 9 and Direct2D; DirectX 11, DirectX 12 and WebGPU raise them only from their DebugRestoreContext hook, and Vulkan reports loss without recovery. DeviceLost is therefore raised on desktop hosts, and GraphicsDeviceStatus can become Lost on more renderers than Direct3D 9.

Source locations

• modules/graphics/include/Microsoft/Xna/Framework/Graphics/GraphicsDevice.hpp — DeviceLost documentation and the deviceStatus_ member comment
• modules/graphics/src/Xna/GraphicsDevice.cpp — createRenderer (deviceEventCallback comment) and getGraphicsDeviceStatusProperty
• modules/renderers/vulkan/src/VulkanRenderer.cpp — VulkanRenderer::CheckDeviceLostEXT raises Lost on VK_ERROR_DEVICE_LOST
• modules/renderers/directx11/src/DirectX11Renderer.cpp — DirectX11Renderer::CheckDeviceRemoved raises Lost
• modules/renderers/directx12/src/DirectX12Renderer.cpp — DirectX12Renderer::CheckDeviceRemovedEXT raises Lost
• modules/renderers/direct2d/src/Direct2DRenderer.cpp — Direct2DRenderer::RecreateDeviceResourcesForRecovery raises Lost and Reset
• modules/renderers/webgpu/src/WebGPURenderer.cpp — WebGPURenderer::DebugSimulateContextLoss and DebugRestoreContext; OnDeviceLost only logs

Evidence

Checked by reading at 009d40f5; not executed. The six raise sites are the renderers' own code; for WebGPU the event comes from the DebugSimulateContextLoss/DebugRestoreContext hooks, while the native OnDeviceLost callback only logs (its comment notes that the pinned wgpu-native delivers no callback for an application-initiated destroy). Behaviour is not affected; the public documentation and the maintainer comments are.

Focused reproduction

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

Current tests

vulkan_device_lost_contract_test.cpp and the renderers' own recovery examples exercise the events; nothing checks the header text.

Regression test

Documentation fix: state which families raise DeviceLost/DeviceReset (and that Vulkan reports loss without recovery), in GraphicsDevice.hpp and the two GraphicsDevice.cpp comments.

Blast radius

Readers of the public header and generated API reference, and maintainers of the device-loss path. A game that trusts "never raised on desktop" skips its DeviceLost handling on Vulkan or Direct3D hosts.

Workaround

Handle DeviceLost/DeviceReset on every renderer; see the device-loss section of the Development graphics architecture.