From 9d114ae4fec465baed381de7782ef42ca77e734b Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sun, 8 Mar 2026 09:13:57 +0100
Subject: fix(shaders): enforce y-up screen-space convention + document
 coordinate conventions

- Add textureSampleYUp() helper to fullscreen_uv_vs.wgsl to correct
  y-flip when sampling WebGPU textures with y-up UV coordinates
- Use textureSampleYUp() in passthrough, gaussian_blur, combined_postprocess
- Fix skybox.wgsl: remove erroneous (1.0 - uv.y) flip (double-flip bug)
- Document world/view/screen conventions in doc/3D.md, camera_common.wgsl,
  and fullscreen_uv_vs.wgsl

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 doc/3D.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

(limited to 'doc')

diff --git a/doc/3D.md b/doc/3D.md
index ac451c8..c27b034 100644
--- a/doc/3D.md
+++ b/doc/3D.md
@@ -1,5 +1,29 @@
 # 3D System and Rendering Pipeline
 
+## Coordinate Conventions
+
+### World Space: Z-up, Y-forward
+- X = right
+- Y = forward
+- Z = up
+- `look_at` up parameter: `{0, 0, 1}`
+- Camera default position: along +Y axis, looking toward origin
+
+### View Space: X-right, Y-up, -Z-forward (standard NDC)
+- Camera looks down **-Z** in view space
+- `perspective()` encodes this via `m[11] = -1`
+- Independent of world-space convention — set by `look_at` construction
+
+### Screen Space: Y-up, origin at bottom-left
+- `uv` in `[0,1]`: `(0,0)` = bottom-left, `(1,1)` = top-right
+- `st` in `[-1,1]`: NDC directly, y-up
+- WebGPU textures are y-down `(0,0)` at top — use `textureSampleYUp()` when sampling with `uv`
+
+### NDC → Screen
+- WebGPU NDC: y-up (`+1` = top)
+- WebGPU framebuffer: y-down (pixel row 0 at top)
+- `uv.y = 0` → NDC `y = -1` → bottom of framebuffer ✓
+
 ## Core Concept
 
 Hybrid SDF/rasterization pipeline with physics and collision detection.
-- 
cgit v1.2.3