feat(render3d): contact darkening, so things sit ON the ground

The existing occlusion is tuned as AMBIENT occlusion: a wide radius answering "how open is
the sky here". That is the right question, and it leaves every object in the frame
hovering - because what says a log is ON the ground rather than in front of it is a hard,
narrow darkening in the last few centimetres where the two meet, and at a metre and a half
of radius that darkening is spread so thin it is not there.

A second, tight pass: eight taps inside 40 cm, which at any normal distance is a handful of
pixels and stays in cache, with a much tighter range check than the ambient one so a wall
across the room does not darken the floor in front of it.

Small by frame area, because contact occlusion is - 1.8% of the frame, 7% of the region
around the things it grounds. GL 7.0 -> 7.1 s, VK 7.3 s over 400 frames.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/ludic.render3d/post.ludic

@@ -50,6 +50,7 @@ var post_ao_blur: Target = null
 var post_p_ao: int = 0
 var post_p_ao_blur: int = 0
 var post_ao_radius: int = 0
+var post_contact: int = 0x3FA00000   # 1.25: how hard a thing is darkened where it meets the ground
 var post_ao_intensity: int = 0
 var post_ao_strength: int = 0
 var post_gi_strength: int = 0x3ECCCCCD     # 0.4
@@ -297,6 +298,9 @@ function post_ssao_pass() -> void {
   u_f2(gpu_uniform(post_p_ao, "u_texel"), fr(1, post_w), fr(1, post_h))
   u_f(gpu_uniform(post_p_ao, "u_radius"), post_ao_radius)
   u_f(gpu_uniform(post_p_ao, "u_intensity"), post_ao_intensity)
+  var contact = post_contact
+  if r3d_env_has("R3D_NOCONTACT") { contact = F_ZERO }
+  u_f(gpu_uniform(post_p_ao, "u_contact"), contact)
   mesh_draw(post_fs)
   target_bind(post_ao_blur)
   gpu_use_program(post_p_ao_blur)

packages/ludic.render3d/shaders/spv/manifest.txt

@@ -469,7 +469,7 @@ T 3e4b62f9 u_shadow 7
 T 3e4b62f9 u_tershadow 8
 T 3e4b62f9 u_ts_height 9
 P 676965ab fullscreen.vert ssgi.frag 
-B 676965ab frag 1 980
+B 676965ab frag 1 984
 U 676965ab frag u_cascade_vp 0 mat4 5 64
 U 676965ab frag u_cascade_split 320 float 5 16
 U 676965ab frag u_cascade_range 400 float 5 16
@@ -509,7 +509,8 @@ U 676965ab frag u_proj 896 mat4 1 0
 U 676965ab frag u_texel 960 vec2 1 0
 U 676965ab frag u_radius 968 float 1 0
 U 676965ab frag u_intensity 972 float 1 0
-U 676965ab frag u_frame 976 float 1 0
+U 676965ab frag u_contact 976 float 1 0
+U 676965ab frag u_frame 980 float 1 0
 T 676965ab u_brdf 2
 T 676965ab u_depth 3
 T 676965ab u_irradiance 4

packages/ludic.render3d/shaders/ssgi.frag

@@ -9,6 +9,7 @@ uniform mat4 u_proj;
 uniform vec2 u_texel;
 uniform float u_radius;
 uniform float u_intensity;
+uniform float u_contact;    // the tight contact pass; 0 switches it off entirely
 uniform float u_frame;
 vec3 viewPos(vec2 uv) {
   float d = texture(u_depth, uv).r;
@@ -59,6 +60,36 @@ void main() {
     }
   }
   ao = 1.0 - u_intensity * ao / float(S);
+  // ---- CONTACT -----------------------------------------------------------------------
+  // The occlusion above is tuned as AMBIENT occlusion: a wide radius that answers "how open
+  // is the sky here". It is the right question and it leaves every object in the frame
+  // hovering, because the thing that says a log is ON the ground rather than in front of it
+  // is a hard, narrow darkening in the last few centimetres where the two meet - and at a
+  // metre and a half of radius that darkening is spread so thin it is not there.
+  //
+  // So a second, tight pass. It is cheap because it is SHORT: eight taps inside a quarter of
+  // a metre, which at any normal distance is a handful of pixels and stays in cache.
+  if (u_contact > 0.0) {
+    float cao = 0.0;
+    const int CS = 8;
+    float crad = 0.40 * (1.0 + 0.004 * -P.z);
+    for (int i = 0; i < CS; i++) {
+      float a2 = (float(i) + noise) * 2.3999632;
+      float r2 = sqrt((float(i) + 0.5 + noise) / float(CS));
+      vec3 dir2 = vec3(cos(a2) * r2, sin(a2) * r2, sqrt(max(0.0, 1.0 - r2 * r2)));
+      vec3 s2 = P + (t * dir2.x + b * dir2.y + N * dir2.z) * crad;
+      vec4 c2 = u_proj * vec4(s2, 1.0);
+      vec2 uv2 = c2.xy / c2.w * 0.5 + 0.5;
+      if (uv2.x < 0.0 || uv2.x > 1.0 || uv2.y < 0.0 || uv2.y > 1.0) continue;
+      float sz2 = viewPos(uv2).z;
+      // a tight range check: only something genuinely touching counts, or a wall across the
+      // room darkens the floor in front of it
+      float rc2 = smoothstep(0.0, 1.0, crad / max(abs(P.z - sz2), 1e-4));
+      cao += (sz2 >= s2.z + 0.004 * crad ? 1.0 : 0.0) * rc2;
+    }
+    cao = 1.0 - u_contact * cao / float(CS);
+    ao = min(ao, clamp(cao, 0.0, 1.0));
+  }
   float fade = smoothstep(120.0, 350.0, -P.z);
   ao = mix(clamp(ao, 0.0, 1.0), 1.0, fade);
   gi = (giW > 0.0 ? gi / float(S) : vec3(0.0)) * (1.0 - fade);