Add deterministic procedural mesh toolkit (procgen) with primitives, spline extrusion, lathe, segments, SDF/volume & shell demo

CMakeLists.txt

@@ -137,6 +137,17 @@ render_apply_project_options(render_renderer)
 render_apply_warnings(render_renderer)
 
 
+
+add_library(render_procgen STATIC
+  engine/procgen/procgen.hpp
+  engine/procgen/procgen.cpp
+)
+add_library(render::procgen ALIAS render_procgen)
+target_include_directories(render_procgen PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}")
+target_link_libraries(render_procgen PUBLIC render::core render::renderer)
+render_apply_project_options(render_procgen)
+render_apply_warnings(render_procgen)
+
 add_library(render_scene STATIC
   engine/scene/scene.hpp
   engine/scene/scene.cpp
@@ -151,7 +162,7 @@ add_library(render_engine STATIC
   engine/engine.cpp
 )
 add_library(render::engine ALIAS render_engine)
-target_link_libraries(render_engine PUBLIC render::core render::filesystem render::platform render::renderer render::serialization render::scene)
+target_link_libraries(render_engine PUBLIC render::core render::filesystem render::platform render::renderer render::serialization render::scene render::procgen)
 render_apply_project_options(render_engine)
 render_apply_warnings(render_engine)
 
@@ -236,6 +247,11 @@ if(RENDER_BUILD_TESTS)
   render_apply_project_options(render_render_pass_system_tests)
   render_apply_warnings(render_render_pass_system_tests)
 
+  add_executable(render_procgen_tests tests/procgen/procgen_tests.cpp)
+  target_link_libraries(render_procgen_tests PRIVATE render::procgen)
+  render_apply_project_options(render_procgen_tests)
+  render_apply_warnings(render_procgen_tests)
+
   add_executable(render_scene_tests tests/scene/scene_tests.cpp)
   target_link_libraries(render_scene_tests PRIVATE render::scene)
   render_apply_project_options(render_scene_tests)
@@ -266,6 +282,8 @@ if(RENDER_BUILD_TESTS)
   set_tests_properties(unit.renderer.debug_views PROPERTIES LABELS "unit;renderer;debug")
   add_test(NAME unit.renderer.render_pass_system COMMAND render_render_pass_system_tests)
   set_tests_properties(unit.renderer.render_pass_system PROPERTIES LABELS "unit;renderer;graph")
+  add_test(NAME unit.procgen.mesh_toolkit COMMAND render_procgen_tests)
+  set_tests_properties(unit.procgen.mesh_toolkit PROPERTIES LABELS "unit;procgen")
   add_test(NAME unit.scene.runtime COMMAND render_scene_tests)
   set_tests_properties(unit.scene.runtime PROPERTIES LABELS "unit;scene")
   add_test(NAME unit.renderer.vfx_system COMMAND render_vfx_system_tests)
@@ -275,7 +293,7 @@ if(RENDER_BUILD_TESTS)
 
   add_custom_target(render_test_unit
     COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure --label-regex unit
-    DEPENDS render_platform_types_tests render_core_runtime_tests render_serialization_tests render_filesystem_tests render_renderer_lifecycle_tests render_shader_pipeline_tests render_geometry_submission_tests render_lighting_pipeline_tests render_debug_renderer_tests render_scene_tests render_vfx_system_tests
+    DEPENDS render_platform_types_tests render_core_runtime_tests render_serialization_tests render_filesystem_tests render_renderer_lifecycle_tests render_shader_pipeline_tests render_geometry_submission_tests render_lighting_pipeline_tests render_debug_renderer_tests render_procgen_tests render_scene_tests render_vfx_system_tests
     WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
     COMMENT "Running render unit tests"
   )

docs/architecture.md

@@ -1,4 +1,4 @@
-# Architecture Snapshot (Statements 5-11)
+# Architecture Snapshot (Statements 5-17)
 
 ## Runtime layering now implemented
 
@@ -40,3 +40,10 @@
    - Engine-owned scene graph with stable node handles, transform hierarchy, visibility, and debug names.
    - Optional camera/light/renderable attachments with traversal and renderer extraction helpers.
    - Explicit update step for dirty world transform propagation (`Scene::update_world_transforms`).
+
+
+7. **Procedural mesh toolkit (`engine/procgen`)**
+   - Engine-owned deterministic mesh generation APIs outputting `render::rendering::CpuMeshData`.
+   - Primitives, spline sampling/extrusion, lathe/revolve, segment assembly, scalar fields, SDF composition, and local surface extraction.
+   - Mesh validation/stats and post-processing helpers for combining/transforms/re-normals/degenerate cleanup.
+   - Runtime shell now demonstrates representative generated meshes using the normal renderer submission path.

docs/procgen.md

@@ -0,0 +1,109 @@
+# Procedural Mesh Toolkit (Statement 17)
+
+## Overview
+
+`engine/procgen` now provides the engine-owned procedural geometry foundation used by runtime generation and test fixtures. It is intentionally renderer-backend agnostic, deterministic when seeded, and emits `render::rendering::CpuMeshData` so generated meshes can flow directly into Statement 12 upload/submission paths.
+
+## Module organization
+
+- `engine/procgen/procgen.hpp`
+  - Public engine API for deterministic mesh generation and helpers.
+  - Primitive generation APIs (`make_box`, `make_uv_sphere`, `make_capsule`, ...).
+  - Spline/path sampling and extrusion APIs.
+  - Lathe/revolve API.
+  - Segment assembly API with explicit seed.
+  - Scalar field / SDF authoring and composition APIs.
+  - Surface extraction API from sampled fields.
+  - Mesh post-processing, validation, and stats APIs.
+- `engine/procgen/procgen.cpp`
+  - Concrete topology generation implementations and shared mesh utility logic.
+
+## Determinism and seed usage
+
+- Segment assembly consumes `render::core::Seed` and uses `render::core::Random` splits per segment.
+- Variation (yaw and scale jitter) is explicit per segment descriptor.
+- No hidden global RNG is used.
+- Same input recipe + same seed => byte-identical generated CPU mesh buffers in tests.
+- Floating-point caveat: exact results assume identical compiler/platform floating-point behavior; topology/ordering is deterministic in-engine.
+
+## Generation modes and conventions
+
+### Primitives
+
+Implemented primitives:
+- quad
+- plane
+- box
+- UV sphere
+- cylinder
+- cone
+- torus
+- capsule
+
+Conventions:
+- Counter-clockwise winding.
+- Per-vertex normals and UVs generated.
+- Tangent slot is populated with a stable orthonormal basis hook.
+- Segment counts are clamped to safe minimums to avoid degenerate topology.
+
+### Spline/path and extrusion
+
+- `SplinePath` stores control points and open/closed state.
+- Catmull-Rom interpolation is used for sampling.
+- Per-sample frame data (tangent/normal/binormal) is derived for extrusion.
+- `extrude_profile_along_path` sweeps a 2D profile through the sampled path.
+- Supports closed profiles and optional caps.
+
+### Lathe/revolve
+
+- `lathe_profile` revolves a 2D radius-height profile around the Y axis.
+- Supports full revolve and partial revolve (`angle_radians`).
+- Optional start/end caps for partial lathes.
+
+### Segment assembly
+
+- `assemble_segments` merges reusable segment meshes using local attachment transforms.
+- Optional deterministic yaw/scale jitter per segment.
+- Useful for chained bug limbs, organic supports, tails, and decorative modular props.
+
+### Volumes, SDF, and extraction
+
+- `ScalarField` provides grid-sampled scalar storage, write, query, and world-space mapping.
+- SDF primitives: sphere, box, capsule, cylinder, plane.
+- SDF composition: union, subtraction, intersection, smooth union, translate.
+- `rasterize_sdf_to_field` samples an arbitrary SDF into a scalar grid.
+- `extract_isosurface` uses marching tetrahedra to produce a local mesh from the scalar field.
+
+## Surface data and post processing
+
+The toolkit includes practical mesh helpers:
+- `merge_meshes`
+- `transform_mesh`
+- `recalculate_normals`
+- `remove_degenerate_triangles`
+- `mesh_stats` / bounds
+- `validate_proc_mesh` (layout, index range, finite data, degenerate counts)
+
+## Renderer integration
+
+Toolkit output is `CpuMeshData` with procgen-owned vertex layout. The shell now uploads generated meshes via normal renderer buffer creation paths and renders:
+- primitive mesh
+- spline extrusion mesh
+- lathed mesh
+- segmented assembly mesh
+- SDF/volume extracted mesh
+
+No bgfx/back-end detail is referenced from generation code.
+
+## Scope and deferred items
+
+Implemented now:
+- deterministic local mesh generation foundation
+- practical primitive/extrude/lathe/segment/SDF/volume pipeline
+- mesh utility + validation support
+
+Deferred for future statements:
+- authoring/editor UX beyond runtime previews
+- higher-order remeshing/subdivision pipelines
+- very large terrain/world extraction systems
+- advanced UV unwrapping strategies for arbitrary extracted surfaces