Research shaders for compositor ops

documents/session-logs/2026-08-09.md

@@ -0,0 +1,59 @@
+# Session Log — 2026-08-09
+
+## Background colour change (blit shader)
+
+- User requested changing the letterbox/pillarbox background from black to neutral grey.
+- Initial attempt: changed the render pass clear color to `(0.5, 0.5, 0.5, 1.0)`. This
+  triggered the NVIDIA validation layer warning
+  `BestPractices-NVIDIA-ClearColor-NotCompressed` — SRGB fast clears only work
+  with 0.0 or 1.0 on NVIDIA tile-based GPUs.
+- Reverted the clear color and implemented the proper solution: draw a fullscreen
+  grey quad in the fragment shader before the texture quad. The render pass clear
+  stays at 0.0 (fast-compressed).
+- Added `mode` field to `BlitData` push constant. Mode 0 samples the texture, mode
+  1 outputs solid grey.
+- User noted that a branch in the shader is free (no warp divergence since `mode`
+  is uniform per draw call). Agreed — no need for a separate clear pipeline.
+- Changed grey from 0.5 to 0.18 (18% grey card, standard in photography/compositing).
+- Fixed a Slang compilation warning by updating the profile from `spirv_1_4` to
+  `spirv_1_6` and explicitly declaring the required capabilities.
+
+## Shader filter node research
+
+- User requested research on: Gaussian blur, CDL, Laplacian, Sobel, sharpen,
+  posterize, pixelize, Kuwahara.
+- Launched a research agent that produced `documents/research/shader-filters.md`
+  covering all filters with formulas, Slang pseudocode, parameter tables, and
+  performance notes.
+
+## Design decisions made during review
+
+1. **Colour space**: all intermediate textures are linear float
+   (`R16G16B16A16_SFLOAT`, `R32G32B32A32_SFLOAT` for Kuwahara tensor). sRGB images
+   are linearized once at load by the Read node. Final blit to sRGB swapchain
+   handles display encoding.
+
+2. **Alpha**: premultiplied everywhere by default. Explicit Unpremult/Premult
+   nodes for operations that need unpremultiplied values (Nuke model).
+
+3. **Edge handling**: per-node parameter, clamp-to-edge default, clamp-to-border
+   option. Affects sampler state, not shader branches.
+
+4. **Premult has no parameters**: removed the empty push constant struct.
+
+## Research document fixes
+
+- Fixed a contradictory sentence about push constant sizes and CDL block size.
+- Added Unpremult (§9) and Premult (§10) sections with full implementations.
+- Added `edge_mode` field to all 5 spatial filter push constant blocks (Gaussian,
+  Laplacian, Sobel, Sharpen, Kuwahara).
+- Restructured the implications section (§12) into open items vs resolved decisions.
+- Expanded all mathematics sections with plain-language explanations suitable for
+  someone without a strong math background.
+
+## Open items for next session
+
+- Begin implementing the actual shader nodes in Prism
+- Node system needs: per-pass resource signatures, scratch texture hooks, per-node
+  sampler choice, compile-time-bounded loop limits
+- Classic Kuwahara is the recommended first implementation (single pass)