terrain: props can now spawn on specific layers/biomes

Author: PanosK92

data/shaders/grass_populate.hlsl

@@ -50,7 +50,7 @@ static const float grass_cull_radius      = 1.5f;
 //   values[0] = (cell_size, ring_radius, lod_base_in_instances, max_instances_per_lod)
 //   values[1] = (height_min, height_max, max_slope_cos, inner_radius)
 //   values[2] = (map_origin_x, map_origin_z, map_inv_size_x, map_inv_size_z)
-//   values[3] = (patch_size_m, patch_coverage, patch_edge, patch_scar)
+//   values[3] = (patch_size_m, patch_coverage, patch_edge, ground_mask bits)
 // a patch size of zero spreads the slot evenly, which is what this pass did before patches existed,
 // and a negative one inverts the field so a slot takes the ground the others left bare
 // every float is taken, so the rest travels in the bits of draw_index:
@@ -64,6 +64,8 @@ static const float grass_cull_radius      = 1.5f;
 // terrain height is r32 local y bound to tex (t7), material_index bitcast is the entity y plus the
 // layer's seating offset, a negative offset is what pushes an instance down into the ground
 // biome_min arrives asfloat(is_transparent), negative disables the gate
+// the prop mask is rgb weights plus the dominant surface layer index in alpha, the index needs a
+// point tap because a bilinear one between two layers averages to a value that names a third
 
 // 32-bit integer hash, takes the cell's integer world coords and returns a uniform 32-bit value
 // keyed off coordinates that do not move with the camera, so blade placement is stable
@@ -131,6 +133,11 @@ static const float grass_max_boost = 12.0f;
 // how far above its own gate the biome mask has to climb before a slot runs at full density, a
 // narrow band here is what keeps meadow cores thick while the mask edges still fade out
 static const float grass_biome_gain = 0.25f;
+// share of the edge fringe amount that also punches bare scars through a pocket interior, a clean
+// edged pocket with a pockmarked middle would read as two unrelated effects. mirrored on the cpu
+static const float grass_patch_scar_ratio = 0.3f;
+// terrain_layer_max, the dominant layer index in the mask alpha can never exceed this
+static const uint grass_ground_layer_max = 8u;
 
 // four octaves, the fewest that still reads as an organic outline rather than a blob
 float grass_fbm(float2 p, uint seed)
@@ -381,7 +388,10 @@ void main_cs(uint3 dispatch_thread_id : SV_DispatchThreadID)
     bool  patch_invert      = patch_size_signed < 0.0f;
     float patch_coverage    = saturate(buffer_pass.values[3].y);
     float patch_edge        = saturate(buffer_pass.values[3].z);
-    float patch_scar        = saturate(buffer_pass.values[3].w);
+    // the knob that frays the outline also breaks the interior, one is a fixed fraction of the other
+    // so it is derived here rather than pushed, which frees the float for the ground type bits
+    float patch_scar        = patch_edge * grass_patch_scar_ratio;
+    uint  ground_mask       = (uint)buffer_pass.values[3].w;
 
     uint  packed_index  = buffer_pass.draw_index;
     uint  lod_index     = packed_index & 0xFu;
@@ -589,7 +599,7 @@ void main_cs(uint3 dispatch_thread_id : SV_DispatchThreadID)
     // biome mask, same uv as the heightfield, the slot picks the channel it is gated on
     // is_transparent carries biome_min as float bits, negative disables the gate
     float biome_min = asfloat(buffer_pass.is_transparent);
-    if (biome_min >= 0.0f)
+    if (biome_min >= 0.0f || ground_mask != 0u)
     {
         // the mask is baked at its own resolution, so it needs its own texel centre rebase
         uint mask_w;
@@ -600,22 +610,44 @@ void main_cs(uint3 dispatch_thread_id : SV_DispatchThreadID)
             terrain_world_to_normalized(world_xz),
             float2(mask_w, mask_h)
         );
-        float4 mask     = tex3.SampleLevel(samplers[sampler_bilinear_clamp], mask_uv, 0);
-        float grass_w   = mask_channel == 0u ? mask.r : (mask_channel == 1u ? mask.g : mask.b);
-        float slope_fit = saturate((surface_normal.y - max_slope_cos) / max(1.0f - max_slope_cos, 1e-4f));
-        if (grass_w < biome_min)
+
+        // ground type gate, the same bitfield the mesh placer reads. the dominant surface layer rides
+        // in alpha as an index rather than a weight, so it takes a point tap, a bilinear one across the
+        // boundary between two layers averages out to a value that names a third
+        if (ground_mask != 0u)
         {
-            return;
+            float index_a = tex3.SampleLevel(samplers[sampler_point_clamp], mask_uv, 0).a;
+            uint  dominant = min(
+                (uint)(index_a * 255.0f + 0.5f),
+                grass_ground_layer_max - 1u
+            );
+            if ((ground_mask & (1u << dominant)) == 0u)
+            {
+                return;
+            }
         }
 
-        // the mask decides where grass can live, the patch field above decides where it did, so the
-        // mask is remapped to saturate just past its own gate instead of being used as the density
-        // directly. a meadow core reading 0.6 used to throw away four blades in ten for nothing
-        float ground = saturate((grass_w - biome_min) / grass_biome_gain) * slope_fit;
-        float biome_roll = hash_unit(hash_mix(h0 ^ 0x27d4eb2du));
-        if (biome_roll > ground)
+        // a slot with the biome set to ignore still wants the ground gate above, so this is nested
+        // rather than being the condition on the whole block
+        if (biome_min >= 0.0f)
         {
-            return;
+            float4 mask     = tex3.SampleLevel(samplers[sampler_bilinear_clamp], mask_uv, 0);
+            float grass_w   = mask_channel == 0u ? mask.r : (mask_channel == 1u ? mask.g : mask.b);
+            float slope_fit = saturate((surface_normal.y - max_slope_cos) / max(1.0f - max_slope_cos, 1e-4f));
+            if (grass_w < biome_min)
+            {
+                return;
+            }
+
+            // the mask decides where grass can live, the patch field above decides where it did, so the
+            // mask is remapped to saturate just past its own gate instead of being used as the density
+            // directly. a meadow core reading 0.6 used to throw away four blades in ten for nothing
+            float ground = saturate((grass_w - biome_min) / grass_biome_gain) * slope_fit;
+            float biome_roll = hash_unit(hash_mix(h0 ^ 0x27d4eb2du));
+            if (biome_roll > ground)
+            {
+                return;
+            }
         }
     }
 

source/editor/widgets/TerrainEditor.cpp

@@ -1574,7 +1574,7 @@ void TerrainEditor::DrawAnalysis(Terrain* terrain)
 
         draw_map("wear, sun, talus", terrain->GetAnalysisMapB(), size, "red is bedrock wear, green is insolation, blue is normalised height, alpha is talus scree");
         ImGui::SameLine(0.0f, design::spacing_lg);
-        draw_map("grass, trees, rocks", terrain->GetPropMask(), size, "the biome mask, props only spawn where their channel is bright");
+        draw_map("grass, trees, rocks", terrain->GetPropMask(), size, "the biome mask, props only spawn where their channel is bright, alpha carries the dominant ground layer index");
 
         if (!terrain->GetAnalysisMapA())
         {

source/rendering/Renderer.h

@@ -151,6 +151,9 @@ namespace spartan
             float max_slope_deg      = 45.0f;
             float biome_min_weight   = 0.2f;
             uint32_t mask_channel    = 0;    // which prop mask channel gates the slot, 0 grass, 1 trees, 2 rocks
+            // ground type gate, bit i allows surface layer i, 0 allows every layer. the dominant layer
+            // arrives in the prop mask alpha, so this needs the mask bound even with no biome channel
+            uint32_t ground_mask     = 0;
             float density            = 1.0f;
             float size_min           = 0.8f; // world scale on the mesh, one roll per instance inside the range
             float size_max           = 1.2f;

source/rendering/Renderer_Passes_Geometry.cpp

@@ -1433,7 +1433,9 @@ namespace spartan
                     m_pcb_pass_cpu.v[12] = patch_push;
                     m_pcb_pass_cpu.v[13] = state.params.patch_coverage;
                     m_pcb_pass_cpu.v[14] = state.params.patch_edge;
-                    m_pcb_pass_cpu.v[15] = state.params.patch_scar;
+                    // the scar amount is always a fixed fraction of the edge, so the shader derives it
+                    // and this float carries the ground type bits instead, every other one is taken
+                    m_pcb_pass_cpu.v[15] = static_cast<float>(state.params.ground_mask);
                     RHI_CommandList::PushConstants(m_pcb_pass_cpu);
 
                     // one cell per thread, dispatch z carries the instance index inside the cell, the

source/world/WorldHelpers.cpp

@@ -827,7 +827,7 @@ namespace spartan
             // a layer that gates on a mask channel cannot run without the mask, a layer that ignores it
             // does not care, which is what lets micro detail cover ground no biome claimed
             RHI_Texture* prop_mask = terrain->GetPropMask();
-            if (!prop_mask && layer.mask_channel >= 0)
+            if (!prop_mask && (layer.mask_channel >= 0 || layer.ground_mask != 0))
             {
                 SP_LOG_WARNING("terrain scatter '%s': no biome mask, gpu scatter disabled", layer.name.c_str());
                 return false;
@@ -880,6 +880,9 @@ namespace spartan
             // a mask channel of -1 turns the gate off, which is what detail wants, a chip belongs anywhere
             params.biome_min_weight = layer.mask_channel >= 0 ? layer.mask_min : -1.0f;
             params.mask_channel = layer.mask_channel >= 0 ? static_cast<uint32_t>(layer.mask_channel) : 0u;
+            // the ground type gate used to stop at the mesh layers, so ticking sand on grass or pebbles
+            // changed a value the gpu never saw
+            params.ground_mask = layer.ground_mask;
             params.density = clamp(layer.density, 0.01f, 1.0f);
             // the gpu rolls one size per instance the same way the cpu placer does
             params.size_min = layer.mesh_scale * min(layer.size_min, layer.size_max);
@@ -903,7 +906,9 @@ namespace spartan
             params.patch_size_m   = max(layer.clump_radius, 0.0f);
             params.patch_edge     = clamp(layer.clump_raggedness, 0.0f, 1.0f);
             // the same knob that frays the outline breaks up the interior, a clean edged pocket with a
-            // pockmarked middle would read as two unrelated effects
+            // pockmarked middle would read as two unrelated effects. this is no longer pushed, the
+            // shader derives it from the edge with the same ratio, so grass_patch_scar_ratio in
+            // grass_populate.hlsl has to track this number. it still feeds the cpu density boost
             params.patch_scar     = params.patch_edge * 0.3f;
             params.patch_invert   = layer.clump_invert;
 

source/world/components/Terrain.cpp

@@ -7582,10 +7582,12 @@ namespace spartan
                 m_prop_mask_pixels[offset + 0] = static_cast<uint8_t>(grass * 255.0f + 0.5f);
                 m_prop_mask_pixels[offset + 1] = static_cast<uint8_t>(trees * 255.0f + 0.5f);
                 m_prop_mask_pixels[offset + 2] = static_cast<uint8_t>(rock * 255.0f + 0.5f);
-                m_prop_mask_pixels[offset + 3] = 255;
-                // which surface layer won this point, it stays off the texture so the preview and the
-                // grass populate pass keep reading an opaque rgb mask
-                m_layer_dominant[i] = static_cast<uint8_t>(dominant_layer);
+                // which surface layer won this point. the mesh placer reads it off the cpu copy below,
+                // the gpu scatter pass reads it out of alpha, which is what lets a ground type gate
+                // apply to grass and detail instead of only to mesh layers. it is an index and not a
+                // weight, so anything sampling it has to use a point tap
+                m_prop_mask_pixels[offset + 3] = static_cast<uint8_t>(dominant_layer);
+                m_layer_dominant[i]            = static_cast<uint8_t>(dominant_layer);
             }
         };
         ThreadPool::ParallelLoop(bake, static_cast<uint32_t>(cell_count));