Img2Num C++ (Internal Developer Docs) dev
API Documentation
Loading...
Searching...
No Matches
gpu_utils.h File Reference

Reusable RAII helpers for WebGPU/Dawn compute work. More...

#include "internal/gpu.h"
#include "internal/log.h"
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <initializer_list>
#include <mutex>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <unordered_map>
#include <vector>
#include <webgpu/webgpu_cpp.h>
+ Include dependency graph for gpu_utils.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  gpu::Buffer< T >
 RAII wrapper around a wgpu::Buffer with compile-time type safety. More...
 
class  gpu::Texture
 RAII wrapper around a wgpu::Texture with upload and aligned readback. More...
 
struct  gpu::BindEntry
 A single entry for bind-group construction. More...
 

Functions

wgpu::ComputePipeline gpu::cached_pipeline (const std::string &shader_id, const std::string &label)
 Get or create a compute pipeline, caching by shader ID.
 
const void * gpu::map_and_wait (wgpu::Buffer &buffer, size_t size)
 Block until a MapAsync on buffer completes.
 
wgpu::BindGroup gpu::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.
 
void gpu::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.
 
void gpu::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.
 
uint32_t gpu::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.
 

Variables

static constexpr uint8_t gpu::COLOR_SPACE_CIELAB {0}
 Color space selector constants previously duplicated in each kernel.
 
static constexpr uint8_t gpu::COLOR_SPACE_RGB {1}
 

Detailed Description

Reusable RAII helpers for WebGPU/Dawn compute work.

This layer sits on top of the GPU singleton (gpu.h) and eliminates boilerplate that every compute kernel otherwise duplicates:

  • typed buffer creation, upload, and blocking readback
  • texture creation, upload, and aligned readback
  • bind-group construction from a simple list
  • compute-pass encoding and single-shot dispatch

All helpers live in the gpu namespace and are internal to the library.

Definition in file gpu_utils.h.

Function Documentation

◆ cached_pipeline()

wgpu::ComputePipeline gpu::cached_pipeline ( const std::string &  shader_id,
const std::string &  label 
)
inline

Get or create a compute pipeline, caching by shader ID.

GPU::createPipeline() recreates the shader module and pipeline on every call. This wrapper memoizes the result so that repeated calls with the same shader_id return the cached pipeline instantly.

Parameters
shader_idThe embedded shader identifier (e.g. "bilateral_filter_rgb").
labelDebug label for the pipeline.
Returns
Cached wgpu::ComputePipeline.

Definition at line 62 of file gpu_utils.h.

62 {
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}

References gpu::cached_pipeline().

Referenced by gpu::cached_pipeline().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ dispatch()

void gpu::dispatch ( const wgpu::ComputePipeline &  pipeline,
const wgpu::BindGroup &  bind_group,
uint32_t  groups_x,
uint32_t  groups_y = 1,
uint32_t  groups_z = 1 
)
inline

Encode, finish, and submit a single compute dispatch.

Convenience for kernels that only need one pass.

Parameters
pipelineThe compute pipeline to run.
bind_groupThe bind group for this pass.
groups_xNumber of workgroups in X.
groups_yNumber of workgroups in Y (default 1).
groups_zNumber of workgroups in Z (default 1).

Definition at line 523 of file gpu_utils.h.

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}
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

References gpu::dispatch(), and gpu::encode_pass().

Referenced by gpu::dispatch().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ encode_pass()

void gpu::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 
)
inline

Encode a compute pass into an existing command encoder.

Use this for multi-pass work (e.g. bilateral filter with color conversion).

Parameters
encoderExisting command encoder to append to.
pipelineThe compute pipeline to run.
bind_groupThe bind group for this pass.
groups_xNumber of workgroups in X.
groups_yNumber of workgroups in Y (default 1).
groups_zNumber of workgroups in Z (default 1).

Definition at line 502 of file gpu_utils.h.

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}

References gpu::encode_pass().

Referenced by gpu::dispatch(), and gpu::encode_pass().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ make_bind_group()

wgpu::BindGroup gpu::make_bind_group ( const wgpu::ComputePipeline &  pipeline,
uint32_t  group_index,
const std::vector< BindEntry > &  entries 
)
inline

Build a wgpu::BindGroup from a pipeline layout and a list of entries.

Parameters
pipelineThe compute pipeline (used to get the bind group layout).
group_indexWhich bind group index (usually 0).
entriesList of BindEntry objects.
Returns
The constructed wgpu::BindGroup.

Definition at line 459 of file gpu_utils.h.

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}

References gpu::make_bind_group().

Referenced by gpu::make_bind_group().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ map_and_wait()

const void * gpu::map_and_wait ( wgpu::Buffer &  buffer,
size_t  size 
)
inline

Block until a MapAsync on buffer completes.

Works on both native Dawn and Emscripten (ASYNCIFY). Returns the pointer from GetConstMappedRange.

Parameters
bufferThe buffer to map (must have MapRead usage).
sizeNumber of bytes to map.
Returns
Pointer to the mapped data. Valid until buffer.Unmap().
Exceptions
std::runtime_errorif the mapping fails.

Definition at line 90 of file gpu_utils.h.

90 {
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}

References gpu::map_and_wait().

Referenced by gpu::map_and_wait(), gpu::Buffer< T >::read(), and gpu::Texture::read().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ workgroup_count()

uint32_t gpu::workgroup_count ( uint32_t  total_size,
uint32_t  workgroup_size = 16 
)
inline

Compute the number of workgroups needed to cover total_size with workgroups of workgroup_size.

Equivalent to (total_size + workgroup_size - 1) / workgroup_size.

Definition at line 541 of file gpu_utils.h.

541 {
542 return (total_size + workgroup_size - 1) / workgroup_size;
543}

References gpu::workgroup_count().

Referenced by gpu::workgroup_count().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Variable Documentation

◆ COLOR_SPACE_CIELAB

constexpr uint8_t gpu::COLOR_SPACE_CIELAB {0}
staticconstexpr

Color space selector constants previously duplicated in each kernel.

Definition at line 45 of file gpu_utils.h.

45{0};

◆ COLOR_SPACE_RGB

constexpr uint8_t gpu::COLOR_SPACE_RGB {1}
staticconstexpr

Definition at line 46 of file gpu_utils.h.

46{1};