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

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

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 three renderer families raise DeviceLost from their real error paths at TARGET; a fifth, WebGPU, raises it only from its debug hooks.

Identifier

CNA-BUG-224

Category

Bug

Subsystem

Documentation & release tooling

Status

Open

Verified against

CNA c1c316b9 (c1c316b9c7a846ce8002809c151fcd1af14942c9)

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 three families: DirectX 9, DirectX 11 (DirectX11Renderer::CheckDeviceRemoved) 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 only; DirectX 11 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/webgpu/src/WebGPURenderer.cpp — WebGPURenderer::DebugSimulateContextLoss and DebugRestoreContext; OnDeviceLost only logs
• modules/renderers/directx9/src/DirectX9Renderer.cpp — DirectX9Renderer raises Lost, Resetting and Reset through deviceEventCallback_ around its real device-reset recovery

Evidence

Checked by reading at c1c316b9; not executed. The four 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.