webgpu improvements

interfaces/Crafter.Graphics-WebGPUBuffer.cppm

@@ -78,6 +78,60 @@ export namespace Crafter {
         void FlushDevice() requires(Mapped) {
             WebGPU::wgpuWriteBuffer(handle, this->value, static_cast<std::int32_t>(size));
         }
+        // Partial upload — write the bytes [srcByteOffset, srcByteOffset+byteCount)
+        // of the host mirror to GPU offset `dstByteOffset`. BuildTLAS uses
+        // this to leave the GPU-owned transform field of an RTInstance
+        // intact (the physics-tlas-transform compute shader is its sole
+        // writer) while still pushing the CPU-side metadata fields.
+        void FlushDeviceRange(std::uint32_t dstByteOffset,
+                              std::uint32_t srcByteOffset,
+                              std::uint32_t byteCount) requires(Mapped) {
+            const auto* base = reinterpret_cast<const char*>(this->value);
+            WebGPU::wgpuWriteBufferRange(handle, dstByteOffset,
+                                          base + srcByteOffset,
+                                          static_cast<std::int32_t>(byteCount));
+        }
+
+        // Push one element's worth of bytes from the host mirror to GPU.
+        // Use when a single SoA slot was mutated (body construction,
+        // per-instance flag flip) and a full FlushDevice would clobber
+        // the GPU-side updates the sim has applied to neighboring slots.
+        void FlushDeviceSlot(std::uint32_t idx) requires(Mapped) {
+            constexpr std::uint32_t kStride = sizeof(T);
+            const std::uint32_t off = idx * kStride;
+            FlushDeviceRange(off, off, kStride);
+        }
+
+        // Schedule a GPU→CPU readback of this buffer's entire contents.
+        // Asynchronous; data isn't ready until a later PollReadback
+        // returns true. Successive Enqueues without a Poll are dropped
+        // — they're a no-op while the previous map is in flight.
+        //
+        // `resetBytes` ≥ 0 — if non-zero, the first `resetBytes` bytes
+        // of THIS buffer are clearBuffer-cleared on the GPU command
+        // encoder immediately after the copy, so the readback captures
+        // the pre-clear bytes and the next frame's writers see zeros.
+        // The reset is tied to a successful enqueue (skipped enqueue =
+        // skipped reset), preserving accumulated state across missed
+        // drains.
+        void EnqueueReadback(std::uint32_t resetBytes = 0) {
+            WebGPU::wgpuReadbackEnqueue(handle,
+                                         static_cast<std::int32_t>(size),
+                                         static_cast<std::int32_t>(resetBytes));
+        }
+        // Try to copy the readback bytes into this->value. Returns true
+        // if the previous EnqueueReadback resolved and the data is now
+        // mirrored into .value; false if the map is still pending.
+        bool PollReadback() requires(Mapped) {
+            return WebGPU::wgpuReadbackPoll(handle, this->value,
+                                             static_cast<std::int32_t>(size)) != 0;
+        }
+        // Non-consuming readiness probe. Returns true if a subsequent
+        // PollReadback would succeed without changing state otherwise.
+        // Use to verify a sibling buffer is also ready before consuming.
+        bool IsReadbackReady() const {
+            return WebGPU::wgpuReadbackReady(handle) != 0;
+        }
 
         ~WebGPUBuffer() { Clear(); }
     };