feat(vulkan): add alpha test shader path

adapters/fparkan-render-vulkan/shaders/manifest.json

@@ -1 +1 @@
-{"schema":2,"target_env":"vulkan1.1","compiler":{"name":"glslangValidator","version":"11:16.3.0","binary_sha256":"9bcd69d830b350aaa6e2254915ff74e46070e217b67f38daad27c1fc1f22910f"},"validator":{"name":"spirv-val","version":"SPIRV-Tools v2026.2 unknown hash, 2026-04-29T17:02:58+00:00","binary_sha256":"f6d5b96ff19f073f3af0c0bcfa0c18702d288d3ec598efc242d01cd104d8354f"},"modules":[{"name":"triangle.vert","stage":"vertex","entry_point":"main","source_path":"adapters/fparkan-render-vulkan/shaders/triangle.vert","source_sha256":"82f9ee39a30b094203041205954576ca820d75771421bb27ddd300359e4e9043","spirv_path":"adapters/fparkan-render-vulkan/shaders/triangle.vert.spv","word_count":290,"sha256":"1984662f78873b70135ec444ccd86d86fa66dfca3f615d19ddaf0cda1587d4cf","descriptor_sets":0,"push_constant_bytes":0,"compile_command":"glslangValidator -V --target-env vulkan1.1 -S vert -e main adapters/fparkan-render-vulkan/shaders/triangle.vert -o adapters/fparkan-render-vulkan/shaders/triangle.vert.spv","validate_command":"spirv-val --target-env vulkan1.1 adapters/fparkan-render-vulkan/shaders/triangle.vert.spv","interface_hash":"23e1d3d9d32e7f7ec0b9ca87f8b86be8f8363c7eb5d745fc5a157cb8433eb138"},{"name":"triangle.frag","stage":"fragment","entry_point":"main","source_path":"adapters/fparkan-render-vulkan/shaders/triangle.frag","source_sha256":"70b600a0c79b6cdee1747a47caf7854bbe0bb9a693b3fe29345e659df549d96f","spirv_path":"adapters/fparkan-render-vulkan/shaders/triangle.frag.spv","word_count":197,"sha256":"49dae3e1c46d5d23cccf3b161c36ea0b3a606e89c2289dbfed3e4fe991eb8556","descriptor_sets":1,"push_constant_bytes":0,"compile_command":"glslangValidator -V --target-env vulkan1.1 -S frag -e main adapters/fparkan-render-vulkan/shaders/triangle.frag -o adapters/fparkan-render-vulkan/shaders/triangle.frag.spv","validate_command":"spirv-val --target-env vulkan1.1 adapters/fparkan-render-vulkan/shaders/triangle.frag.spv","interface_hash":"446615153811b02f05622dc3cdeae998461a6a225a3d2098bba0e0d158a21027"}],"manifest_hash":"038ecdb57832ac2d45a1ca6da5ec058b34f4f31b7170aa68fa612ac9d0ae7565"}
+{"schema":2,"target_env":"vulkan1.1","compiler":{"name":"glslangValidator","version":"11:16.3.0","binary_sha256":"9bcd69d830b350aaa6e2254915ff74e46070e217b67f38daad27c1fc1f22910f"},"validator":{"name":"spirv-val","version":"SPIRV-Tools v2026.2 unknown hash, 2026-04-29T17:02:58+00:00","binary_sha256":"f6d5b96ff19f073f3af0c0bcfa0c18702d288d3ec598efc242d01cd104d8354f"},"modules":[{"name":"triangle.vert","stage":"vertex","entry_point":"main","source_path":"adapters/fparkan-render-vulkan/shaders/triangle.vert","source_sha256":"82f9ee39a30b094203041205954576ca820d75771421bb27ddd300359e4e9043","spirv_path":"adapters/fparkan-render-vulkan/shaders/triangle.vert.spv","word_count":290,"sha256":"1984662f78873b70135ec444ccd86d86fa66dfca3f615d19ddaf0cda1587d4cf","descriptor_sets":0,"push_constant_bytes":0,"compile_command":"glslangValidator -V --target-env vulkan1.1 -S vert -e main adapters/fparkan-render-vulkan/shaders/triangle.vert -o adapters/fparkan-render-vulkan/shaders/triangle.vert.spv","validate_command":"spirv-val --target-env vulkan1.1 adapters/fparkan-render-vulkan/shaders/triangle.vert.spv","interface_hash":"23e1d3d9d32e7f7ec0b9ca87f8b86be8f8363c7eb5d745fc5a157cb8433eb138"},{"name":"triangle.frag","stage":"fragment","entry_point":"main","source_path":"adapters/fparkan-render-vulkan/shaders/triangle.frag","source_sha256":"f9162fccce56111e85fdf0f58251798393c37aa23f9f3d979ba404bf6773c27b","spirv_path":"adapters/fparkan-render-vulkan/shaders/triangle.frag.spv","word_count":296,"sha256":"536a5c9a4389f9d34ca11a25f20d0acbc53d3eb0782c18375326647319336a85","descriptor_sets":1,"push_constant_bytes":4,"compile_command":"glslangValidator -V --target-env vulkan1.1 -S frag -e main adapters/fparkan-render-vulkan/shaders/triangle.frag -o adapters/fparkan-render-vulkan/shaders/triangle.frag.spv","validate_command":"spirv-val --target-env vulkan1.1 adapters/fparkan-render-vulkan/shaders/triangle.frag.spv","interface_hash":"7692547c3195074fefc2321e1f4d4a09a3d83c65465cefd2237c8bae1df58d88"}],"manifest_hash":"5a16fb791e86bb790cd2d85151627e0d39193c5c073a9294130f149d4ff5ba58"}

adapters/fparkan-render-vulkan/shaders/triangle.frag

@@ -6,6 +6,13 @@ layout(location = 0) out vec4 out_color;
 
 layout(set = 0, binding = 0) uniform sampler2D base_color;
 
+layout(push_constant) uniform AlphaTestConstants {
+    float alpha_cutoff;
+} alpha_test;
+
 void main() {
     out_color = texture(base_color, in_uv) * vec4(in_color, 1.0);
+    if (out_color.a < alpha_test.alpha_cutoff) {
+        discard;
+    }
 }

adapters/fparkan-render-vulkan/src/asset_mesh.rs

@@ -71,6 +71,7 @@ pub fn project_msh_to_static_mesh(
             index_count: u32::from(batch.index_count),
             material_index: batch.material_index,
             pipeline_state: LegacyPipelineState::default(),
+            alpha_test_reference: 0,
         });
     }
     if indices.is_empty() {
@@ -186,6 +187,7 @@ mod tests {
                 index_count: 3,
                 material_index: 0,
                 pipeline_state: LegacyPipelineState::default(),
+                alpha_test_reference: 0,
             }]
         );
         assert_eq!(mesh.vertices[1].position, [-0.8, -0.8]);
@@ -233,12 +235,14 @@ mod tests {
                     index_count: 3,
                     material_index: 0,
                     pipeline_state: LegacyPipelineState::default(),
+                    alpha_test_reference: 0,
                 },
                 VulkanStaticDrawRange {
                     first_index: 3,
                     index_count: 3,
                     material_index: 7,
                     pipeline_state: LegacyPipelineState::default(),
+                    alpha_test_reference: 0,
                 },
             ]
         );

adapters/fparkan-render-vulkan/src/ffi.rs

@@ -494,7 +494,7 @@ const fn spirv_words<const WORD_COUNT: usize>(bytes: &[u8]) -> [u32; WORD_COUNT]
 
 static TRIANGLE_VERTEX_SHADER_DATA: [u32; 290] =
     spirv_words(include_bytes!("../shaders/triangle.vert.spv"));
-static TRIANGLE_FRAGMENT_SHADER_DATA: [u32; 197] =
+static TRIANGLE_FRAGMENT_SHADER_DATA: [u32; 296] =
     spirv_words(include_bytes!("../shaders/triangle.frag.spv"));
 pub(crate) const TRIANGLE_VERTEX_SHADER_WORDS: &[u32] = &TRIANGLE_VERTEX_SHADER_DATA;
 pub(crate) const TRIANGLE_FRAGMENT_SHADER_WORDS: &[u32] = &TRIANGLE_FRAGMENT_SHADER_DATA;

adapters/fparkan-render-vulkan/src/ffi/smoke.rs

@@ -678,6 +678,14 @@ impl VulkanSmokeRenderer {
                     std::slice::from_ref(descriptor_set),
                     &[],
                 );
+                let alpha_cutoff = range.alpha_test_cutoff().to_ne_bytes();
+                device.device().cmd_push_constants(
+                    command_buffer,
+                    resources.pipeline_layout,
+                    vk::ShaderStageFlags::FRAGMENT,
+                    0,
+                    &alpha_cutoff,
+                );
                 device.device().cmd_draw_indexed(
                     command_buffer,
                     range.index_count,

adapters/fparkan-render-vulkan/src/ffi/smoke_types.rs

@@ -73,6 +73,8 @@ pub struct VulkanStaticDrawRange {
     pub material_index: u16,
     /// Backend-neutral fixed-function state for this source range.
     pub pipeline_state: LegacyPipelineState,
+    /// Alpha-test reference in legacy 0..=255 units; dynamic material data.
+    pub alpha_test_reference: u8,
 }
 
 impl VulkanStaticDrawRange {
@@ -81,6 +83,16 @@ impl VulkanStaticDrawRange {
     pub fn pipeline_key(self) -> PipelineKey {
         self.pipeline_state.into()
     }
+
+    /// Returns the normalized cutoff consumed by the fragment shader.
+    #[must_use]
+    pub fn alpha_test_cutoff(self) -> f32 {
+        if self.pipeline_state.alpha_test {
+            f32::from(self.alpha_test_reference) / 255.0
+        } else {
+            0.0
+        }
+    }
 }
 
 /// One diffuse material texture keyed by an original MSH batch selector.
@@ -185,6 +197,7 @@ impl VulkanStaticMesh {
                 index_count: 3,
                 material_index: 0,
                 pipeline_state: LegacyPipelineState::default(),
+                alpha_test_reference: 0,
             }],
         }
     }
@@ -252,6 +265,7 @@ mod static_mesh_tests {
                 index_count: 2,
                 material_index: 0,
                 pipeline_state: LegacyPipelineState::default(),
+                alpha_test_reference: 0,
             }],
         };
         let out_of_range_index = VulkanStaticMesh {
@@ -279,12 +293,14 @@ mod static_mesh_tests {
                 index_count: 3,
                 material_index: 7,
                 pipeline_state: LegacyPipelineState::default(),
+                alpha_test_reference: 0,
             },
             VulkanStaticDrawRange {
                 first_index: 3,
                 index_count: 3,
                 material_index: 2,
                 pipeline_state: LegacyPipelineState::default(),
+                alpha_test_reference: 0,
             },
         ];
         let texture = || VulkanStaticTexture {
@@ -323,6 +339,25 @@ mod static_mesh_tests {
         assert_eq!(base.pipeline_key().packed(), 0);
         assert_ne!(base.pipeline_key(), blended.pipeline_key());
     }
+
+    #[test]
+    fn alpha_cutoff_is_dynamic_and_disabled_outside_alpha_test_pipeline() {
+        let base = VulkanStaticMesh::smoke_triangle().draw_ranges[0];
+        let disabled = VulkanStaticDrawRange {
+            alpha_test_reference: 200,
+            ..base
+        };
+        let enabled = VulkanStaticDrawRange {
+            pipeline_state: LegacyPipelineState {
+                alpha_test: true,
+                ..LegacyPipelineState::default()
+            },
+            alpha_test_reference: 128,
+            ..base
+        };
+        assert_eq!(disabled.alpha_test_cutoff(), 0.0);
+        assert_eq!(enabled.alpha_test_cutoff(), 128.0 / 255.0);
+    }
 }
 
 /// Shared bootstrap progress used to report partial renderer startup evidence.

adapters/fparkan-render-vulkan/src/ffi/swapchain_resources.rs

@@ -381,7 +381,13 @@ fn create_pipeline_layout(
     descriptor_set_layout: vk::DescriptorSetLayout,
 ) -> Result<vk::PipelineLayout, VulkanSmokeRendererError> {
     let set_layouts = [descriptor_set_layout];
-    let create_info = vk::PipelineLayoutCreateInfo::default().set_layouts(&set_layouts);
+    let push_constant_ranges = [vk::PushConstantRange::default()
+        .stage_flags(vk::ShaderStageFlags::FRAGMENT)
+        .offset(0)
+        .size(u32::try_from(std::mem::size_of::<f32>()).unwrap_or(u32::MAX))];
+    let create_info = vk::PipelineLayoutCreateInfo::default()
+        .set_layouts(&set_layouts)
+        .push_constant_ranges(&push_constant_ranges);
     // SAFETY: The descriptor-set layout belongs to this live logical device.
     unsafe { device.device().create_pipeline_layout(&create_info, None) }.map_err(|error| {
         VulkanSmokeRendererError::VulkanOperation {
@@ -562,12 +568,6 @@ fn create_graphics_pipeline(
     extent: (u32, u32),
     state: LegacyPipelineState,
 ) -> Result<vk::Pipeline, VulkanSmokeRendererError> {
-    if state.alpha_test {
-        return Err(VulkanSmokeRendererError::InvalidStaticMesh {
-            context:
-                "static renderer has no alpha-test shader variant for requested pipeline state",
-        });
-    }
     let vertex_shader = create_shader_module(device, TRIANGLE_VERTEX_SHADER_WORDS)?;
     let fragment_shader = match create_shader_module(device, TRIANGLE_FRAGMENT_SHADER_WORDS) {
         Ok(module) => module,

adapters/fparkan-render-vulkan/src/ffi/tests.rs

@@ -669,11 +669,11 @@ fn triangle_shader_manifest_hashes_are_stable() {
     assert!(!report.modules[0].interface_hash.is_empty());
     assert_eq!(
         report.modules[1].sha256,
-        "49dae3e1c46d5d23cccf3b161c36ea0b3a606e89c2289dbfed3e4fe991eb8556"
+        "536a5c9a4389f9d34ca11a25f20d0acbc53d3eb0782c18375326647319336a85"
     );
     assert_eq!(
         report.manifest_hash,
-        "038ecdb57832ac2d45a1ca6da5ec058b34f4f31b7170aa68fa612ac9d0ae7565"
+        "5a16fb791e86bb790cd2d85151627e0d39193c5c073a9294130f149d4ff5ba58"
     );
 }
 

adapters/fparkan-render-vulkan/src/shader_manifest.rs

@@ -29,7 +29,7 @@ pub(crate) const TRIANGLE_VERTEX_VALIDATE_COMMAND: &str =
     "spirv-val --target-env vulkan1.1 adapters/fparkan-render-vulkan/shaders/triangle.vert.spv";
 const TRIANGLE_FRAGMENT_SOURCE_PATH: &str = "adapters/fparkan-render-vulkan/shaders/triangle.frag";
 const TRIANGLE_FRAGMENT_SOURCE_SHA256: &str =
-    "70b600a0c79b6cdee1747a47caf7854bbe0bb9a693b3fe29345e659df549d96f";
+    "f9162fccce56111e85fdf0f58251798393c37aa23f9f3d979ba404bf6773c27b";
 const TRIANGLE_FRAGMENT_SPIRV_PATH: &str =
     "adapters/fparkan-render-vulkan/shaders/triangle.frag.spv";
 const TRIANGLE_FRAGMENT_COMPILE_COMMAND: &str =
@@ -226,7 +226,7 @@ pub fn triangle_shader_manifest() -> Vec<VulkanShaderModuleManifest> {
             stage: VulkanShaderStage::Fragment,
             entry_point: "main",
             descriptor_sets: 1,
-            push_constant_bytes: 0,
+            push_constant_bytes: 4,
             source_path: TRIANGLE_FRAGMENT_SOURCE_PATH,
             source_sha256: TRIANGLE_FRAGMENT_SOURCE_SHA256,
             spirv_path: TRIANGLE_FRAGMENT_SPIRV_PATH,

docs/tomes/05-render.md

@@ -849,9 +849,12 @@ swapchain resources, создаёт один `vk::Pipeline` на уникаль
 кэше. При создании swapchain resources renderer выбирает capability-approved
 depth/stencil format, выделяет device-local attachment, очищает его в render
 pass и прикрепляет к каждому framebuffer. `TestWrite` включает depth test и
-write; `TestReadOnly` включает test без write. Alpha-test пока завершается
+write; `TestReadOnly` включает test без write. Alpha test выполняется во
-явной ошибкой: shader variant ещё не существует, поэтому renderer не должен
+fragment shader: перед каждым draw renderer передаёт через push constant
-молча подменять state. Также не установлен источник значений для Batch20/MAT0: их
+`alpha_test_reference / 255`, а shader отбрасывает fragment с меньшей alpha.
+При выключенном `alpha_test` cutoff принудительно равен нулю; reference остаётся
+dynamic material data и не входит в `PipelineKey`. Также не установлен источник
+значений для Batch20/MAT0: их
 поля нельзя объявлять blend/depth/cull mapping без dynamic capture или
 дополнительного дизассемблирования. Это частично реализованная compatibility
 boundary, а не заявление о готовой parity fixed-function state.

fixtures/acceptance/coverage.tsv

@@ -297,7 +297,7 @@ S2-PLANNING-RENDER-009	covered	cargo xtask policy
 S3-VK-MESH-UPLOAD-001	covered-gpu	cargo run -p fparkan-vulkan-smoke --release --locked -- --out target/fparkan/stage3-mtcheck-msh.json --frames 300 --resize-frame 120 --timeout-seconds 90 --model-root <GOG_ROOT> --model-archive system.rlb --model-name MTCHECK.MSH; original MSH reports 128 vertices and 252 indices
 S3-VK-TEXM-UPLOAD-001	covered-gpu	cargo run -p fparkan-vulkan-smoke --release --locked -- --out target/fparkan/stage3-mtcheck-texm-upload.json --frames 300 --resize-frame 120 --timeout-seconds 90 --model-root <GOG_ROOT> --model-archive system.rlb --model-name MTCHECK.MSH --texture-root <GOG_ROOT> --texture-archive Textures.lib --texture-name DEFAULT.0; original TEXM 16x16 decoded RGBA8, staged into device-local image and transitioned to SHADER_READ_ONLY_OPTIMAL
 S3-VK-DESCRIPTOR-001	covered-gpu	cargo run -p fparkan-vulkan-smoke --release --locked -- --out target/fparkan/stage3-texm-sampled.json --frames 300 --resize-frame 120 --timeout-seconds 90 --model-root <GOG_ROOT> --model-archive system.rlb --model-name MTCHECK.MSH --texture-root <GOG_ROOT> --texture-archive Textures.lib --texture-name DEFAULT.0; original TEXM is bound as set=0,binding=0 combined image sampler and sampled in fragment shader; validation_warning_count=0 and validation_error_count=0
-S3-VK-PIPELINE-001	covered-gpu	cargo run -p fparkan-vulkan-smoke --release --locked -- --out target/fparkan/stage3-depth-attachment-smoke.json --frames 300 --resize-frame 120 --timeout-seconds 90 --model-root <GOG_ROOT> --model-archive system.rlb --model-name MTCHECK.MSH --texture-root <GOG_ROOT> --texture-archive Textures.lib --texture-name DEFAULT.0; PipelineKey selects a deduplicated live Vulkan pipeline per static draw range; capability-selected device-local depth attachment supports TestWrite/TestReadOnly, baseline key is live-proven; unproven Batch20/MAT0 state mapping and unsupported alpha-test remain explicit gaps
+S3-VK-PIPELINE-001	covered-gpu	cargo run -p fparkan-vulkan-smoke --release --locked -- --out target/fparkan/stage3-alpha-test-smoke.json --frames 300 --resize-frame 120 --timeout-seconds 90 --model-root <GOG_ROOT> --model-archive system.rlb --model-name MTCHECK.MSH --texture-root <GOG_ROOT> --texture-archive Textures.lib --texture-name DEFAULT.0; PipelineKey selects a deduplicated live Vulkan pipeline per static draw range; capability-selected depth attachment supports TestWrite/TestReadOnly; fragment alpha test receives per-range dynamic cutoff through push constants; baseline key is live-proven, while Batch20/MAT0 state/reference mapping remains an evidence gap
 S3-VK-DRAW-MODEL-001	covered-gpu	cargo run -p fparkan-vulkan-smoke --release --locked -- --out target/fparkan/stage3-fr-l-mtp-per-batch-materials.json --frames 300 --resize-frame 120 --timeout-seconds 90 --model-root <GOG_ROOT> --model-archive fortif.rlb --model-name FR_L_MTP.msh --wear-root <GOG_ROOT> --wear-archive fortif.rlb --wear-name FR_L_MTP.WEA; live Win32 Vulkan issues 237 source-preserving indexed batch draws and binds the deduplicated WEAR→MAT0 material descriptor selected by each Batch20.material_index (this corpus model has selector 0 only)
 S3-VK-DRAW-TERRAIN-001	blocked	awaits Stage 3 terrain Vulkan draw path
 S3-VK-PIXEL-CAPTURE-001	blocked	awaits Stage 3 fixed-camera pixel capture approval flow