Img2Num C++ (Internal Developer Docs) dev
API Documentation
Loading...
Searching...
No Matches
gpu.h
1#ifndef GPU_H
2#define GPU_H
3
4#if defined(__EMSCRIPTEN__)
5#include <emscripten/emscripten.h>
6#include <emscripten/html5.h>
7#endif
8
9#include <fstream>
10#include <iterator>
11#include <map>
12#include <mutex>
13#include <sstream>
14#include <stdexcept>
15#include <string>
16#include <string_view>
17#include <webgpu/webgpu_cpp.h>
18
19// auto generated by tools/embed_shaders.py
20#include "internal/log.h"
21
22#include <embedded_shaders.h>
23
24class GPU {
25 private:
26#if defined(__EMSCRIPTEN__)
27 static constexpr wgpu::CallbackMode kWaitMode = wgpu::CallbackMode::AllowProcessEvents;
28#else
29 // Callbacks fire inside WaitAny on the waiting thread, so concurrent waits
30 // on different threads never run each other's callbacks.
31 static constexpr wgpu::CallbackMode kWaitMode = wgpu::CallbackMode::WaitAnyOnly;
32#endif
33
34 // Every thread gets its own device and queue, so threads can run GPU jobs
35 // concurrently without sharing (or locking) a single device.
36 struct ThreadDevice {
37 wgpu::Device device;
38 wgpu::Queue queue;
39 bool init_attempted = false;
40 };
41
42 static ThreadDevice& thread_device() {
43 thread_local ThreadDevice td;
44 return td;
45 }
46
47 // The instance is shared by all threads. mutex_ guards its creation and
48 // serializes adapter/device creation; GPU work itself runs unlocked.
49 wgpu::Instance instance;
50 std::mutex mutex_;
51 bool instance_attempted = false;
52
53 GPU() = default;
54 ~GPU() = default;
55
56 void cleanup() {
57 instance = nullptr;
58 }
59
60 static bool validate_device(const wgpu::Device& device) {
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 }
72
73 public:
74 // makes a single global instance that other files can reference
75 static GPU& getClassInstance() {
76 static GPU gpuInstance;
77 return gpuInstance;
78 }
79
80 // Device and queue belonging to the calling thread
81 const wgpu::Device& get_device() {
82 return thread_device().device;
83 }
84
85 const wgpu::Instance& get_instance() {
86 return instance;
87 }
88
89 const wgpu::Queue& get_queue() {
90 return thread_device().queue;
91 }
92
93 bool is_initialized() {
94 return thread_device().device != nullptr;
95 }
96
97 // Block until `future` completes; `done` must be set by its callback.
98 // The callback must have been registered with kWaitMode.
99 bool wait(wgpu::Future future, const bool& done) {
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 }
111
112 static constexpr wgpu::CallbackMode wait_mode() {
113 return kWaitMode;
114 }
115
116 // Delete copy constructor and assignment operator to prevent duplication
117 GPU(const GPU&) = delete;
118 GPU& operator=(const GPU&) = delete;
119 GPU(GPU&&) = delete;
120 GPU& operator=(GPU&&) = delete;
121
129 std::string readWGSLFile(std::string_view shader_id) {
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 }
143
144 wgpu::ComputePipeline createPipeline(const std::string& filename, const std::string& label) {
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 };
158
159 static uint32_t getAlignedBytesPerRow(uint32_t width, uint32_t bytesPerPixel = 4) {
160 uint32_t unaligned = width * bytesPerPixel;
161 uint32_t align = 256;
162 return (unaligned + align - 1) & ~(align - 1);
163 };
164
165 static void printShaderError(wgpu::ShaderModule shaderModule) {
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 };
201
202 // Creates the calling thread's device on first use. Safe to call from
203 // any thread; falls back to CPU (is_initialized() == false) on failure.
204 void init_gpu() {
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 };
230
231 private:
232 // Creates the shared instance once. Caller must hold mutex_.
233 bool init_instance() {
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 }
255
256 // Requests a new adapter from the shared instance. Caller must hold mutex_.
257 wgpu::Adapter request_adapter() {
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 }
288
289 // Requests a new device from `adapter`. Caller must hold mutex_.
290 wgpu::Device request_device(const wgpu::Adapter& adapter) {
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 }
376};
377
378#endif
Definition gpu.h:24
std::string readWGSLFile(std::string_view shader_id)
Look up the WGSL source of an embedded shader.
Definition gpu.h:129