Img2Num C++ (Internal Developer Docs) dev
API Documentation
Loading...
Searching...
No Matches
GPU Class Reference
+ Collaboration diagram for GPU:

Classes

struct  ThreadDevice
 

Public Member Functions

const wgpu::Device & get_device ()
 
const wgpu::Instance & get_instance ()
 
const wgpu::Queue & get_queue ()
 
bool is_initialized ()
 
bool wait (wgpu::Future future, const bool &done)
 
 GPU (const GPU &)=delete
 
GPU & operator= (const GPU &)=delete
 
 GPU (GPU &&)=delete
 
GPU & operator= (GPU &&)=delete
 
std::string readWGSLFile (std::string_view shader_id)
 Look up the WGSL source of an embedded shader.
 
wgpu::ComputePipeline createPipeline (const std::string &filename, const std::string &label)
 
void init_gpu ()
 

Static Public Member Functions

static GPU & getClassInstance ()
 
static constexpr wgpu::CallbackMode wait_mode ()
 
static uint32_t getAlignedBytesPerRow (uint32_t width, uint32_t bytesPerPixel=4)
 
static void printShaderError (wgpu::ShaderModule shaderModule)
 

Private Member Functions

void cleanup ()
 
bool init_instance ()
 
wgpu::Adapter request_adapter ()
 
wgpu::Device request_device (const wgpu::Adapter &adapter)
 

Static Private Member Functions

static ThreadDevice & thread_device ()
 
static bool validate_device (const wgpu::Device &device)
 

Private Attributes

wgpu::Instance instance
 
std::mutex mutex_
 
bool instance_attempted = false
 

Static Private Attributes

static constexpr wgpu::CallbackMode kWaitMode = wgpu::CallbackMode::WaitAnyOnly
 

Detailed Description

Definition at line 24 of file gpu.h.

Member Function Documentation

◆ cleanup()

void GPU::cleanup ( )
inlineprivate

Definition at line 56 of file gpu.h.

56 {
57 instance = nullptr;
58 }

◆ createPipeline()

wgpu::ComputePipeline GPU::createPipeline ( const std::string &  filename,
const std::string &  label 
)
inline

Definition at line 144 of file gpu.h.

144 {
145 wgpu::ShaderSourceWGSL wgsl;
146 std::string shaderCode = readWGSLFile(filename);
147 wgsl.code = shaderCode.c_str();
148 wgpu::ShaderModuleDescriptor md = {};
149 md.nextInChain = &wgsl;
150 md.label = label.c_str();
151 wgpu::ShaderModule sm = get_device().CreateShaderModule(&md);
152
153 wgpu::ComputePipelineDescriptor cpd = {};
154 cpd.compute.module = sm;
155 cpd.compute.entryPoint = "main";
156 return get_device().CreateComputePipeline(&cpd);
157 };
std::string readWGSLFile(std::string_view shader_id)
Look up the WGSL source of an embedded shader.
Definition gpu.h:129

◆ get_device()

const wgpu::Device & GPU::get_device ( )
inline

Definition at line 81 of file gpu.h.

81 {
82 return thread_device().device;
83 }

◆ get_instance()

const wgpu::Instance & GPU::get_instance ( )
inline

Definition at line 85 of file gpu.h.

85 {
86 return instance;
87 }

◆ get_queue()

const wgpu::Queue & GPU::get_queue ( )
inline

Definition at line 89 of file gpu.h.

89 {
90 return thread_device().queue;
91 }

◆ getAlignedBytesPerRow()

static uint32_t GPU::getAlignedBytesPerRow ( uint32_t  width,
uint32_t  bytesPerPixel = 4 
)
inlinestatic

Definition at line 159 of file gpu.h.

159 {
160 uint32_t unaligned = width * bytesPerPixel;
161 uint32_t align = 256;
162 return (unaligned + align - 1) & ~(align - 1);
163 };

◆ getClassInstance()

static GPU & GPU::getClassInstance ( )
inlinestatic

Definition at line 75 of file gpu.h.

75 {
76 static GPU gpuInstance;
77 return gpuInstance;
78 }
Definition gpu.h:24

◆ init_gpu()

void GPU::init_gpu ( )
inline

Definition at line 204 of file gpu.h.

204 {
205 ThreadDevice& td = thread_device();
206 if (td.init_attempted)
207 return;
208 td.init_attempted = true;
209
210 std::lock_guard<std::mutex> lock(mutex_);
211 if (!init_instance())
212 return;
213
214 // Dawn adapters are consumed by creating a device, so each thread
215 // needs its own adapter as well as its own device.
216 wgpu::Adapter adapter = request_adapter();
217 if (!adapter)
218 return;
219
220 wgpu::Device device = request_device(adapter);
221 if (!validate_device(device)) {
222 IMG2NUM_LOG_WARN("Fatal: Could not get WebGPU Device. Falling back to CPU.");
223 return;
224 }
225
226 td.queue = device.GetQueue();
227 td.device = std::move(device);
228 IMG2NUM_LOG_INFO("GPU Fully Initialized.");
229 };

◆ init_instance()

bool GPU::init_instance ( )
inlineprivate

Definition at line 233 of file gpu.h.

233 {
234 if (instance_attempted)
235 return instance != nullptr;
236 instance_attempted = true;
237
238 wgpu::InstanceDescriptor instanceDesc = {};
239#if !defined(__EMSCRIPTEN__)
240 // Required for WaitAny with a non-zero timeout
241 static constexpr wgpu::InstanceFeatureName kTimedWaitAny =
242 wgpu::InstanceFeatureName::TimedWaitAny;
243 instanceDesc.requiredFeatureCount = 1;
244 instanceDesc.requiredFeatures = &kTimedWaitAny;
245#endif
246 instance = wgpu::CreateInstance(&instanceDesc);
247
248 if (!instance) {
249 IMG2NUM_LOG_WARN("Fatal: WebGPU instance creation failed. Falling back to CPU.");
250 cleanup();
251 return false;
252 }
253 return true;
254 }

◆ is_initialized()

bool GPU::is_initialized ( )
inline

Definition at line 93 of file gpu.h.

93 {
94 return thread_device().device != nullptr;
95 }

◆ printShaderError()

static void GPU::printShaderError ( wgpu::ShaderModule  shaderModule)
inlinestatic

Definition at line 165 of file gpu.h.

165 {
166 shaderModule.GetCompilationInfo(
167 // Callback Mode (New API Requirement)
168 wgpu::CallbackMode::AllowProcessEvents,
169 // Callback Lambda
170 [](wgpu::CompilationInfoRequestStatus status, const wgpu::CompilationInfo* info) {
171 if (status != wgpu::CompilationInfoRequestStatus::Success || !info)
172 return;
173
174 for (uint32_t i {0}; i < info->messageCount; ++i) {
175 const auto& msg = info->messages[i];
176 const std::string_view text(
177 msg.message.data ? msg.message.data : "", msg.message.length
178 );
179
180 switch (msg.type) {
181 case wgpu::CompilationMessageType::Error:
182 IMG2NUM_LOG_ERROR(
183 "Shader Error Line {}:{} - {}", msg.lineNum, msg.linePos, text
184 );
185 break;
186 case wgpu::CompilationMessageType::Warning:
187 IMG2NUM_LOG_WARN(
188 "Shader Warning Line {}:{} - {}", msg.lineNum, msg.linePos, text
189 );
190 break;
191 default: // Info
192 IMG2NUM_LOG_DEBUG(
193 "Shader Info Line {}:{} - {}", msg.lineNum, msg.linePos, text
194 );
195 break;
196 }
197 }
198 }
199 );
200 };

◆ readWGSLFile()

std::string GPU::readWGSLFile ( std::string_view  shader_id)
inline

Look up the WGSL source of an embedded shader.

Parameters
shader_idEmbedded shader identifier to look up.
Returns
An owning copy of the embedded WGSL source.
Exceptions
std::invalid_argumentIf shader_id is not found. The diagnostic includes the function name and the full supplied ID.

Definition at line 129 of file gpu.h.

129 {
130 // A simple linear search over 9 items is blazingly fast in C++
131 for (const auto& entry : embedded_shaders::shaders) {
132 if (entry.id == shader_id) {
133 // Safely convert the string_view back to a std::string for Dawn
134 return std::string(entry.source);
135 }
136 }
137
138 throw std::invalid_argument(
139 std::string("GPU::readWGSLFile: unknown shader id '") + std::string(shader_id) +
140 "' (not found in embedded shaders)"
141 );
142 }

◆ request_adapter()

wgpu::Adapter GPU::request_adapter ( )
inlineprivate

Definition at line 257 of file gpu.h.

257 {
258 IMG2NUM_LOG_DEBUG("Requesting Adapter...");
259 wgpu::Adapter adapter;
260 bool adapter_ready = false;
261 wgpu::Future future = instance.RequestAdapter(
262 nullptr, kWaitMode,
263 [&](wgpu::RequestAdapterStatus status, wgpu::Adapter a, wgpu::StringView msg) {
264 if (status == wgpu::RequestAdapterStatus::Success) {
265 adapter = std::move(a);
266 IMG2NUM_LOG_INFO("Adapter Acquired");
267 } else {
268 IMG2NUM_LOG_WARN(
269 "Adapter Failed: {}", std::string_view(msg.data ? msg.data : "", msg.length)
270 );
271 }
272 adapter_ready = true;
273 }
274 );
275 wait(future, adapter_ready);
276
277 if (!adapter) {
278 IMG2NUM_LOG_WARN("Fatal: Could not get WebGPU Adapter. Falling back to CPU.");
279 return nullptr;
280 }
281 if (wgpu::AdapterInfo info; adapter.GetInfo(&info) != wgpu::Status::Success ||
282 info.backendType == wgpu::BackendType::Null) {
283 IMG2NUM_LOG_WARN("No usable WebGPU adapter found. Falling back to CPU.");
284 return nullptr;
285 }
286 return adapter;
287 }

◆ request_device()

wgpu::Device GPU::request_device ( const wgpu::Adapter &  adapter)
inlineprivate

Definition at line 290 of file gpu.h.

290 {
291 IMG2NUM_LOG_DEBUG("Requesting Device...");
292
293 wgpu::DeviceDescriptor deviceDesc = {};
294 deviceDesc.SetUncapturedErrorCallback([](const wgpu::Device&, wgpu::ErrorType type,
295 wgpu::StringView msg) {
296 // 1. Safely extract the string using the provided length
297 std::string err_str = (msg.data && msg.length > 0) ? std::string(msg.data, msg.length)
298 : "Unknown Error (Null message)";
299
300 // 2. Print it safely
301 IMG2NUM_LOG_ERROR(
302 "\n[WEBGPU FATAL ERROR] Type: {} | Msg: {}\n", static_cast<uint32_t>(type), err_str
303 );
304 });
305 deviceDesc.SetDeviceLostCallback(
306#if defined(__EMSCRIPTEN__)
307 wgpu::CallbackMode::AllowProcessEvents,
308#else
309 // Nothing calls ProcessEvents natively, so let Dawn fire this directly
310 wgpu::CallbackMode::AllowSpontaneous,
311#endif
312 [](const wgpu::Device&, wgpu::DeviceLostReason reason, wgpu::StringView msg) {
313 std::string err_msg = (msg.data && msg.length > 0)
314 ? std::string(msg.data, msg.length)
315 : "Unknown device lost reason";
316 // 1. Ignore teardown so we don't log when a thread's device is released
317 if (reason == wgpu::DeviceLostReason::CallbackCancelled ||
318 reason == wgpu::DeviceLostReason::Destroyed) {
319 return;
320 }
321 IMG2NUM_LOG_ERROR(
322 "[DEVICE LOST] Reason: {} Msg: {}", static_cast<int>(reason), err_msg
323 );
324 }
325 );
326
327#if !defined(__EMSCRIPTEN__)
328 // Each device is only used by its own thread, so this isn't required;
329 // it makes Dawn lock internally in case a device is ever shared.
330 static constexpr wgpu::FeatureName kImplicitSync =
331 wgpu::FeatureName::ImplicitDeviceSynchronization;
332 if (adapter.HasFeature(kImplicitSync)) {
333 deviceDesc.requiredFeatureCount = 1;
334 deviceDesc.requiredFeatures = &kImplicitSync;
335 }
336#endif
337
338 // Set maximum possible device hardware memory
339 wgpu::Limits supportedLimits;
340 wgpu::Limits requiredLimits;
341 if (adapter.GetLimits(&supportedLimits)) {
342 // nominally the device Buffer limit is 256MB
343
344 // Copy the adapter's physical limits over to your requested limits
345 requiredLimits = supportedLimits;
346
347 IMG2NUM_LOG_DEBUG("maxBufferSize: {}", requiredLimits.maxBufferSize);
348 IMG2NUM_LOG_DEBUG(
349 "maxStorageBufferBindingSize: {}", requiredLimits.maxStorageBufferBindingSize
350 );
351
352 deviceDesc.requiredLimits = &requiredLimits;
353 }
354
355 wgpu::Device device;
356 bool device_ready = false;
357 wgpu::Future future = adapter.RequestDevice(
358 &deviceDesc, kWaitMode,
359 [&](wgpu::RequestDeviceStatus status, wgpu::Device d, wgpu::StringView msg) {
360 if (status == wgpu::RequestDeviceStatus::Success) {
361 device = std::move(d);
362 IMG2NUM_LOG_INFO("Device Acquired");
363 } else {
364 IMG2NUM_LOG_WARN(
365 "Device Failed: {}", msg.data && msg.length > 0
366 ? std::string(msg.data, msg.length)
367 : "Unknown error"
368 );
369 }
370 device_ready = true;
371 }
372 );
373 wait(future, device_ready);
374 return device;
375 }

◆ thread_device()

static ThreadDevice & GPU::thread_device ( )
inlinestaticprivate

Definition at line 42 of file gpu.h.

42 {
43 thread_local ThreadDevice td;
44 return td;
45 }

◆ validate_device()

static bool GPU::validate_device ( const wgpu::Device &  device)
inlinestaticprivate

Definition at line 60 of file gpu.h.

60 {
61 if (!device)
62 return false;
63
64 // Try creating a trivial buffer to ensure the device is usable
65 wgpu::BufferDescriptor desc = {};
66 desc.size = 4;
67 desc.usage = wgpu::BufferUsage::CopyDst;
68
69 wgpu::Buffer test = device.CreateBuffer(&desc);
70 return test != nullptr;
71 }

◆ wait()

bool GPU::wait ( wgpu::Future  future,
const bool &  done 
)
inline

Definition at line 99 of file gpu.h.

99 {
100#if defined(__EMSCRIPTEN__)
101 (void)future;
102 while (!done) {
103 instance.ProcessEvents();
104 emscripten_sleep(10);
105 }
106#else
107 instance.WaitAny(future, UINT64_MAX);
108#endif
109 return done;
110 }

◆ wait_mode()

static constexpr wgpu::CallbackMode GPU::wait_mode ( )
inlinestaticconstexpr

Definition at line 112 of file gpu.h.

112 {
113 return kWaitMode;
114 }

Member Data Documentation

◆ instance

wgpu::Instance GPU::instance
private

Definition at line 49 of file gpu.h.

◆ instance_attempted

bool GPU::instance_attempted = false
private

Definition at line 51 of file gpu.h.

◆ kWaitMode

constexpr wgpu::CallbackMode GPU::kWaitMode = wgpu::CallbackMode::WaitAnyOnly
staticconstexprprivate

Definition at line 31 of file gpu.h.

◆ mutex_

std::mutex GPU::mutex_
private

Definition at line 50 of file gpu.h.


The documentation for this class was generated from the following file: