Skip to content

feat(render): add 3D mesh staging uploads and camera-relative occlusion - #13

Merged
brasga-a merged 2 commits into
masterfrom
feat/m2-p4-render-mesh
Nov 18, 2026
Merged

brasga-a merged 2 commits into
masterfrom
feat/m2-p4-render-mesh

Conversation

@brasga-a

Copy link
Copy Markdown
Owner

Summary

Implements Milestone 2 — Phase 4 (spawn-render: static 3D vertex/index staging uploads, indexed draws, and camera-relative reversed-Z occlusion), stacked on feat/m2-p3-render-triangle (#12).

  • Dependencies & crate boundaries (ADR-0004, ADR-0010, SPN-INV-006, SPN-INV-009, SPN-INV-011, SPN-INV-023):
    • Added spawn-render -> spawn-math (default-features = false; headless spawn-render pulls only pure-Rust spawn-math -> libm with zero window/GPU or C/FFI crates).
    • Added approved bytemuck = 1.25.2 (default-features = false, features = ["derive"], MIT OR Apache-2.0 OR Zlib) behind optional feature vulkan, strictly confined inside private crates/spawn-render/src/vulkan/mesh.rs with zero public API leakage (SPN-INV-011).
  • Pure 3D mesh descriptors & camera-relative draw contracts (crates/spawn-render/src/{mesh,handle,types}.rs):
    • #![forbid(unsafe_code)] and #![deny(clippy::indexing_slicing)].
    • MeshVertex (40 B: position, normal, color), MeshDescriptor::validate (REND-0014 pre-allocation bounds/multiplicity/finiteness/index-range checks), generational MeshHandle (REND-0013), GraphicsPipelineDescriptor::new_mesh_3d, CameraRelativeView, MeshDraw (from_world subtracting WorldPos in f64 on the CPU via spawn_math::camera_relative_f32 per SPN-INV-052), and PackedMeshPushConstants (128 B matching shaders/mesh_3d.slang).
  • Vulkan 1.3 staging uploads & indexed draws (crates/spawn-render/src/vulkan/{mesh,memory,frame,pipeline,mod}.rs, src/renderer.rs):
    • Renderer::{upload_mesh, destroy_mesh, render_meshes, render_offscreen_meshes}: suballocates HOST_VISIBLE | HOST_COHERENT staging buffers and DEVICE_LOCAL VERTEX_BUFFER + INDEX_BUFFER buffers with VK_EXT_debug_utils labels, records vkCmdCopyBuffer2 + synchronization2 VkBufferMemoryBarrier2 (COPY/TRANSFER_WRITE -> VERTEX_ATTRIBUTE_INPUT/INDEX_INPUT), retires staging and destroyed mesh buffers on the timeline semaphore, pushes 128-byte MeshPushConstants, and executes vkCmdDrawIndexed across both COLOR_ATTACHMENT-only swapchains (SPN-INV-092) and R8G8B8A8_UNORM offscreen readback targets.

Requirements Covered

  • F3D-FR-02, F3D-FR-06, F3D-FR-07, F3D-FR-08, F3D-FR-10, F3D-FR-12
  • F3D-NFR-01..07
  • Verification cases: F3D-T12, Phase 4 F3D-T13, FND-T09 (with FND-T01..T10 and F3D-T01..T04, T06..T09, T11 remaining green)

Invariants Touched

  • SPN-INV-006, SPN-INV-009, SPN-INV-011, SPN-INV-020..023, SPN-INV-030, SPN-INV-033, SPN-INV-034, SPN-INV-035, SPN-INV-050..053, SPN-INV-083, SPN-INV-084, SPN-INV-091, SPN-INV-092, SPN-INV-100, SPN-INV-101
  • F3D-INV-01..04, F3D-INV-06, F3D-INV-07, F3D-INV-11..16
  • ADR-0020 and ADR-0022 remain Proposed (SPN-INV-101).

Tests Run

  1. Gate G0 with pinned slangc 2026.22 (PATH="$HOME/.local/bin:$PATH" ./scripts/check.sh):
    • cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (51 spawn-render unit tests + 7 shader_validation + 1 f3d_t13_render_hygiene + FND-T01..T10 + F3D-T01..T04, T06..T09), cargo doc --workspace --no-deps, cargo doc -p spawn-render --features vulkan --no-deps, cargo deny check (advisories ok, bans ok, licenses ok, sources ok) -> exit 0.
  2. Gate G0 headless without slangc (PATH="/usr/bin:/usr/local/bin:/bin:$HOME/.cargo/bin" ./scripts/check.sh):
    • exit 0.
  3. Gate G2 standalone fuzz target (cargo check --manifest-path crates/spawn-render/fuzz/Cargo.toml):
    • exit 0.
  4. Opt-in Vulkan 1.3 GPU validation + sync-validation suite on reference RX 460 (PATH="$HOME/.local/bin:$PATH" VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true cargo test -p spawn-render --features vulkan -- --ignored):
    • 7/7 passed (validation_enabled: true, 0 validation/sync errors, 0 leaked allocations):
      • vulkan::gpu_tests (4/4 Foundation headless-surface tests)
      • f3d_t11_triangle_gpu (1/1)
      • f3d_t12_mesh_occlusion_gpu (2/2: exercises both self-contained synthesized SPIR-V 1.6 and live slangc 2026.22-cooked shaders/mesh_3d.slang for -2.0 m vs -5.0 m far-after-near occlusion across finite & infinite reversed-Z projections, +Y world-up top orientation, CullMode::Back backface culling + directional-shaded 24-vertex 3D cube, byte-exact 129x129 RGBA8 equivalence between WorldPos::ORIGIN and WorldPos(50_000, -50_000, 50_000) at 2 mm separation, headless swapchain multi-mesh resize/0x0 suspend/resume, and negative REND-0012..0014 unwind checks; also verified self-contained with target/shaders removed and slangc off PATH).

Platforms Tested & Known Limitations

  • Tested: Omarchy (Arch Linux 7.2.15-1-omarchy), AMD Ryzen 5 1600, AMD Radeon RX 460 (RADV POLARIS11, Mesa 26.2.5-arch1.1, Vulkan 1.4.354), pinned slangc 2026.22, VK_LAYER_KHRONOS_validation + VK_KHRONOS_VALIDATION_VALIDATE_SYNC=true.
  • Not verified / deferred: Interactive 60 Hz f64 FreeCamera and spawn-engine Wayland 3D session (PLANNED for Phase 5); compositors other than Hyprland; GPUs other than RX 460; X11 and Windows (PLANNED); separate transfer queues, descriptor binding tables, render graph, and materials (PLANNED for subsequent milestones).

@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 force-pushed the feat/m2-p4-render-mesh branch from ff59bc3 to 46330aa Compare November 18, 2026 17:03
@brasga-a
brasga-a changed the base branch from feat/m2-p3-render-triangle to master November 18, 2026 19:40
@brasga-a
brasga-a merged commit 6a54ce3 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