CNA-BUG-261: Comments and docs say GpuDrawParams::specularEnabled is read by no renderer and DIRECTX9's specular variants are blocked, but D3D9EffectDraw and Fna3dDraw read it

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

IGraphicsRenderer.hpp says no renderer reads GpuDrawParams::specularEnabled, and two DirectX9 headers and docs/directx9-renderer.md call the specular and per-pixel-lighting variants unreachable, although DIRECTX9 and FNA3D read the fields.

Identifier

CNA-BUG-261

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

None

Affected contract

GpuDrawParams::specularEnabled and preferPerPixelLighting (IGraphicsRenderer.hpp) and the DIRECTX9 shader-dispatch documentation

Expected behaviour

Comments and renderer documents describe the code. After plans/plan_dx9.md's D9-81 resolution of 2026-07-16 EnvironmentMapEffect forwards specularEnabled in GpuDrawParams and the renderers use it to pick the shader variant.

Actual behaviour at TARGET

The GpuDrawParams::specularEnabled comment in IGraphicsRenderer.hpp ends “No renderer currently reads this field”; D3D9ShaderDispatch.hpp says the value “is not forwarded through GpuDrawParams today”; DirectX9Renderer.hpp says only the eight non-specular EnvironmentMapEffect ShaderIndex values are reachable; and docs/directx9-renderer.md lists the specular variants and PreferPerPixelLighting as blocked on a GpuDrawParams gap. In the code, D3D9EffectDraw.cpp passes params.specularEnabled to ComputeEnvironmentMapEffectShaderIndex (its own comment says all 16 indices are reachable) and params.preferPerPixelLighting to the skinned and basic index functions, and Fna3dDraw.cpp passes params.specularEnabled to the FNA3D environment-map shader index.

Source locations

• modules/graphics/include/CNA/Internal/Renderers/Common/IGraphicsRenderer.hpp — GpuDrawParams::specularEnabled comment
• modules/renderers/directx9/include/CNA/Internal/Renderers/DirectX9/D3D9ShaderDispatch.hpp — ComputeEnvironmentMapEffectShaderIndex comment
• modules/renderers/directx9/include/CNA/Internal/Renderers/DirectX9/DirectX9Renderer.hpp — DrawEnvironmentMapEffectEXT comment
• modules/renderers/directx9/src/D3D9EffectDraw.cpp — reads params.specularEnabled and params.preferPerPixelLighting
• modules/renderers/fna3d/src/Fna3dDraw.cpp — EnvironmentMap case reads params.specularEnabled
• docs/directx9-renderer.md — What's not (yet): the specular variants listed as blocked

Evidence

Read at 009d40f5: every reader of GpuDrawParams::specularEnabled and the comments that describe it, the EnvironmentMapEffect setter and fill, the DIRECTX9 and FNA3D draw paths, plans/plan_dx9.md and the renderer document; nothing executed. The libcna.com pages do not repeat the stale statement. Reported as a narrow restore by the D2 dismissal reviewer, who had confirmed that the functional claim (no renderer reads the field) is false, and re-verified by the orchestrator.

Focused reproduction

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

Regression test

Correct the four comments and the renderer document; a grep for “No renderer currently reads this field” should then find nothing.

Blast radius

Maintainers of the DIRECTX9 and shared renderer code, who would be told that the specular and per-pixel-lighting variants cannot be reached and might re-implement or avoid them. No runtime behaviour is affected.

Workaround

No workaround is known.