feat(webgpu): HDR post-process primitives — float textures, storage-texture bindings, RESOLVE→HDR target (#27)

Adds the minimal WebGPU-backend surface an HDR bloom/post chain needs:

1. wgpuCreateStorageImage2D + StorageImage2D<>: runtime rgba16float (or
   other format) textures with STORAGE_BINDING|TEXTURE_BINDING usage, no
   CompressedTextureAsset upload — GPU-produced HDR targets.
2. UICustomBindingKind::StorageTexture (kind 5): write-only storage-texture
   binding carrying a texel format (the freed UICustomBinding::format byte),
   wired through all three binding paths (UI custom / RT / plain compute).
   Float textures already sample via SampledTexture (sampleType float).
3. PipelineRTWebGPU::Init(..., hdrOutputFormat): RESOLVE writes the linear
   accumulator into a user rgba16float texture (RTPass::outTexHandle)
   instead of the rgba8unorm canvas, leaving the composite→swapchain pass to
   the app. Default RGBA8Unorm keeps the canvas path byte-identical.

Existing RT examples updated for the _pad→format field rename; the default
paths are unchanged (verified RTStress builds + renders).

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

interfaces/Crafter.Graphics-Image2D.cppm

@@ -47,8 +47,48 @@ import std;
 import Crafter.Asset;
 import :DescriptorHeapWebGPU;
 import :WebGPU;
+import :WebGPUComputeShader;   // WebGPUTexelFormat
 
 export namespace Crafter {
+    // GPU-produced 2D texture with STORAGE_BINDING + TEXTURE_BINDING usage
+    // and a runtime-chosen format. The HDR post-process building block: an
+    // rgba16float target a compute pass can write through a StorageTexture
+    // binding and a later pass can sample through a SampledTexture binding.
+    // No CompressedTextureAsset / CPU upload — content comes from the GPU.
+    // Distinct from Image2D<T> (rgba8unorm, sampled-only, asset-upload).
+    class StorageImage2D {
+    public:
+        WebGPUTextureRef  handle = 0;
+        std::uint16_t     width  = 0;
+        std::uint16_t     height = 0;
+        WebGPUTexelFormat format = WebGPUTexelFormat::RGBA16Float;
+
+        void Create(std::uint16_t w, std::uint16_t h,
+                    WebGPUTexelFormat fmt = WebGPUTexelFormat::RGBA16Float) {
+            width  = w;
+            height = h;
+            format = fmt;
+            handle = WebGPU::wgpuCreateStorageImage2D(
+                w, h, static_cast<std::int32_t>(fmt));
+        }
+
+        // Register in a heap image slot so a UI custom shader can bind it
+        // via UICustomBinding (SampledTexture to read, StorageTexture to
+        // write). PlainComputeShader / RTPass take the raw `handle` directly.
+        ImageSlot AllocateSlot(DescriptorHeapWebGPU& heap) {
+            DescriptorRange r = heap.AllocateImageSlots(1);
+            heap.imageTable[r.firstElement] = handle;
+            return ImageSlot(&heap, r.firstElement);
+        }
+
+        void Destroy() {
+            if (handle != 0) {
+                WebGPU::wgpuDestroyTexture(handle);
+                handle = 0;
+            }
+        }
+    };
+
     template <typename PixelType>
     class Image2D {
     public:

interfaces/Crafter.Graphics-PipelineRTWebGPU.cppm

@@ -36,6 +36,10 @@ export namespace Crafter {
         // RTPass to consult when packing the handles[] array at dispatch
         // time (one resolved u32 handle per binding, in declaration order).
         std::vector<UICustomBinding> userBindings;
+        // True when Init was given a non-default hdrOutputFormat: RESOLVE
+        // writes a user storage texture instead of the canvas, and RTPass
+        // must supply its handle via RTPass::outTexHandle.
+        bool hdrOutput = false;
 
         // Build the megakernel pipeline. Groups carry indices into
         // `sbt.shaders`. The library generates one `case` per registered
@@ -45,12 +49,19 @@ export namespace Crafter {
         // `userBindings` declares extra @group(2)+ resources the user's
         // closest-hit / miss / raygen WGSL touches (material SSBOs,
         // albedo textures, samplers).
+        // `hdrOutputFormat` defaults to RGBA8Unorm — the canvas ping-pong
+        // path, unchanged. Pass RGBA16Float (or another float format) to
+        // have RESOLVE write the linear accumulator into a user storage
+        // texture instead, for an HDR post-process chain. The app then owns
+        // the composite→swapchain pass and must set RTPass::outTexHandle.
         void Init(WebGPUCommandEncoderRef                 cmd,
                   std::span<const RTShaderGroup>          raygenGroups,
                   std::span<const RTShaderGroup>          missGroups,
                   std::span<const RTShaderGroup>          hitGroups,
                   const ShaderBindingTableWebGPU&         sbt,
-                  std::span<const UICustomBinding>        bindings = {});
+                  std::span<const UICustomBinding>        bindings = {},
+                  WebGPUTexelFormat                       hdrOutputFormat
+                      = WebGPUTexelFormat::RGBA8Unorm);
 
         PipelineRTWebGPU() = default;
         PipelineRTWebGPU(const PipelineRTWebGPU&) = delete;

interfaces/Crafter.Graphics-RTPass.cppm

@@ -97,6 +97,12 @@ export namespace Crafter {
         // bounce; etc. The library unrolls GENERATE; (PREP; TRACE; SHADE)
         // ×maxDepth; RESOLVE.
         std::uint32_t     maxDepth     = 1;
+        // Destination storage-texture handle for an HDR-output pipeline
+        // (one Init'd with a non-default hdrOutputFormat). RESOLVE writes
+        // the linear accumulator here instead of the canvas; the app runs
+        // its own composite→swapchain pass afterwards. Ignored (0) for the
+        // default canvas path.
+        std::uint32_t     outTexHandle = 0;
 
         RTPass(PipelineRTWebGPU* p) : pipeline(p) {}
 
@@ -114,7 +120,8 @@ export namespace Crafter {
                 static_cast<std::int32_t>(gy),
                 handlesPtr,
                 static_cast<std::int32_t>(handlesCount),
-                static_cast<std::int32_t>(maxDepth));
+                static_cast<std::int32_t>(maxDepth),
+                outTexHandle);
         }
     };
 }

interfaces/Crafter.Graphics-WebGPU.cppm

@@ -109,6 +109,17 @@ namespace Crafter::WebGPU {
                                           const void* srcPtr, std::int32_t byteSize,
                                           std::int32_t w, std::int32_t h);
 
+    // Runtime storage texture — STORAGE_BINDING | TEXTURE_BINDING usage,
+    // caller-chosen format (`format` is the WebGPUTexelFormat enum, e.g.
+    // 1 = rgba16float). Unlike wgpuCreateImage2D this needs no
+    // CompressedTextureAsset upload: the content is produced on the GPU
+    // (e.g. an HDR post-process target a compute pass writes via a
+    // StorageTexture binding and later samples via SampledTexture). Backs
+    // StorageImage2D<T> in :Image2D.
+    __attribute__((import_module("env"), import_name("wgpuCreateStorageImage2D")))
+    extern "C" std::uint32_t wgpuCreateStorageImage2D(std::int32_t w, std::int32_t h,
+                                                      std::int32_t format);
+
     __attribute__((import_module("env"), import_name("wgpuCreateLinearClampSampler")))
     extern "C" std::uint32_t wgpuCreateLinearClampSampler();
 
@@ -190,10 +201,16 @@ namespace Crafter::WebGPU {
     // UICustomBinding-shaped (8 bytes each) declaring extra @group(2)+
     // resources the user's closest-hit / miss / raygen WGSL references.
     // Pass (nullptr, 0) for a pipeline with no user-declared bindings.
+    // `hdrOutputFormat` (0 = none) makes the RESOLVE stage write the linear
+    // accumulator into a user-supplied storage texture of that
+    // WebGPUTexelFormat (e.g. 1 = rgba16float) instead of the rgba8unorm
+    // canvas ping-pong — the entry point for an HDR post-process chain. The
+    // matching output texture handle is passed to wgpuDispatchRT.
     // Returns an opaque pipeline handle.
     __attribute__((import_module("env"), import_name("wgpuLoadRTPipeline")))
     extern "C" std::uint32_t wgpuLoadRTPipeline(const void* wgslPtr, std::int32_t wgslLen,
-                                                const void* bindingsPtr, std::int32_t bindingsCount);
+                                                const void* bindingsPtr, std::int32_t bindingsCount,
+                                                std::int32_t hdrOutputFormat);
 
     // Dispatch a TraceRays-equivalent pass: the RT pipeline is dispatched
     // over a (gx, gy) tile grid; the library writes the push data (camera,
@@ -202,6 +219,9 @@ namespace Crafter::WebGPU {
     // `handles[]` carries resolved WebGPU resource handles for every user
     // binding declared at pipeline-load time, in the same order. Pass
     // (nullptr, 0) for a pipeline with no user bindings.
+    // `outTexHandle` is the destination texture for an HDR-output pipeline
+    // (one loaded with hdrOutputFormat != 0); ignored (pass 0) for the
+    // default canvas path.
     __attribute__((import_module("env"), import_name("wgpuDispatchRT")))
     extern "C" void wgpuDispatchRT(std::uint32_t pipelineHandle,
                                    const void* pushPtr, std::int32_t pushBytes,
@@ -209,7 +229,8 @@ namespace Crafter::WebGPU {
                                    std::int32_t  instanceCount,
                                    std::int32_t  gx, std::int32_t gy,
                                    const void* handlesPtr, std::int32_t handlesCount,
-                                   std::int32_t maxDepth);
+                                   std::int32_t maxDepth,
+                                   std::uint32_t outTexHandle);
 
     // GPU TLAS-build dispatch. Two sequential compute passes:
     //   1. tlasBuildMain — per-instance world AABB + identity permutation

interfaces/Crafter.Graphics-WebGPUComputeShader.cppm

@@ -31,6 +31,16 @@ import std;
 import :WebGPU;
 
 export namespace Crafter {
+    // Texel format for runtime-allocated textures and write-only storage-
+    // texture bindings. Values are the wire contract with dom-webgpu.js's
+    // texelFormatStr(); keep them in sync. rgba8unorm (0) is the default so
+    // an unset `format` byte preserves prior behaviour.
+    enum class WebGPUTexelFormat : std::uint8_t {
+        RGBA8Unorm  = 0,
+        RGBA16Float = 1,   // HDR post-process targets — filterable per spec
+        R32Float    = 2,
+    };
+
     enum class UICustomBindingKind : std::uint8_t {
         Buffer              = 0,   // read-only-storage SSBO, handle is a slot into heap.bufferTable
         SampledTexture      = 1,   // sampled texture_2d<f32>, handle is a slot into heap.imageTable
@@ -41,13 +51,20 @@ export namespace Crafter {
         // integrate node momentum, write brace stress, or output TLAS
         // instance transforms.
         BufferReadWrite     = 4,
+        // write-only storage texture (texture_storage_2d<FMT, write> in
+        // WGSL). The `format` field carries the WebGPUTexelFormat. Lets a
+        // compute pass write a user-owned texture (e.g. an rgba16float bloom
+        // mip) at an arbitrary group/binding — the missing primitive for an
+        // HDR mip pyramid. Bind the same texture as SampledTexture to read
+        // it back in a later pass.
+        StorageTexture      = 5,
     };
 
     struct UICustomBinding {
         std::uint8_t  group;        // @group(N), must be >= 2 (0 and 1 are reserved)
         std::uint8_t  binding;      // @binding(N)
         UICustomBindingKind kind;
-        std::uint8_t  _pad;
+        std::uint8_t  format;       // WebGPUTexelFormat for StorageTexture; 0 otherwise
         std::uint32_t pushOffset;   // offset in push data where the slot uint32 lives
     };
     static_assert(sizeof(UICustomBinding) == 8);