[Visual Test] Menu screenshot RMSE 0.0437 exceeds 0.015 tolerance after g_pipeline inherits alphaToCoverageEnable

[MichaelFisher1997]

Visual Test Failure

The nightly visual-test workflow (run 29078561400) regressed the menu golden-image comparison. The game launches successfully, Lavapipe renders, and screenshot.png is captured, but the pixel diff against docs/visual-test/golden/menu.png is RMSE 0.0436523, which is ~2.9x the configured VISUAL_DIFF_RMSE_TOLERANCE of 0.015.

Exact error output

The Compare against golden image step in visual-test.yml (line 99-105) exits with status 1:

Visual RMSE: 0.0436523 (tolerance 0.015)
Visual golden diff exceeds tolerance: 0.0436523 > 0.015
##[error]Process completed with exit code 1.

The build log captured by run-with-log shows two Vulkan validation errors that point at broken pipeline contracts introduced (or exposed) by commit 9feb275 "refactor: remove legacy lighting paths (#910)":

[ERROR] Vulkan validation error: vkCreateGraphicsPipelines():
  pCreateInfos[0].pMultisampleState->alphaToCoverageEnable is VK_TRUE,
  but the fragment shader doesn't declare a variable that covers
  Location 0, Component 3 (alpha channel).
  (VUID-VkGraphicsPipelineCreateInfo-alphaToCoverageEnable-08891)

[ERROR] Vulkan validation error: vkCreateGraphicsPipelines():
  pCreateInfos[0].pMultisampleState->rasterizationSamples (1)
  does not match the number of samples of the RenderPass color and/or
  depth attachment (4).
  (VUID-VkGraphicsPipelineCreateInfo-multisampledRenderToSingleSampled-06853)

Followed at runtime by image-layout violations on the offscreen swapchain image (VkImage 0x180000000018):

[ERROR] Vulkan validation error: vkQueueSubmit(): pSubmits[0] command buffer ...
  expects VkImage ... to be in layout VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
  -- instead, current layout is VK_IMAGE_LAYOUT_UNDEFINED.
[ERROR] Vulkan validation error: vkQueueSubmit(): pSubmits[0] command buffer ...
  expects VkImage ... to be in layout VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
  -- instead, current layout is VK_IMAGE_LAYOUT_PRESENT_SRC_KHR.

These are emitted under VK_LAYER_KHRONOS_validation + VK_VALIDATION_FEATURE_ENABLE_BEST_PRACTICES_EXT (configured by .github/actions/setup-lavapipe/action.yml). Lavapipe keeps executing despite the spec violations, but the G-buffer output is undefined, which is why the final post-processed menu frame no longer matches the golden capture.

Root cause

1. g_pipeline inherits alphaToCoverageEnable = VK_TRUE

modules/engine-graphics/src/vulkan/pipeline_manager.zig:280-285 builds the shared multisample state:

var multisampling = std.mem.zeroes(c.VkPipelineMultisampleStateCreateInfo);
multisampling.sType = c.VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO;
multisampling.rasterizationSamples = sample_count;

var terrain_multisampling = multisampling;
terrain_multisampling.alphaToCoverageEnable =
    if (sample_count != c.VK_SAMPLE_COUNT_1_BIT) c.VK_TRUE else c.VK_FALSE;

createTerrainPipeline then forwards &terrain_multisampling (which has alphaToCoverageEnable = VK_TRUE) as the multisampling parameter to pipeline_specialized.createTerrainPipeline.

In modules/engine-graphics/src/vulkan/pipeline_specialized.zig:130-131, the G-buffer pipeline is built by copying that struct and only overriding rasterizationSamples:

var g_multisampling = multisampling.*;          // inherits alphaToCoverageEnable = VK_TRUE
g_multisampling.rasterizationSamples = c.VK_SAMPLE_COUNT_1_BIT;

But assets/shaders/vulkan/g_pass.frag declares layout(location = 0) out vec3 outNormal; (no alpha component). Vulkan therefore rejects the pipeline with VUID-VkGraphicsPipelineCreateInfo-alphaToCoverageEnable-08891, and on Lavapipe the G-buffer pass writes an undefined alpha-driven coverage mask, corrupting SSAO/velocity inputs that downstream post-process passes sample.

2. water_pipeline sample-count mismatch with hdr_render_pass

modules/engine-graphics/src/vulkan/water_system.zig:281-387 constructs the water pipeline with rasterizationSamples = c.VK_SAMPLE_COUNT_1_BIT but is invoked from rhi_init_deinit.zig:99 with ctx.render_pass_manager.hdr_render_pass. When MSAA is on (default msaa_samples = 4 per modules/game-core/src/settings/data.zig:113), that render pass has sampleCount = 4 on its color and depth attachments (render_pass_manager.zig:129, 139), producing VUID-VkGraphicsPipelineCreateInfo-multisampledRenderToSingleSampled-06853.

Why this regresses only the menu capture

• The HomeScreen draws UI (ui.frag, ui_tex.frag) into the offscreen HDR MSAA color/depth attachments.
• The MSAA-resolved HDR target is then sampled by post-process passes (post_process_system.zig, bloom_system.zig, FXAA, etc.) and finally copied into the swapchain image via the UI swapchain render pass.
• The undefined G-buffer coverage + invalid VK_IMAGE_LAYOUT_* transitions on the offscreen image leave the swapchain contents in an inconsistent state at the moment screenshot.captureFrame issues its vkCmdCopyImageToBuffer.
• On a real GPU, hardware may "do the right thing" anyway, but Lavapipe deterministically diverges, producing the ~4.4% RMSE that the golden-image gate now rejects.

Origin of the failure

• modules/engine-graphics/src/vulkan/pipeline_specialized.zig:130 — g_multisampling = multisampling.* copy-then-override in createTerrainPipeline.
• modules/engine-graphics/src/vulkan/pipeline_manager.zig:284-285 — terrain_multisampling with alphaToCoverageEnable = VK_TRUE.
• modules/engine-graphics/src/vulkan/water_system.zig:337 — water pipeline hard-coded VK_SAMPLE_COUNT_1_BIT while bound to a 4-sample HDR render pass.

Suggested fix

A. Stop inheriting alphaToCoverageEnable for the G-buffer pipeline

modules/engine-graphics/src/vulkan/pipeline_specialized.zig:130-131

var g_multisampling = std.mem.zeroes(c.VkPipelineMultisampleStateCreateInfo);
g_multisampling.sType = c.VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO;
g_multisampling.rasterizationSamples = c.VK_SAMPLE_COUNT_1_BIT;

(alphaToCoverageEnable, sampleShadingEnable, minSampleShading, etc. all stay at the spec defaults of VK_FALSE/0.)

B. Match water pipeline sample count to the HDR render pass

Either pass the active msaa_samples through createWaterPipeline and set rasterizationSamples = getMSAASampleCountFlag(msaa_samples), or move the water pass into its own single-sample render pass before the HDR MSAA resolve. Minimal change in modules/engine-graphics/src/vulkan/water_system.zig:281:

pub fn createWaterPipeline(
    self: *WaterSystem,
    allocator: std.mem.Allocator,
    device: c.VkDevice,
    main_render_pass: c.VkRenderPass,
    msaa_samples: u8,
) !void {
    ...
    multisampling.rasterizationSamples = getMSAASampleCountFlag(msaa_samples);
    ...
}

…and update the two callers in modules/engine-graphics/src/vulkan/rhi_init_deinit.zig:99 and modules/engine-graphics/src/vulkan/rhi_frame_orchestration.zig:129 to pass ctx.options.msaa_samples.

C. Optional: also stop inheriting alphaToCoverageEnable in any other pipeline that derives from terrain_multisampling

The wireframe/selection/line pipelines share the same pipeline_info as the terrain pipeline, so they currently do not trip the validation error (they do output alpha in terrain.frag). No change required there, but if the G-buffer fix exposes other consumers of multisampling.*, prefer std.mem.zeroes + targeted field assignments over struct copies.

Verification

After applying A and B:

nix develop --command zig fmt modules/engine-graphics/src
nix develop --command zig build test
nix develop --command zig build -Doptimize=ReleaseFast

# Manual re-run of the failing CI step
nix develop .#ci-graphics --command \
  zig build run -Dscreenshot-path=screenshot.png -Dskip-present=true
magick compare -metric RMSE docs/visual-test/golden/menu.png screenshot.png visual-diff.png

The expected RMSE should drop below the 0.015 tolerance configured via VISUAL_DIFF_RMSE_TOLERANCE in .github/workflows/visual-test.yml:105, and the VK_LAYER_KHRONOS_validation log should no longer report alphaToCoverageEnable-08891 or multisampledRenderToSingleSampled-06853 for the home-screen capture path.

Related

• CI run: https://github.com/OpenStaticFish/ZigCraft/actions/runs/29078561400
• Previous (also failing) run with same validation errors: https://github.com/OpenStaticFish/ZigCraft/actions/runs/29003611574
• Likely-introducing PR: refactor: remove legacy lighting paths #910 ("refactor: remove legacy lighting paths")

[github-actions]

Thanks for the thorough report — I walked through every file/line referenced and the analysis matches the tree on dev. Two concrete bugs, well-scoped, and the suggested fixes are correct.

Validation summary

#	Claim	Verified at
1	g_multisampling inherits alphaToCoverageEnable = VK_TRUE	modules/engine-graphics/src/vulkan/pipeline_specialized.zig:130-131 copies multisampling.* from pipeline_manager.zig:280-285 and only overrides rasterizationSamples
2	g_pass.frag has no alpha output	assets/shaders/vulkan/g_pass.frag:14 → layout(location = 0) out vec3 outNormal; (no out vec4, so location 0 component 3 is undefined → VUID-…-alphaToCoverageEnable-08891 fires)
3	Water pipeline hard-codes VK_SAMPLE_COUNT_1_BIT	modules/engine-graphics/src/vulkan/water_system.zig:337
4	HDR render pass attachments use sample_count = 4	render_pass_manager.zig:129,139 (hdr_format color + depth .samples = sample_count when msaa_samples > 1; default msaa_samples = 4 in modules/game-core/src/settings/data.zig:113) → VUID-…-multisampledRenderToSingleSampled-06853
5	Both call sites pass hdr_render_pass	rhi_init_deinit.zig:99 and rhi_frame_orchestration.zig:129 confirmed

No related open issues. PR #910 ("refactor: remove legacy lighting paths") is the plausible introducer; CI runs 29078561400 and 29003611574 both show the same pair of validation errors, which is consistent with a real regression rather than a flaky Lavapipe capture.

Scope assessment

This is two independent, well-scoped bugs that happen to share one symptom (Lavapipe golden RMSE blow-up). I would recommend splitting them into two PRs so that the G-buffer fix isn't blocked by the water fix (or vice versa) and so the bisect log stays clean:

PR 1 — G-buffer pipeline ("fix: zero-initialize G-buffer multisample state")

• modules/engine-graphics/src/vulkan/pipeline_specialized.zig:130-131: replace var g_multisampling = multisampling.*; with std.mem.zeroes(c.VkPipelineMultisampleStateCreateInfo) + .sType + .rasterizationSamples = VK_SAMPLE_COUNT_1_BIT.
• Tests: rerun zig build test (shader validation covers g_pass.frag), and rerun the failing visual-test workflow — expect RMSE < 0.015.

PR 2 — Water pipeline MSAA sample count ("fix: thread msaa_samples into water pipeline")

• modules/engine-graphics/src/vulkan/water_system.zig:281: add msaa_samples: u8 parameter, derive rasterizationSamples = getMSAASampleCountFlag(msaa_samples).
• modules/engine-graphics/src/vulkan/rhi_init_deinit.zig:99 and rhi_frame_orchestration.zig:129: pass ctx.options.msaa_samples.
• Consider also plumbing getMSAASampleCountFlag if not already exposed by WaterSystem's module — render_pass_manager.zig:121 already calls it, so reuse the same helper.
• Tests: same — zig build test + visual-test rerun.

Optional follow-up (not strictly required)

The author is right that any other pipeline that copies multisampling.* could trip the same alphaToCoverage VUID later. A small audit pass grepping for = multisampling.* and = terrain_multisampling.* across modules/engine-graphics/src/vulkan/ would catch them before they bite. Current scan finds only the G-buffer site, so PR 1 is sufficient on its own.

Implementation guidance

• Both changes are minimal (≈5–10 LOC each) and confined to the Vulkan backend; no public API change.
• The suggested fix in the issue (std.mem.zeroes + targeted field assignments) matches existing house style in the same files (e.g., rasterizer, depth_stencil, vertex_input in water_system.zig:329-343).
• Keep an eye on the swapchain VK_IMAGE_LAYOUT_* errors in the report — they look downstream of the G-buffer corruption (the post-process pipeline reads stale/undefined data and the resolve target never gets a proper COLOR_ATTACHMENT_OPTIMAL → PRESENT_SRC transition on Lavapipe). I'd expect those to clear once PR 1 lands; if they don't, that's a separate layout-transition bug to file.
• After PR 1 + PR 2: regenerate docs/visual-test/golden/menu.png only if the new RMSE is genuinely closer to the intended look than the current golden — otherwise the existing golden stays valid.

Happy to pick one of these up if you want me to open the PR(s).

[github-actions]

Comment posted on issue #911: #911 (comment)

Classification: Bug (regression, two independent root causes).

Validation: Walked every file/line in the report — all five claims verified against the tree. PR #910 ("refactor: remove legacy lighting paths") is the plausible introducer; no duplicate open issues; both referenced CI runs (29078561400, 29003611574) confirm the same pair of validation errors.

Scope recommendation: Split into two PRs so bisect stays clean and the G-buffer fix isn't blocked on the water fix:

1. PR 1 — pipeline_specialized.zig:130-131: replace var g_multisampling = multisampling.* with std.mem.zeroes + targeted fields (kills alphaToCoverageEnable-08891).
2. PR 2 — thread msaa_samples through createWaterPipeline and both call sites (rhi_init_deinit.zig:99, rhi_frame_orchestration.zig:129) so water_system.zig:337 matches hdr_render_pass attachments (kills multisampledRenderToSingleSampled-06853).

Both are ~5–10 LOC each, follow existing house style, and should drop RMSE under 0.015. The downstream VK_IMAGE_LAYOUT_* errors in the report are likely just collateral damage from the corrupted G-buffer resolve and should clear automatically.

opencode session  |  github run