From 77f9dbee1721518e09f0beed10b3dbb78d893b08 Mon Sep 17 00:00:00 2001
From: 3gg <3gg@shellblade.net>
Date: Fri, 13 Feb 2026 10:27:58 -0800
Subject: Ambient lighting. Defer texture filtering

---
 doc/lighting.md           | 64 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/pipeline.txt          | 15 +++++++++++
 doc/triangle-pipeline.txt | 27 ++++++++++++++++++++
 3 files changed, 106 insertions(+)
 create mode 100644 doc/lighting.md
 create mode 100644 doc/pipeline.txt
 create mode 100644 doc/triangle-pipeline.txt

(limited to 'doc')

diff --git a/doc/lighting.md b/doc/lighting.md
new file mode 100644
index 0000000..bc111b0
--- /dev/null
+++ b/doc/lighting.md
@@ -0,0 +1,64 @@
+# Lighting
+
+## Forward
+
+```
+for each triangle:
+    for each pixel:
+        for each light:
+            shade(pixel, light)
+```
+
+- Overdraw penalty.
+- Client must specify all lights (for the object) up front.
+
+## Deferred
+
+### Forward Pass
+
+The forward pass generates:
+- Depth
+- Texture ID
+- Texture coordinates
+
+Sampling of textures is deferred to avoid overdraw penalty.
+
+### Pixel-centric Shading
+
+```
+for each pixel:
+    for each light:
+        shade(pixel, light)
+```
+
+- Need a pixel-in-volume test.
+- Inefficient if most pixels are not affected by a light.
+  - Ok:  ambient, directional.
+  - Bad: point, area.
+
+### Light-centric Shading
+
+```
+for each light:
+    volume <- project light volume
+    for each pixel in volume:
+        shade(pixel, light)
+```
+
+- Need to project the light volume.
+- Shades only the pixels that are covered by the volume.
+- For ambient and directional, the volume is all space.
+
+## Clustered
+
+### Cluster Generation
+
+```
+for each light:
+    volume <- project light volume to NDC
+    for each cluster:
+        test(cluster, volume)
+```
+
+- Need a volume-AABB test (the cluster is an AABB in NDC space.)
+- Lighting then proceeds as in deferred.
diff --git a/doc/pipeline.txt b/doc/pipeline.txt
new file mode 100644
index 0000000..75bd69e
--- /dev/null
+++ b/doc/pipeline.txt
@@ -0,0 +1,15 @@
+@startuml
+:G-buffer;
+fork
+  :Depth;
+fork again
+  :Normal;
+fork again
+  :Tex coords;
+fork again
+  :Tex ID;
+end fork
+:Lighting;
+:Tone map;
+:Gamma correct;
+@enduml
diff --git a/doc/triangle-pipeline.txt b/doc/triangle-pipeline.txt
new file mode 100644
index 0000000..064cf5d
--- /dev/null
+++ b/doc/triangle-pipeline.txt
@@ -0,0 +1,27 @@
+@startuml
+:Triangles;
+:Vertices;
+if (Vertex cache?) then (hit)
+  :Load vertex;
+else (miss)
+  :Transform & Store vertex;
+endif
+:Transformed triangle (clip space);
+:Clip;
+:2D triangles;
+:Backface cull;
+:Rasterize;
+:Pixels;
+if (Depth test?) then (pass)
+  if (Alpha mask?) then (opaque)
+    :Write pixel;
+  else (transparent)
+    :Discard;
+    stop
+  endif
+else (fail)
+  :Discard;
+  stop
+endif
+stop
+@enduml
-- 
cgit v1.2.3