WebGPU: backend components created and conditionally logged

Initial groundwork in creating WebGPU backend components, namely
the instance, adapter, device, and queue.
If configured to do so, the backend will print out details about
these components.
The samples/hellotriangle.cpp was slightly modified to include a
webgpu option which allows for exercising the above, but does not
yet draw anything to the screen/window.
NOTE: This has only been sanity tested with hello triangle
on Mac OS and the Android emulator at this time, NOT IOS,
Windows, or Linux yet.

Author: AndyHovingh

filament/backend/CMakeLists.txt

@@ -242,11 +242,29 @@ endif()
 
 if (FILAMENT_SUPPORTS_WEBGPU)
     list(APPEND SRCS
+            include/backend/platforms/WebGPUPlatform.h
+            src/webgpu/platform/WebGPUPlatform.cpp
+            src/webgpu/WebGPUConstants.h
             src/webgpu/WebGPUDriver.cpp
             src/webgpu/WebGPUDriver.h
-            src/webgpu/WebGPUPlatform.cpp
-            src/webgpu/WebGPUPlatform.h
     )
+    if (LINUX OR WIN32)
+        list(APPEND SRCS src/webgpu/platform/WebGPUPlatformLinuxWindows.cpp)
+    elseif (APPLE OR IOS)
+        list(APPEND SRCS src/webgpu/platform/WebGPUPlatformApple.mm)
+    elseif (ANDROID)
+        list(APPEND SRCS src/webgpu/platform/WebGPUPlatformAndroid.cpp)
+    endif()
+
+    if (TNT_DEV)
+        set(FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING_DEFAULT ON)
+    else()
+        set(FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING_DEFAULT OFF)
+    endif()
+
+    option(FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING
+            "Enable immediate_error_handling for the WebGPU backend Dawn implementation"
+            ${FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING_DEFAULT})
 endif()
 
 if (ANDROID)
@@ -433,6 +451,10 @@ if (FILAMENT_SUPPORTS_METAL)
     target_compile_definitions(${TARGET} PRIVATE $<$<BOOL:${FILAMENT_METAL_PROFILING}>:FILAMENT_METAL_PROFILING>)
 endif()
 
+if (FILAMENT_SUPPORTS_WEBGPU)
+    target_compile_definitions(${TARGET} PRIVATE $<$<BOOL:${FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING}>:FILAMENT_WEBGPU_IMMEDIATE_ERROR_HANDLING>)
+endif()
+
 target_link_libraries(${TARGET} PRIVATE
         ${OSMESA_LINKER_FLAGS}
         $<$<AND:$<PLATFORM_ID:Linux>,$<CONFIG:Release>>:${LINUX_LINKER_OPTIMIZATION_FLAGS}>

filament/backend/include/backend/platforms/WebGPUPlatform.h

@@ -0,0 +1,65 @@
+/*
+ * Copyright (C) 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_PLATFORMS_WEBGPUPLATFORM_H
+#define TNT_FILAMENT_BACKEND_PLATFORMS_WEBGPUPLATFORM_H
+
+#include <cstdint>
+
+#include <webgpu/webgpu_cpp.h>
+
+#include "backend/Platform.h"
+
+namespace filament::backend {
+
+/**
+ * A Platform interface, handling the environment-specific concerns, e.g. OS, for creating a WebGPU
+ * driver (backend).
+ */
+class WebGPUPlatform final : public Platform {
+public:
+
+    struct SurfaceBundle final {
+        wgpu::Surface surface = nullptr;
+        // may or may not be defined based on the platform
+        wgpu::Extent2D fallbackExtent = {.width = 0, .height = 0};
+    };
+
+    WebGPUPlatform();
+    ~WebGPUPlatform() override = default;
+
+    [[nodiscard]] int getOSVersion() const noexcept final { return 0; }
+
+    [[nodiscard]] wgpu::Instance& getInstance() noexcept { return mInstance; }
+
+    //either returns a valid surface or panics
+    [[nodiscard]] SurfaceBundle createSurface(void* nativeWindow, uint64_t flags);
+    //either returns a valid adapter or panics
+    [[nodiscard]] wgpu::Adapter requestAdapter(wgpu::Surface const& surface);
+    //either returns a valid device or panics
+    [[nodiscard]] wgpu::Device requestDevice(wgpu::Adapter const& adapter);
+
+protected:
+    [[nodiscard]] Driver* createDriver(void* sharedContext,
+            const Platform::DriverConfig& driverConfig) noexcept override;
+
+private:
+    wgpu::Instance mInstance;  // we may consider having the driver own this in the future
+};
+
+}// namespace filament::backend
+
+#endif// TNT_FILAMENT_BACKEND_PLATFORMS_WEBGPUPLATFORM_H

filament/backend/src/PlatformFactory.cpp

@@ -66,7 +66,7 @@ filament::backend::Platform* createDefaultMetalPlatform();
 
 #include "noop/PlatformNoop.h"
 #if defined(FILAMENT_SUPPORTS_WEBGPU)
-    #include "webgpu/WebGPUPlatform.h"
+    #include "backend/platforms/WebGPUPlatform.h"
 #endif
 
 namespace filament::backend {

filament/backend/src/webgpu/WebGPUConstants.h

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_WEBGPUCONSTANTS_H
+#define TNT_FILAMENT_BACKEND_WEBGPUCONSTANTS_H
+
+#include <cstdint>
+
+#include "utils/Log.h"
+
+// FWGPU is short for Filament WebGPU
+
+// turn on runtime validation, namely for debugging, that would normally not run (for release)
+#define FWGPU_DEBUG_VALIDATION     0x00000001
+// print/log system component details to the console, e.g. about the
+// instance, surface, adapter, device, etc.
+#define FWGPU_PRINT_SYSTEM         0x00000002
+
+// Set this to enable logging "only" to one output stream. This is useful in the case where we want
+// to debug with print statements and want ordered logging (e.g slog.i and slog.e will not appear in
+// order of calls).
+#define FWGPU_DEBUG_FORCE_LOG_TO_I 0x00000004
+
+// Useful default combinations
+#define FWGPU_DEBUG_EVERYTHING     0xFFFFFFFF
+
+#if defined(FILAMENT_BACKEND_DEBUG_FLAG)
+    #define FWGPU_DEBUG_FORWARDED_FLAG (FILAMENT_BACKEND_DEBUG_FLAG & FWGPU_DEBUG_EVERYTHING)
+#else
+    #define FWGPU_DEBUG_FORWARDED_FLAG 0
+#endif
+
+#ifndef NDEBUG
+    #define FWGPU_DEBUG_FLAGS FWGPU_DEBUG_FORWARDED_FLAG
+#else
+    #define FWGPU_DEBUG_FLAGS 0
+#endif
+
+#define FWGPU_ENABLED(flags) (((FWGPU_DEBUG_FLAGS) & (flags)) == (flags))
+
+#if FWGPU_ENABLED(FWGPU_DEBUG_FORCE_LOG_TO_I)
+    #define FWGPU_LOGI (utils::slog.i)
+    #define FWGPU_LOGD FWGPU_LOGI
+    #define FWGPU_LOGE FWGPU_LOGI
+    #define FWGPU_LOGW FWGPU_LOGI
+#else
+    #define FWGPU_LOGE (utils::slog.e)
+    #define FWGPU_LOGW (utils::slog.w)
+    #define FWGPU_LOGD (utils::slog.d)
+    #define FWGPU_LOGI (utils::slog.i)
+#endif
+
+#endif// TNT_FILAMENT_BACKEND_WEBGPUCONSTANTS_H