Img2Num C++ (Internal Developer Docs) dev
API Documentation
Loading...
Searching...
No Matches
gpu_utils.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 Img2Num Contributors
2// SPDX-License-Identifier: MIT
3
4#ifndef IMG2NUM_GPU_UTILS_H
5#define IMG2NUM_GPU_UTILS_H
6
18
19#if defined(__EMSCRIPTEN__)
20#include <emscripten/emscripten.h>
21#endif
22
23#include "internal/gpu.h"
24#include "internal/log.h"
25
26#include <cstddef>
27#include <cstdint>
28#include <cstring>
29#include <initializer_list>
30#include <mutex>
31#include <stdexcept>
32#include <string>
33#include <type_traits>
34#include <unordered_map>
35#include <vector>
36#include <webgpu/webgpu_cpp.h>
37
38namespace gpu {
39
40// =========================================================================
41// Color-space constants (shared across kernels)
42// =========================================================================
43
45static constexpr uint8_t COLOR_SPACE_CIELAB {0};
46static constexpr uint8_t COLOR_SPACE_RGB {1};
47
48// =========================================================================
49// cached_pipeline — pipeline caching wrapper
50// =========================================================================
51
61inline wgpu::ComputePipeline
62cached_pipeline(const std::string& shader_id, const std::string& label) {
63 // Pipelines belong to a device and every thread has its own device, so the
64 // cache is per thread too. No locking needed, and pipelines are released
65 // along with the thread's device when the thread exits.
66 thread_local std::unordered_map<std::string, wgpu::ComputePipeline> cache;
67
68 auto it = cache.find(shader_id);
69 if (it != cache.end()) {
70 return it->second;
71 }
72 wgpu::ComputePipeline pipeline = GPU::getClassInstance().createPipeline(shader_id, label);
73 cache[shader_id] = pipeline;
74 return pipeline;
75}
76
77// =========================================================================
78// map_and_wait — blocking readback primitive
79// =========================================================================
80
90inline const void* map_and_wait(wgpu::Buffer& buffer, size_t size) {
91 struct MapState {
92 bool done = false;
93 bool success = false;
94 };
95
96 MapState state;
97
98 wgpu::Future future = buffer.MapAsync(
99 wgpu::MapMode::Read, 0, size, GPU::wait_mode(),
100 [](wgpu::MapAsyncStatus status, wgpu::StringView /*msg*/, void* userdata) {
101 auto* s = static_cast<MapState*>(userdata);
102 s->done = true;
103 s->success = (status == wgpu::MapAsyncStatus::Success);
104 },
105 static_cast<void*>(&state)
106 );
107
108 GPU::getClassInstance().wait(future, state.done);
109
110 if (!state.success) {
111 throw std::runtime_error("gpu::map_and_wait: MapAsync failed");
112 }
113
114 const void* mapped = buffer.GetConstMappedRange(0, size);
115 if (!mapped) {
116 throw std::runtime_error("gpu::map_and_wait: GetConstMappedRange returned null");
117 }
118 return mapped;
119}
120
121// =========================================================================
122// Buffer<T> — RAII typed GPU buffer
123// =========================================================================
124
131template <typename T> class Buffer {
132 static_assert(std::is_trivially_copyable_v<T>, "Buffer<T>: T must be trivially copyable");
133
134 public:
138 Buffer(size_t count, wgpu::BufferUsage usage)
139 : count_(count)
140 , byte_size_(count * sizeof(T)) {
141 wgpu::BufferDescriptor desc {};
142 desc.size = byte_size_;
143 desc.usage = usage;
144 buffer_ = GPU::getClassInstance().get_device().CreateBuffer(&desc);
145 }
146
151 void write(const T* data, size_t count, size_t offset_elements = 0) {
152 GPU::getClassInstance().get_queue().WriteBuffer(
153 buffer_, offset_elements * sizeof(T), data, count * sizeof(T)
154 );
155 }
156
158 void write(const std::vector<T>& data) {
159 write(data.data(), data.size());
160 }
161
166 std::vector<T> read() {
167 // Create staging buffer
168 wgpu::BufferDescriptor staging_desc {};
169 staging_desc.size = byte_size_;
170 staging_desc.usage = wgpu::BufferUsage::MapRead | wgpu::BufferUsage::CopyDst;
171 wgpu::Buffer staging = GPU::getClassInstance().get_device().CreateBuffer(&staging_desc);
172
173 // Copy GPU buffer → staging
174 wgpu::CommandEncoder encoder = GPU::getClassInstance().get_device().CreateCommandEncoder();
175 encoder.CopyBufferToBuffer(buffer_, 0, staging, 0, byte_size_);
176 wgpu::CommandBuffer commands = encoder.Finish();
177 GPU::getClassInstance().get_queue().Submit(1, &commands);
178
179 // Map and wait
180 const void* mapped = map_and_wait(staging, byte_size_);
181
182 // Copy to vector
183 std::vector<T> result(count_);
184 std::memcpy(result.data(), mapped, byte_size_);
185
186 staging.Unmap();
187 staging.Destroy();
188 return result;
189 }
190
192 const wgpu::Buffer& handle() const {
193 return buffer_;
194 }
195
197 size_t byte_size() const {
198 return byte_size_;
199 }
200
202 size_t size() const {
203 return count_;
204 }
205
206 // Non-copyable
207 Buffer(const Buffer&) = delete;
208 Buffer& operator=(const Buffer&) = delete;
209
211 Buffer(Buffer&& other) noexcept
212 : buffer_(std::move(other.buffer_))
213 , count_(other.count_)
214 , byte_size_(other.byte_size_) {
215 other.buffer_ = nullptr;
216 other.count_ = 0;
217 other.byte_size_ = 0;
218 }
219
221 Buffer& operator=(Buffer&& other) noexcept {
222 if (this != &other) {
223 if (buffer_) {
224 buffer_.Destroy();
225 }
226 buffer_ = std::move(other.buffer_);
227 count_ = other.count_;
228 byte_size_ = other.byte_size_;
229 other.buffer_ = nullptr;
230 other.count_ = 0;
231 other.byte_size_ = 0;
232 }
233 return *this;
234 }
235
238 if (buffer_) {
239 buffer_.Destroy();
240 }
241 }
242
243 private:
244 wgpu::Buffer buffer_ {nullptr};
245 size_t count_ {0};
246 size_t byte_size_ {0};
247};
248
249// =========================================================================
250// Texture — RAII texture wrapper
251// =========================================================================
252
257class Texture {
258 public:
264 Texture(uint32_t width, uint32_t height, wgpu::TextureFormat format, wgpu::TextureUsage usage)
265 : width_(width)
266 , height_(height)
267 , format_(format) {
268 wgpu::TextureDescriptor desc {};
269 desc.size = {width, height, 1};
270 desc.format = format;
271 desc.usage = usage;
272 texture_ = GPU::getClassInstance().get_device().CreateTexture(&desc);
273 }
274
279 void write(const void* data, size_t data_size, uint32_t bytes_per_pixel) {
280 wgpu::TexelCopyTextureInfo dst {};
281 dst.texture = texture_;
282 wgpu::TexelCopyBufferLayout layout {};
283 layout.offset = 0;
284 layout.bytesPerRow = width_ * bytes_per_pixel;
285 layout.rowsPerImage = height_;
286 wgpu::Extent3D extent {width_, height_, 1};
287 GPU::getClassInstance().get_queue().WriteTexture(&dst, data, data_size, &layout, &extent);
288 }
289
296 std::vector<uint8_t> read(uint32_t bytes_per_pixel) {
297 uint32_t aligned_bpr = GPU::getAlignedBytesPerRow(width_, bytes_per_pixel);
298 uint32_t staging_size = aligned_bpr * height_;
299
300 // Create staging buffer
301 wgpu::BufferDescriptor staging_desc {};
302 staging_desc.size = staging_size;
303 staging_desc.usage = wgpu::BufferUsage::MapRead | wgpu::BufferUsage::CopyDst;
304 wgpu::Buffer staging = GPU::getClassInstance().get_device().CreateBuffer(&staging_desc);
305
306 // Encode copy
307 wgpu::CommandEncoder encoder = GPU::getClassInstance().get_device().CreateCommandEncoder();
308
309 wgpu::TexelCopyTextureInfo src {};
310 src.texture = texture_;
311 wgpu::TexelCopyBufferInfo dst {};
312 dst.buffer = staging;
313 dst.layout.bytesPerRow = aligned_bpr;
314 dst.layout.rowsPerImage = height_;
315 wgpu::Extent3D extent {width_, height_, 1};
316 encoder.CopyTextureToBuffer(&src, &dst, &extent);
317
318 wgpu::CommandBuffer commands = encoder.Finish();
319 GPU::getClassInstance().get_queue().Submit(1, &commands);
320
321 // Map and wait
322 const auto* mapped = static_cast<const uint8_t*>(map_and_wait(staging, staging_size));
323
324 // Strip row alignment padding
325 uint32_t tight_bpr = width_ * bytes_per_pixel;
326 std::vector<uint8_t> result(tight_bpr * height_);
327
328 for (uint32_t y = 0; y < height_; ++y) {
329 std::memcpy(result.data() + y * tight_bpr, mapped + y * aligned_bpr, tight_bpr);
330 }
331
332 staging.Unmap();
333 staging.Destroy();
334 return result;
335 }
336
338 wgpu::TextureView view() const {
339 return texture_.CreateView();
340 }
341
343 const wgpu::Texture& handle() const {
344 return texture_;
345 }
346
348 uint32_t width() const {
349 return width_;
350 }
352 uint32_t height() const {
353 return height_;
354 }
356 wgpu::TextureFormat format() const {
357 return format_;
358 }
359
360 // Non-copyable
361 Texture(const Texture&) = delete;
362 Texture& operator=(const Texture&) = delete;
363
365 Texture(Texture&& other) noexcept
366 : texture_(std::move(other.texture_))
367 , width_(other.width_)
368 , height_(other.height_)
369 , format_(other.format_) {
370 other.texture_ = nullptr;
371 other.width_ = 0;
372 other.height_ = 0;
373 }
374
376 Texture& operator=(Texture&& other) noexcept {
377 if (this != &other) {
378 if (texture_) {
379 texture_.Destroy();
380 }
381 texture_ = std::move(other.texture_);
382 width_ = other.width_;
383 height_ = other.height_;
384 format_ = other.format_;
385 other.texture_ = nullptr;
386 other.width_ = 0;
387 other.height_ = 0;
388 }
389 return *this;
390 }
391
394 if (texture_) {
395 texture_.Destroy();
396 }
397 }
398
399 private:
400 wgpu::Texture texture_ {nullptr};
401 uint32_t width_ {0};
402 uint32_t height_ {0};
403 wgpu::TextureFormat format_ {};
404};
405
406// =========================================================================
407// make_bind_group — build from pipeline + resource list
408// =========================================================================
409
411struct BindEntry {
412 uint32_t binding;
413 wgpu::TextureView texture_view {};
414 wgpu::Buffer buffer {};
415 uint64_t buffer_size {0};
416 uint64_t buffer_offset {0};
417
419 static BindEntry texture(uint32_t binding, const Texture& tex) {
420 BindEntry e;
421 e.binding = binding;
422 e.texture_view = tex.view();
423 return e;
424 }
425
427 static BindEntry texture_raw(uint32_t binding, wgpu::TextureView tv) {
428 BindEntry e;
429 e.binding = binding;
430 e.texture_view = std::move(tv);
431 return e;
432 }
433
435 template <typename T> static BindEntry buffer_entry(uint32_t binding, const Buffer<T>& buf) {
436 BindEntry e;
437 e.binding = binding;
438 e.buffer = buf.handle();
439 e.buffer_size = buf.byte_size();
440 return e;
441 }
442
444 static BindEntry buffer_raw(uint32_t binding, wgpu::Buffer buf, uint64_t size) {
445 BindEntry e;
446 e.binding = binding;
447 e.buffer = std::move(buf);
448 e.buffer_size = size;
449 return e;
450 }
451};
452
459inline wgpu::BindGroup make_bind_group(
460 const wgpu::ComputePipeline& pipeline, uint32_t group_index,
461 const std::vector<BindEntry>& entries
462) {
463 std::vector<wgpu::BindGroupEntry> wgpu_entries;
464 wgpu_entries.reserve(entries.size());
465
466 for (const auto& e : entries) {
467 wgpu::BindGroupEntry wge {};
468 wge.binding = e.binding;
469 if (e.texture_view) {
470 wge.textureView = e.texture_view;
471 }
472 if (e.buffer) {
473 wge.buffer = e.buffer;
474 wge.size = e.buffer_size;
475 wge.offset = e.buffer_offset;
476 }
477 wgpu_entries.push_back(wge);
478 }
479
480 wgpu::BindGroupDescriptor desc {};
481 desc.layout = pipeline.GetBindGroupLayout(group_index);
482 desc.entryCount = static_cast<uint32_t>(wgpu_entries.size());
483 desc.entries = wgpu_entries.data();
484
485 return GPU::getClassInstance().get_device().CreateBindGroup(&desc);
486}
487
488// =========================================================================
489// dispatch / encode_pass — compute pass helpers
490// =========================================================================
491
502inline void encode_pass(
503 wgpu::CommandEncoder& encoder, const wgpu::ComputePipeline& pipeline,
504 const wgpu::BindGroup& bind_group, uint32_t groups_x, uint32_t groups_y = 1,
505 uint32_t groups_z = 1
506) {
507 wgpu::ComputePassEncoder pass = encoder.BeginComputePass();
508 pass.SetPipeline(pipeline);
509 pass.SetBindGroup(0, bind_group);
510 pass.DispatchWorkgroups(groups_x, groups_y, groups_z);
511 pass.End();
512}
513
523inline void dispatch(
524 const wgpu::ComputePipeline& pipeline, const wgpu::BindGroup& bind_group, uint32_t groups_x,
525 uint32_t groups_y = 1, uint32_t groups_z = 1
526) {
527 wgpu::CommandEncoder encoder = GPU::getClassInstance().get_device().CreateCommandEncoder();
528 encode_pass(encoder, pipeline, bind_group, groups_x, groups_y, groups_z);
529 wgpu::CommandBuffer commands = encoder.Finish();
530 GPU::getClassInstance().get_queue().Submit(1, &commands);
531}
532
533// =========================================================================
534// workgroup_count — common ceiling-division helper
535// =========================================================================
536
541inline uint32_t workgroup_count(uint32_t total_size, uint32_t workgroup_size = 16) {
542 return (total_size + workgroup_size - 1) / workgroup_size;
543}
544
545} // namespace gpu
546
547#endif // IMG2NUM_GPU_UTILS_H
RAII wrapper around a wgpu::Buffer with compile-time type safety.
Definition gpu_utils.h:131
size_t size() const
Element count.
Definition gpu_utils.h:202
Buffer(Buffer &&other) noexcept
Move constructor. Transfers ownership of the GPU buffer.
Definition gpu_utils.h:211
void write(const T *data, size_t count, size_t offset_elements=0)
Upload data from CPU to GPU.
Definition gpu_utils.h:151
Buffer(size_t count, wgpu::BufferUsage usage)
Create a GPU buffer holding count elements of T.
Definition gpu_utils.h:138
Buffer & operator=(Buffer &&other) noexcept
Move assignment. Destroys the current buffer and takes ownership.
Definition gpu_utils.h:221
void write(const std::vector< T > &data)
Upload an entire vector to GPU.
Definition gpu_utils.h:158
~Buffer()
Destructor. Releases the GPU buffer.
Definition gpu_utils.h:237
size_t byte_size() const
Size in bytes.
Definition gpu_utils.h:197
const wgpu::Buffer & handle() const
Returns the underlying wgpu::Buffer handle.
Definition gpu_utils.h:192
std::vector< T > read()
Blocking readback: GPU → CPU.
Definition gpu_utils.h:166
RAII wrapper around a wgpu::Texture with upload and aligned readback.
Definition gpu_utils.h:257
std::vector< uint8_t > read(uint32_t bytes_per_pixel)
Blocking readback with automatic 256-byte row-alignment stripping.
Definition gpu_utils.h:296
uint32_t width() const
Width of the texture in pixels.
Definition gpu_utils.h:348
Texture & operator=(Texture &&other) noexcept
Move assignment. Destroys the current texture and takes ownership.
Definition gpu_utils.h:376
void write(const void *data, size_t data_size, uint32_t bytes_per_pixel)
Upload tightly-packed pixel data to the texture.
Definition gpu_utils.h:279
wgpu::TextureView view() const
Create a default texture view.
Definition gpu_utils.h:338
~Texture()
Destructor. Releases the GPU texture.
Definition gpu_utils.h:393
uint32_t height() const
Height of the texture in pixels.
Definition gpu_utils.h:352
Texture(uint32_t width, uint32_t height, wgpu::TextureFormat format, wgpu::TextureUsage usage)
Create a 2D texture.
Definition gpu_utils.h:264
Texture(Texture &&other) noexcept
Move constructor. Transfers ownership of the GPU texture.
Definition gpu_utils.h:365
wgpu::TextureFormat format() const
Texel format of the texture.
Definition gpu_utils.h:356
const wgpu::Texture & handle() const
Underlying wgpu::Texture handle.
Definition gpu_utils.h:343
static constexpr uint8_t COLOR_SPACE_CIELAB
Color space selector constants previously duplicated in each kernel.
Definition gpu_utils.h:45
void encode_pass(wgpu::CommandEncoder &encoder, const wgpu::ComputePipeline &pipeline, const wgpu::BindGroup &bind_group, uint32_t groups_x, uint32_t groups_y=1, uint32_t groups_z=1)
Encode a compute pass into an existing command encoder.
Definition gpu_utils.h:502
void dispatch(const wgpu::ComputePipeline &pipeline, const wgpu::BindGroup &bind_group, uint32_t groups_x, uint32_t groups_y=1, uint32_t groups_z=1)
Encode, finish, and submit a single compute dispatch.
Definition gpu_utils.h:523
uint32_t workgroup_count(uint32_t total_size, uint32_t workgroup_size=16)
Compute the number of workgroups needed to cover total_size with workgroups of workgroup_size.
Definition gpu_utils.h:541
wgpu::ComputePipeline cached_pipeline(const std::string &shader_id, const std::string &label)
Get or create a compute pipeline, caching by shader ID.
Definition gpu_utils.h:62
wgpu::BindGroup make_bind_group(const wgpu::ComputePipeline &pipeline, uint32_t group_index, const std::vector< BindEntry > &entries)
Build a wgpu::BindGroup from a pipeline layout and a list of entries.
Definition gpu_utils.h:459
const void * map_and_wait(wgpu::Buffer &buffer, size_t size)
Block until a MapAsync on buffer completes.
Definition gpu_utils.h:90
A single entry for bind-group construction.
Definition gpu_utils.h:411
static BindEntry texture_raw(uint32_t binding, wgpu::TextureView tv)
Create a texture-view entry from a raw wgpu::TextureView.
Definition gpu_utils.h:427
static BindEntry buffer_raw(uint32_t binding, wgpu::Buffer buf, uint64_t size)
Create a buffer entry from a raw wgpu::Buffer and size.
Definition gpu_utils.h:444
static BindEntry buffer_entry(uint32_t binding, const Buffer< T > &buf)
Create a buffer entry (storage or uniform).
Definition gpu_utils.h:435
static BindEntry texture(uint32_t binding, const Texture &tex)
Create a texture-view entry.
Definition gpu_utils.h:419