Skip to content

feat(render): Milestone 2 Phase 3 — GPU block suballocator, D32_SFLOAT reversed-Z depth & dynamicRendering triangle - #12

Merged
brasga-a merged 1 commit into
masterfrom
feat/m2-p3-render-triangle
Nov 18, 2026
Merged

brasga-a merged 1 commit into
masterfrom
feat/m2-p3-render-triangle

Conversation

@brasga-a

Copy link
Copy Markdown
Owner

Summary

Implements Milestone 2 — Phase 3 (crates/spawn-render + examples/vulkan_triangle.rs), stacked cleanly on feat/m2-p2-shader-cook (359c9fc):

  1. Device selection & hardware limits (src/selection.rs, src/vulkan/device.rs):
    • Requires optimal-tiling VK_FORMAT_D32_SFLOAT support for VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, maxPushConstantsSize >= 128, vertex-input limits (maxVertexInputAttributes >= 3, maxVertexInputBindings >= 1, maxVertexInputBindingStride >= 40), and timelineSemaphore alongside synchronization2 and dynamicRendering, reporting every missing requirement per GPU under REND-0003.
  2. In-house GPU block suballocator & timeline retirement (src/allocator.rs, src/vulkan/memory.rs, ADR-0004 decision 3):
    • Pure, always-compiled PureGpuAllocator (default-features = false, #![forbid(unsafe_code)], #![deny(clippy::indexing_slicing)]) paired with VulkanMemoryAllocator (16 MiB DEVICE_LOCAL blocks + persistently mapped 4 MiB HOST_VISIBLE | HOST_COHERENT blocks, dedicated oversized block fallback, configurable GpuMemoryBudget returning located REND-0012 GpuMemoryExhausted on exhaustion).
    • Enforces power-of-two alignment and exact left/right neighbor bufferImageGranularity page separation between linear (VkBuffer) and optimal (VkImage) suballocations, deterministically coalesces adjacent freed ranges without fragmentation, retires Vulkan child handles and suballocations on the timeline semaphore (completed_timeline >= last_used_timeline) before vkFreeMemory, and verifies zero leaks on shutdown.
  3. Swapchain-matched D32_SFLOAT reversed-Z depth (src/depth.rs, src/vulkan/{frame,mod}.rs):
    • Pure DepthAttachmentController + DEVICE_LOCAL VK_FORMAT_D32_SFLOAT depth image/view (REVERSED_Z_CLEAR_DEPTH = 0.0, never allocated at 0x0 while Suspended, idempotent extent reuse/recreation across resize and surface recovery).
    • Keeps swapchain imageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT only (SPN-INV-092).
  4. Generational handles, Vulkan 1.3 dynamicRendering pipelines & offscreen RGBA8 readback (src/handle.rs, src/vulkan/pipeline.rs, examples/vulkan_triangle.rs):
    • Generational ShaderHandle, PipelineHandle, and OffscreenTargetHandle (SPN-INV-035: stale, destroyed, or forged handles return located REND-0013 InvalidResourceHandle; invalid descriptors return REND-0014 InvalidResourceDescriptor).
    • Validates untrusted .spnshdr artifacts via CookedShader::from_bytes and validate_graphics_pipeline_shaders BEFORE vkCreateShaderModule (SPN-INV-034).
    • Builds graphics pipelines via VkPipelineRenderingCreateInfo (zero VkRenderPass/VkFramebuffer): TRIANGLE_LIST, VK_FRONT_FACE_COUNTER_CLOCKWISE, VK_CULL_MODE_BACK_BIT, reversed-Z VK_COMPARE_OP_GREATER_OR_EQUAL, positive-height [0.0, 1.0] VkViewport, synchronization2 barriers, and VK_EXT_debug_utils names on memory blocks, buffers, depth/offscreen images, views, shader modules, pipeline layouts, and pipelines.
    • Dedicated DEVICE_LOCAL VK_FORMAT_R8G8B8A8_UNORM (COLOR_ATTACHMENT | TRANSFER_SRC) + D32_SFLOAT offscreen targets with vkCmdCopyImageToBuffer2 (COPY -> HOST_READ barrier) into suballocated HOST_VISIBLE | HOST_COHERENT buffers, plus examples/vulkan_triangle.rs (keeping examples/vulkan_clear.rs intact).

Requirements Covered

  • F3D-FR-05 (cooked-shader + layout validation before GPU shader module/pipeline creation)
  • F3D-FR-06 (in-house GPU block suballocator, staging/readback host-visible blocks, timeline retirement, leak-free shutdown)
  • F3D-FR-07 (VK_FORMAT_D32_SFLOAT reversed-Z depth attachment across resize, 0x0 suspend, and recovery)
  • F3D-FR-08 (Vulkan 1.3 dynamicRendering triangle pass, CCW front-face, backface culling, offscreen readback)
  • F3D-FR-12 (located RenderErrors REND-0012..0014 with #[track_caller] and reverse-order unwind)
  • F3D-NFR-01..07 (genre neutrality, zero new crate edges, zero default-feature third-party deps, #![forbid(unsafe_code)] outside src/vulkan/, zero Khronos validation/sync errors, recorded reference-hardware smoke evidence)

Tests Run

  1. Gate G0 (./scripts/check.sh) with slangc 2026.22 on PATH and headless without slangc:
    • PATH="$HOME/.local/bin:$PATH" ./scripts/check.sh → exit 0
    • PATH="/usr/bin:/usr/local/bin:/bin:$HOME/.cargo/bin" ./scripts/check.sh → exit 0
    • Includes F3D-T08 (allocator.rs unit + proptest + insta OOM snapshot), F3D-T09 (depth.rs lifecycle + selection.rs rejections), Phase 3 F3D-T13 (tests/f3d_t13_render_hygiene.rs), F3D-T01..T04, F3D-T06..T07, FND-T01..T10, cargo clippy --all-targets -- -D warnings, RUSTDOCFLAGS="-D warnings" cargo doc, and cargo deny check.
  2. Gate G2 standalone fuzz target check:
    • cargo check --manifest-path crates/spawn-render/fuzz/Cargo.toml → exit 0
  3. Opt-in Vulkan 1.3 GPU validation + sync-validation suite on RX 460:
    • VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true cargo test -p spawn-render --features vulkan -- --ignored → 5/5 passed (4 Foundation headless-surface tests + tests/f3d_t11_triangle_gpu.rs F3D-T11: offscreen 65x65 R8G8B8A8_UNORM CCW triangle readback [153, 115, 102, 255] center & [13, 26, 38, 255] corners, CW backface culling, reversed-Z z = 0.0 vs clipped z = -0.25, negative shader/layout/stale-handle/OOM checks, headless swapchain resize/0x0 suspend, validation_errors=0, 0 leaked blocks/suballocations).
  4. Live Wayland + RX 460 vulkan_triangle smoke run & missing-shader probe:
    • PATH="$HOME/.local/bin:$PATH" cargo run -p spawn-cli -- shaders build && SPAWN_SMOKE_SECONDS=3 VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true cargo run --example vulkan_triangle
    • Observed: mapped 976x512, handled live Hyprland tiling resize to 968x504 inside a single 16 MiB (16,777,216 B) DEVICE_LOCAL block (blocks=1, live_allocs=1, live_bytes=2,129,928, peak_block_bytes=16,777,216), presented=157, suspended=0, skipped=0, validation_errors=0, clean close (shutdown_blocks=0, shutdown_live_allocs=0, shutdown_retired_allocs=0, exit 0).
    • Negative probe (SPAWN_SHADER_DIR=/tmp/nonexistent_spawn_shaders): actionable diagnostic naming missing .spnshdr path, exit 1, no panic.

Platforms Tested

  • Reference hardware: Omarchy (Arch Linux, kernel 7.2.15-1-omarchy), Hyprland 0.56.2 (Wayland native), AMD Ryzen 5 1600, AMD Radeon RX 460 (RADV POLARIS11, Mesa 26.2.5-arch1.1, Vulkan 1.4.354), VK_LAYER_KHRONOS_validation + VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true, pinned slangc 2026.22, Rust 1.99.1.

Invariants Touched / Verified

  • SPN-INV-001..006, 009, 011, 020..023, 030..035, 050, 053, 081, 083..084, 090..092, 100..101
  • F3D-INV-01..04, 07, 09, 11..16
  • Proposed ADR-0020 and ADR-0022 remain Proposed.

Known Limitations

  • spawn-render -> spawn-math dependency edge, static vertex/index buffer staging uploads (vkCmdCopyBuffer2), and indexed camera-relative 3D mesh occlusion (F3D-T12) are PLANNED for Phase 4.
  • 60 Hz f64 free-fly camera simulation and alpha-interpolated procedural 3D scene (F3D-T05, F3D-T10) are PLANNED for Phase 5.
  • X11 and Windows native window/surface backends are not implemented (PLANNED); Linux/Wayland on Hyprland + RADV RX 460 is the only smoke-tested native target.

@brasga-a
brasga-a force-pushed the feat/m2-p2-shader-cook branch from 359c9fc to c3bc712 Compare November 18, 2026 17:03
@brasga-a
brasga-a force-pushed the feat/m2-p3-render-triangle branch from 945155f to 87462e8 Compare November 18, 2026 17:03
@brasga-a
brasga-a changed the base branch from feat/m2-p2-shader-cook to master November 18, 2026 19:40
@brasga-a
brasga-a merged commit 2f20b1e into master Nov 18, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant