native-dawn 0.0.0-stage → 0.1.1

package/CMakeLists.txt

@@ -0,0 +1,90 @@
+cmake_minimum_required(VERSION 3.22)
+project(native_dawn LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_C_VISIBILITY_PRESET hidden)
+set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
+set(CMAKE_INSTALL_LIBDIR lib CACHE PATH "" FORCE)
+include(GNUInstallDirs)
+
+# Keep checkout paths out of __FILE__ strings and debug information.
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang" AND NOT MSVC)
+  add_compile_options("-ffile-prefix-map=${CMAKE_SOURCE_DIR}=.")
+endif()
+
+# The Node addon is built for desktop targets only; Android gets the C SDK.
+option(NATIVE_DAWN_NODE "Build the Node-API addon" ON)
+
+set(DAWN_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/.cache/dawn" CACHE PATH "Dawn checkout")
+
+# One shared libwebgpu_dawn holds all of Dawn. The Node addon links against it
+# instead of carrying a second copy, so C/C++ code and JavaScript in the same
+# process share one implementation and can pass handles to each other.
+set(DAWN_BUILD_MONOLITHIC_LIBRARY SHARED CACHE STRING "" FORCE)
+set(DAWN_ENABLE_INSTALL ON CACHE BOOL "" FORCE)
+set(DAWN_BUILD_NODE_BINDINGS ${NATIVE_DAWN_NODE} CACHE BOOL "" FORCE)
+set(DAWN_ENABLE_PIC ON CACHE BOOL "" FORCE)
+set(DAWN_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
+set(DAWN_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(DAWN_BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE)
+set(DAWN_BUILD_PROTOBUF OFF CACHE BOOL "" FORCE)
+set(TINT_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(TINT_BUILD_CMD_TOOLS OFF CACHE BOOL "" FORCE)
+set(DAWN_USE_GLFW OFF CACHE BOOL "" FORCE)
+set(DAWN_SUPPORTS_GLFW_FOR_WINDOWING OFF CACHE BOOL "" FORCE)
+set(DAWN_SUPPORTS_CXX_MODULES OFF CACHE BOOL "" FORCE)
+if(UNIX AND NOT APPLE AND NOT ANDROID)
+  set(DAWN_USE_X11 ON CACHE BOOL "" FORCE)
+  set(DAWN_USE_WAYLAND ON CACHE BOOL "" FORCE)
+  # Vulkan covers desktop Linux GPUs. OpenGL ES stays for GPUs without a
+  # Vulkan driver (WebGPU compatibility mode); desktop OpenGL adds nothing.
+  set(DAWN_ENABLE_DESKTOP_GL OFF CACHE BOOL "" FORCE)
+endif()
+if(WIN32)
+  set(DAWN_USE_BUILT_DXC ON CACHE BOOL "" FORCE)
+  set(DAWN_DXC_ENABLE_ASSERTS_IN_NDEBUG OFF CACHE BOOL "" FORCE)
+endif()
+
+add_subdirectory("${DAWN_SOURCE_DIR}" dawn)
+
+if(APPLE)
+  set_target_properties(webgpu_dawn PROPERTIES INSTALL_RPATH "@loader_path" BUILD_WITH_INSTALL_RPATH ON)
+elseif(UNIX)
+  set_target_properties(webgpu_dawn PROPERTIES INSTALL_RPATH "$ORIGIN" BUILD_WITH_INSTALL_RPATH ON)
+endif()
+if(ANDROID)
+  # 16 KB pages, required for apps targeting Android 15 and newer devices.
+  target_link_options(webgpu_dawn PRIVATE "-Wl,-z,max-page-size=16384")
+endif()
+
+if(NATIVE_DAWN_NODE)
+  # Swap the addon's static Dawn for the shared library. Its calls go straight
+  # to webgpu_dawn's exports, so the dawn_proc table is dropped too (see the
+  # Module.cpp hook in scripts/build.mjs).
+  get_target_property(node_libs dawn_node LINK_LIBRARIES)
+  list(REMOVE_ITEM node_libs dawn_native dawn_proc)
+  list(APPEND node_libs webgpu_dawn)
+  set_property(TARGET dawn_node PROPERTY LINK_LIBRARIES "${node_libs}")
+  foreach(target dawn_node dawn_node_binding dawn_node_interop)
+    target_compile_definitions(${target} PRIVATE WGPU_SHARED_LIBRARY DAWN_NATIVE_SHARED_LIBRARY)
+  endforeach()
+
+  target_sources(dawn_node PRIVATE src/node/extensions.cpp)
+  target_include_directories(dawn_node PRIVATE src/node include)
+
+  if(APPLE)
+    set_target_properties(dawn_node PROPERTIES INSTALL_RPATH "@loader_path" BUILD_WITH_INSTALL_RPATH ON)
+  elseif(UNIX)
+    set_target_properties(dawn_node PROPERTIES INSTALL_RPATH "$ORIGIN" BUILD_WITH_INSTALL_RPATH ON)
+  endif()
+
+  # The addon sits next to the shared library: lib/ on Linux and macOS, bin/ on
+  # Windows, where Node resolves an addon's DLLs from the addon's own directory.
+  install(TARGETS dawn_node
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+endif()
+
+install(DIRECTORY include/native_dawn DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(FILES "${DAWN_SOURCE_DIR}/src/dawn/dawn.json" DESTINATION share/native-dawn)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Montes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,9 @@
+native-dawn builds Google's Dawn WebGPU implementation and its Node-API
+bindings. Dawn source: https://dawn.googlesource.com/dawn
+The exact revision is recorded in upstream.json. Binary archives include the
+Dawn license and the licenses of its bundled dependencies under
+share/native-dawn/licenses.
+
+The handling of @kmamal/sdl window handles follows Konstantin M's
+@kmamal/gpu (MIT): https://github.com/kmamal/gpu, at the revision recorded
+in upstream.json.

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# native-dawn
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Prebuilt [Dawn](https://dawn.googlesource.com/dawn), Google's WebGPU implementation, packaged for two kinds of users:
+
+- **Native code.** A shared `webgpu_dawn` library, the WebGPU C and C++ headers, and a CMake package, so a C or C++ program can use WebGPU without building Dawn.
+- **Node.js.** Dawn's own Node-API bindings, built against that same library, plus a swap chain for native windows.
+
+It is the WebGPU counterpart of [native-gles](https://github.com/monteslu/native-gles): the native layer, kept separate from the browser-style JavaScript API that sits on top of it (webgpu-node, as [webgl-node](https://github.com/monteslu/webgl-node) is for native-gles).
+
+Because the Node addon links the shared library instead of carrying its own copy of Dawn, JavaScript and native code in one process use the same Dawn. A `GPUDevice` created in JavaScript can be handed to a C++ addon as a `WGPUDevice`.
+
+## Install
+
+```sh
+npm install native-dawn
+```
+
+Installation downloads the archive for your platform from this repository's GitHub releases, checks its SHA-256 and version, and loads the addon once to make sure it works. If that fails (an unsupported platform, no network, a C library too old for the binary), the install prints a warning and still succeeds, so packages that depend on native-dawn install everywhere; importing native-dawn then throws. A corrupt or mismatched archive is never installed. Set `NATIVE_DAWN_STRICT_INSTALL=1` to make install failures fatal.
+
+| Platform | Architectures | Backend |
+| --- | --- | --- |
+| Linux (glibc 2.34+: Ubuntu 22.04, Debian 12 and newer) | x64, arm64 | Vulkan |
+| macOS 11+ | x64, arm64 | Metal |
+| Windows | x64, arm64 | D3D12 |
+| Android 8.0+ (API 26), C SDK only | arm64 | Vulkan, OpenGL ES |
+
+Linux builds support X11 and Wayland windows and also include the OpenGL ES backend (see [OpenGL ES](#opengl-es-compatibility-mode)). The Node addon needs Node.js 22 or newer.
+
+## Using it from Node
+
+```js
+import { create, globals } from 'native-dawn'
+
+const gpu = create([])  // Dawn instance flags, e.g. ['backend=vulkan']
+const adapter = await gpu.requestAdapter()
+const device = await adapter.requestDevice()
+
+const buffer = device.createBuffer({ size: 16, usage: globals.GPUBufferUsage.COPY_DST | globals.GPUBufferUsage.MAP_READ })
+```
+
+`gpu`, `adapter` and `device` are standard WebGPU objects. `globals` holds the WebGPU classes and constants (`GPUBufferUsage`, `GPUDevice`, `GPUValidationError`, ...). Nothing is installed on `globalThis` or `navigator`; webgpu-node does that, along with a canvas and `GPUCanvasContext`.
+
+Adapters and devices stay valid even if the `gpu` object is garbage collected. Call `device.destroy()` when you are done to release GPU memory promptly. Only pending asynchronous work (a `mapAsync`, `onSubmittedWorkDone`, pipeline creation and the like) keeps Node running; an idle device does not, and it costs no CPU. Dawn notices a lost device (a driver reset, for example) on the next WebGPU call or asynchronous operation, and `device.lost` settles then.
+
+### Presenting to a window
+
+`NativeSurface` is a swap chain for a native window. With [@kmamal/sdl](https://github.com/kmamal/node-sdl):
+
+```js
+import sdl from '@kmamal/sdl'
+import { create, NativeSurface, globals } from 'native-dawn'
+
+const window = sdl.video.createWindow({ width: 640, height: 480, webgpu: true })
+const gpu = create([])
+const device = await (await gpu.requestAdapter()).requestDevice()
+
+const surface = new NativeSurface(device, window.native.gpu, sdl.info.drivers.video.current)
+surface.configure({
+  width: window.pixelWidth,
+  height: window.pixelHeight,
+  format: gpu.getPreferredCanvasFormat(),
+  usage: globals.GPUTextureUsage.RENDER_ATTACHMENT,
+})
+
+// Each frame:
+const texture = surface.getCurrentTexture()
+// ... render into texture, submit ...
+surface.present()
+```
+
+The third argument matters on Linux. @kmamal/sdl 0.11 hands over the same two pointers for X11 and Wayland windows without saying which they are, so `NativeSurface` needs the video driver name. Without it you get an error instead of a guess.
+
+Windows from other libraries work too. Pass the native handles as BigInts:
+
+```js
+new NativeSurface(device, { kind: 'xlib', display, xid })
+new NativeSurface(device, { kind: 'wayland', display, handle })     // wl_display*, wl_surface*
+new NativeSurface(device, { kind: 'win32', display, handle })       // HINSTANCE, HWND
+new NativeSurface(device, { kind: 'metal-layer', handle })          // CAMetalLayer*
+```
+
+`configure` accepts `alphaMode` (`opaque`, `premultiplied`), `presentMode` (`fifo` by default, or `fifoRelaxed`, `immediate`, `mailbox`) and `viewFormats`, and checks each against what the surface supports. Call `configure` again after the window resizes. The window belongs to you: call `surface.destroy()` before destroying it.
+
+### Sharing a device with native code
+
+```js
+import { deviceHandle } from 'native-dawn'
+const pointer = deviceHandle(device)  // BigInt: the WGPUDevice
+```
+
+The pointer is valid while the `GPUDevice` is alive. Native code that holds on to it longer should call `wgpuDeviceAddRef`. This works because the addon and your native code load the same `webgpu_dawn` library; build your addon against native-dawn's headers and library (see below).
+
+## Using it from C or C++
+
+The package holds a normal install prefix:
+
+```
+include/webgpu/webgpu.h          WebGPU C API
+include/webgpu/webgpu_cpp.h      C++ wrapper
+include/dawn/...                 Dawn extensions
+include/native_dawn/window.h     window helpers (see below)
+lib/libwebgpu_dawn.so            .dylib on macOS; bin/webgpu_dawn.dll and lib/webgpu_dawn.lib on Windows
+lib/cmake/Dawn/                  CMake package: dawn::webgpu_dawn
+share/native-dawn/dawn.json      Dawn's description of the whole API
+share/native-dawn/licenses/      licenses for everything in the binaries
+```
+
+Point CMake at it:
+
+```sh
+cmake -B build -DCMAKE_PREFIX_PATH="$(npx native-dawn prefix)"
+```
+
+```cmake
+find_package(Dawn REQUIRED)
+target_link_libraries(my_app PRIVATE dawn::webgpu_dawn)
+```
+
+You don't need npm for this. Each GitHub release has a `native-dawn-v<version>-<platform>-<arch>.tar.gz` that unpacks to the same prefix. On Linux and macOS the library is found through the executable's rpath when CMake links it. On Windows, put `webgpu_dawn.dll`, `dxcompiler.dll` and `dxil.dll` next to your executable or on `PATH`.
+
+[test/c/compute.c](test/c/compute.c) is a complete program: adapter and device setup, a compute shader, an offscreen render pass, and reading both back.
+
+### Window helpers
+
+`native_dawn/window.h` is header-only and needs nothing but `webgpu.h`. Describe the window, get a surface:
+
+```c
+#include <native_dawn/window.h>
+
+NativeDawnWindow window = { NATIVE_DAWN_WINDOW_XLIB, display, NULL, xid };
+WGPUSurface surface = nativeDawnCreateSurface(instance, &window);
+```
+
+If you use SDL2, `native_dawn/sdl2.h` fills that in from an `SDL_Window*` for X11, Wayland, Windows and macOS (create the window with `SDL_WINDOW_METAL` on macOS):
+
+```c
+#include <native_dawn/sdl2.h>
+
+NativeDawnSDL2Window native;
+if (nativeDawnSDL2Window(sdlWindow, &native) != 0) { /* SDL_GetError() */ }
+WGPUSurface surface = nativeDawnCreateSurface(instance, &native.window);
+/* ... */
+wgpuSurfaceRelease(surface);
+nativeDawnSDL2Release(&native);
+```
+
+[test/c/sdl2_window.c](test/c/sdl2_window.c) configures a surface, presents frames and handles a resize.
+
+### OpenGL ES (compatibility mode)
+
+GPUs without a Vulkan driver, such as the Mali-G31 in many Allwinner H700 handhelds, can still run WebGPU through Dawn's OpenGL ES backend. It needs OpenGL ES 3.1 or newer; ES 3.0 lacks the compute shaders and storage buffers that WebGPU requires. WGSL vertex, fragment and compute shaders are all translated to GLSL ES.
+
+This backend implements WebGPU's compatibility mode, a reduced feature level for OpenGL ES 3.1 and Direct3D 11 class hardware. Ask for it explicitly:
+
+```c
+WGPURequestAdapterOptions options = WGPU_REQUEST_ADAPTER_OPTIONS_INIT;
+options.featureLevel = WGPUFeatureLevel_Compatibility;
+options.backendType = WGPUBackendType_OpenGLES;  // optional: prefer it over Vulkan
+```
+
+```js
+const adapter = await gpu.requestAdapter({ featureLevel: 'compatibility' })
+```
+
+Code written for compatibility mode also runs on full WebGPU. On Linux the backend reaches the driver through EGL; without an X11 or Wayland session, set `EGL_PLATFORM=surfaceless`.
+
+Known driver bug: with Mesa 26.0.8 (the only version seen so far, on radeonsi and llvmpipe), creating a render pipeline on this backend crashes inside Mesa whenever the GL program comes from Mesa's on-disk shader cache, so the first run works and later runs segfault. Set `MESA_SHADER_CACHE_DISABLE=true` until Mesa is fixed. The Vulkan backend is not affected. Presenting needs an X11, Wayland or Android window: Dawn has no surface type for direct KMS/DRM output, so on such systems this mode is limited to compute and offscreen rendering.
+
+## Android
+
+The Android archive (`android-arm64`) holds the C SDK: `libwebgpu_dawn.so`, headers, the CMake package and `dawn.json`. There is no Node addon for Android, and npm installs don't fetch these; download them from the GitHub release. The library uses the static C++ runtime, needs only system libraries, and is aligned for 16 KB pages.
+
+With the NDK and CMake:
+
+```sh
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
+  -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-26 \
+  -DDawn_DIR=/path/to/native-dawn-android-arm64/lib/cmake/Dawn
+```
+
+Package `lib/libwebgpu_dawn.so` with your app's other native libraries (`jniLibs/arm64-v8a/`, or `IMPORTED_LOCATION` in an Android Gradle CMake build). For a window, pass the `ANativeWindow*` from your `Surface`:
+
+```c
+NativeDawnWindow window = { NATIVE_DAWN_WINDOW_ANDROID, NULL, aNativeWindow, 0 };
+WGPUSurface surface = nativeDawnCreateSurface(instance, &window);
+```
+
+or use `native_dawn/sdl2.h` with an SDL2 Android app. Vulkan is used where the device has it; OpenGL ES 3.1+ is available through compatibility mode. Kotlin and Java apps are better served by Google's `androidx.webgpu` library, which is built from Dawn too.
+
+### Bindings for other runtimes
+
+`share/native-dawn/dawn.json` is the file Dawn generates its own headers and wrappers from: every object, method, struct, enum and callback in the API. A binding for another JavaScript engine or language can be generated from it rather than written by hand. `npx native-dawn dawn-json` prints its path.
+
+## Building from source
+
+You need Git, Python 3, Go 1.26+, CMake 3.22+, a C++20 compiler, and Ninja (Linux and macOS). On Windows use Visual Studio 2022 with the C++ tools and a recent Windows SDK; run the build from a developer command prompt to get Ninja and compiler caching, or from a plain prompt to use the Visual Studio generator.
+
+Linux packages (Debian/Ubuntu names):
+
+```sh
+sudo apt-get install ninja-build libx11-dev libx11-xcb-dev libxcb1-dev libxrandr-dev libxinerama-dev \
+  libxcursor-dev libxi-dev libwayland-dev libvulkan1 mesa-vulkan-drivers
+```
+
+Then:
+
+```sh
+npm ci --ignore-scripts
+npm run build
+```
+
+The build fetches the Dawn revision pinned in `upstream.json` and the dependencies Dawn pins for it (no depot_tools), builds `webgpu_dawn` and the addon, and installs the result to `dist/<platform>-<arch>`. Sources go in `.cache/dawn`, build files in `build/<platform>-<arch>`. A first build takes a while; Dawn is large.
+
+Android builds cross-compile from Linux, macOS or Windows with the NDK (r27 or newer) and need no Go:
+
+```sh
+NATIVE_DAWN_TARGET=android-arm64 npm run build
+```
+
+The NDK is found through `ANDROID_NDK_HOME`, `ANDROID_NDK_ROOT`, or the newest one under `$ANDROID_HOME/ndk`.
+
+Environment variables:
+
+| Variable | Effect |
+| --- | --- |
+| `NATIVE_DAWN_TARGET` | `android-arm64` to cross-compile; default is this machine |
+| `NATIVE_DAWN_BUILD_JOBS` | Parallel compile jobs (default: up to 8) |
+| `NATIVE_DAWN_COMPILER_LAUNCHER` | Compiler launcher such as `sccache` or `ccache` |
+| `NATIVE_DAWN_BUILD_FROM_SOURCE=1` | Make `npm install` build instead of downloading |
+| `NATIVE_DAWN_BINARY=/path/to/archive.tar.gz` | Install a local archive (with its `.sha256` beside it) |
+| `NATIVE_DAWN_SKIP_INSTALL=1` | Skip the install step entirely |
+| `NATIVE_DAWN_STRICT_INSTALL=1` | Fail `npm install` when no native build can be installed |
+
+## Tests
+
+```sh
+npm test                          # Node: compute, mapping, validation, rendering, surface errors, installer
+npm run test:types                # TypeScript declarations
+npm run test:c                    # C programs built against dist/ with find_package(Dawn)
+NATIVE_DAWN_TEST_SDL2=1 npm run test:c    # plus the SDL2 window test
+npm run test:window               # Node + @kmamal/sdl window (needs a display)
+npm run test:package              # pack, install into a scratch project, run from Node and C
+NATIVE_DAWN_TARGET=android-arm64 npm run test:android   # C test on the device or emulator adb sees
+```
+
+Tests need a working adapter, hardware or software (Mesa's lavapipe on Linux, WARP on Windows), and fail without one rather than skipping. `NATIVE_DAWN_TEST_BACKEND=vulkan|metal|d3d12|opengles` picks a backend, `NATIVE_DAWN_TEST_COMPAT=1` requests compatibility mode (required for `opengles`), and `NATIVE_DAWN_TEST_FALLBACK=1` asks for a fallback adapter. The Android emulator only offers OpenGL ES 3.0, so it tests Vulkan; on Linux, `EGL_PLATFORM=surfaceless NATIVE_DAWN_TEST_BACKEND=opengles NATIVE_DAWN_TEST_COMPAT=1 npm run test:c` tests OpenGL ES. On headless Linux, run the window tests under `xvfb-run -a` with `SDL_VIDEODRIVER=x11`.
+
+## CI and releases
+
+[CI](.github/workflows/ci.yml) builds the six desktop targets on native runners and runs every suite above on each one, on Node 22 and 24, against the runner's software adapter. Linux also runs the C tests on OpenGL ES in compatibility mode. The window tests run everywhere except Windows ARM64, which has no @kmamal/sdl build. Android is cross-compiled on Linux and its C tests run on an x86_64 Android emulator, through Android's ARM translation.
+
+Pushing a `v<version>` tag that matches `package.json` runs the same jobs, and if all seven pass, creates a GitHub release with the seven archives and their checksums. npm publishing is a separate, manual step after that, since `npm install` downloads from the release.
+
+## License
+
+MIT for this package. Dawn and its dependencies keep their own licenses; see [NOTICE](NOTICE) and `share/native-dawn/licenses` in each archive.

package/bin/native-dawn.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Prints install locations for build systems, e.g.
+//   cmake -DCMAKE_PREFIX_PATH="$(npx native-dawn prefix)" ...
+import { paths } from '../paths.js'
+
+const keys = { prefix: 'prefix', include: 'include', lib: 'lib', bin: 'bin', cmake: 'cmake', library: 'library', addon: 'addon', 'dawn-json': 'dawnJson', licenses: 'licenses' }
+const name = process.argv[2]
+if (!keys[name]) {
+  console.error(`usage: native-dawn <${Object.keys(keys).join('|')}>`)
+  process.exit(2)
+}
+console.log(paths[keys[name]])

package/include/native_dawn/sdl2.h

@@ -0,0 +1,88 @@
+/*
+ * native-dawn: fill a NativeDawnWindow from an SDL2 window.
+ *
+ * Header-only and optional; include it only when the program already uses
+ * SDL2 (X11, Wayland, Windows, macOS, Android). On macOS, create the window
+ * with SDL_WINDOW_METAL. Call nativeDawnSDL2Release after releasing the
+ * surface.
+ */
+#ifndef NATIVE_DAWN_SDL2_H_
+#define NATIVE_DAWN_SDL2_H_
+
+#include <SDL.h>
+#include <SDL_syswm.h>
+#if defined(SDL_VIDEO_DRIVER_COCOA) || defined(SDL_VIDEO_DRIVER_UIKIT)
+#include <SDL_metal.h>
+#endif
+#include "native_dawn/window.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct NativeDawnSDL2Window {
+    NativeDawnWindow window;
+    void* metalView; /* SDL_MetalView created for Cocoa windows */
+} NativeDawnSDL2Window;
+
+/* Returns 0 on success, or -1 with SDL_GetError() describing the failure. */
+static inline int nativeDawnSDL2Window(SDL_Window* sdlWindow, NativeDawnSDL2Window* out) {
+    SDL_SysWMinfo info;
+    SDL_zerop(out);
+    SDL_VERSION(&info.version);
+    if (!SDL_GetWindowWMInfo(sdlWindow, &info)) return -1;
+    switch (info.subsystem) {
+#if defined(SDL_VIDEO_DRIVER_X11)
+        case SDL_SYSWM_X11:
+            out->window.kind = NATIVE_DAWN_WINDOW_XLIB;
+            out->window.display = info.info.x11.display;
+            out->window.xid = (uint64_t)info.info.x11.window;
+            return 0;
+#endif
+#if defined(SDL_VIDEO_DRIVER_WAYLAND)
+        case SDL_SYSWM_WAYLAND:
+            out->window.kind = NATIVE_DAWN_WINDOW_WAYLAND;
+            out->window.display = info.info.wl.display;
+            out->window.handle = info.info.wl.surface;
+            return 0;
+#endif
+#if defined(SDL_VIDEO_DRIVER_WINDOWS)
+        case SDL_SYSWM_WINDOWS:
+            out->window.kind = NATIVE_DAWN_WINDOW_WIN32;
+            out->window.display = info.info.win.hinstance;
+            out->window.handle = info.info.win.window;
+            return 0;
+#endif
+#if defined(SDL_VIDEO_DRIVER_ANDROID)
+        case SDL_SYSWM_ANDROID:
+            out->window.kind = NATIVE_DAWN_WINDOW_ANDROID;
+            out->window.handle = info.info.android.window;
+            return 0;
+#endif
+#if defined(SDL_VIDEO_DRIVER_COCOA) || defined(SDL_VIDEO_DRIVER_UIKIT)
+        case SDL_SYSWM_COCOA:
+        case SDL_SYSWM_UIKIT:
+            out->metalView = SDL_Metal_CreateView(sdlWindow);
+            if (!out->metalView) return -1;
+            out->window.kind = NATIVE_DAWN_WINDOW_METAL_LAYER;
+            out->window.handle = SDL_Metal_GetLayer((SDL_MetalView)out->metalView);
+            return 0;
+#endif
+        default:
+            SDL_SetError("native-dawn: unsupported SDL window subsystem %d", (int)info.subsystem);
+            return -1;
+    }
+}
+
+static inline void nativeDawnSDL2Release(NativeDawnSDL2Window* window) {
+#if defined(SDL_VIDEO_DRIVER_COCOA) || defined(SDL_VIDEO_DRIVER_UIKIT)
+    if (window->metalView) SDL_Metal_DestroyView((SDL_MetalView)window->metalView);
+#endif
+    window->metalView = NULL;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* NATIVE_DAWN_SDL2_H_ */

package/include/native_dawn/window.h

@@ -0,0 +1,102 @@
+/*
+ * native-dawn: create a WebGPU surface from a native window.
+ *
+ * Header-only. Include it after linking dawn::webgpu_dawn; it uses nothing
+ * but the WebGPU C API. The caller owns the window and must release the
+ * surface (wgpuSurfaceRelease) before destroying it.
+ */
+#ifndef NATIVE_DAWN_WINDOW_H_
+#define NATIVE_DAWN_WINDOW_H_
+
+#include <stddef.h>
+#include <stdint.h>
+#include <webgpu/webgpu.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum NativeDawnWindowKind {
+    NATIVE_DAWN_WINDOW_XLIB = 1,        /* display: Display*, xid: Window */
+    NATIVE_DAWN_WINDOW_WAYLAND = 2,     /* display: wl_display*, handle: wl_surface* */
+    NATIVE_DAWN_WINDOW_WIN32 = 3,       /* display: HINSTANCE, handle: HWND */
+    NATIVE_DAWN_WINDOW_METAL_LAYER = 4, /* handle: CAMetalLayer* */
+    NATIVE_DAWN_WINDOW_ANDROID = 5      /* handle: ANativeWindow* */
+} NativeDawnWindowKind;
+
+typedef struct NativeDawnWindow {
+    NativeDawnWindowKind kind;
+    void* display;
+    void* handle;
+    uint64_t xid;
+} NativeDawnWindow;
+
+/* Returns NULL when the window is complete, otherwise what is missing. */
+static inline const char* nativeDawnWindowError(const NativeDawnWindow* window) {
+    if (!window) return "window is NULL";
+    switch (window->kind) {
+        case NATIVE_DAWN_WINDOW_XLIB:
+            return window->display && window->xid ? NULL : "Xlib window needs display and xid";
+        case NATIVE_DAWN_WINDOW_WAYLAND:
+            return window->display && window->handle ? NULL : "Wayland window needs display and handle (wl_surface)";
+        case NATIVE_DAWN_WINDOW_WIN32:
+            return window->handle ? NULL : "Win32 window needs handle (HWND)";
+        case NATIVE_DAWN_WINDOW_METAL_LAYER:
+            return window->handle ? NULL : "Metal window needs handle (CAMetalLayer)";
+        case NATIVE_DAWN_WINDOW_ANDROID:
+            return window->handle ? NULL : "Android window needs handle (ANativeWindow)";
+    }
+    return "unknown window kind";
+}
+
+/*
+ * Creates a surface for the window, or returns NULL if the window description
+ * is incomplete. A kind the platform does not support yields an error surface
+ * from Dawn, which fails wgpuSurfaceGetCapabilities.
+ */
+static inline WGPUSurface nativeDawnCreateSurface(WGPUInstance instance, const NativeDawnWindow* window) {
+    WGPUSurfaceDescriptor descriptor = WGPU_SURFACE_DESCRIPTOR_INIT;
+    if (!instance || nativeDawnWindowError(window)) return NULL;
+    switch (window->kind) {
+        case NATIVE_DAWN_WINDOW_XLIB: {
+            WGPUSurfaceSourceXlibWindow source = WGPU_SURFACE_SOURCE_XLIB_WINDOW_INIT;
+            source.display = window->display;
+            source.window = window->xid;
+            descriptor.nextInChain = &source.chain;
+            return wgpuInstanceCreateSurface(instance, &descriptor);
+        }
+        case NATIVE_DAWN_WINDOW_WAYLAND: {
+            WGPUSurfaceSourceWaylandSurface source = WGPU_SURFACE_SOURCE_WAYLAND_SURFACE_INIT;
+            source.display = window->display;
+            source.surface = window->handle;
+            descriptor.nextInChain = &source.chain;
+            return wgpuInstanceCreateSurface(instance, &descriptor);
+        }
+        case NATIVE_DAWN_WINDOW_WIN32: {
+            WGPUSurfaceSourceWindowsHWND source = WGPU_SURFACE_SOURCE_WINDOWS_HWND_INIT;
+            source.hinstance = window->display;
+            source.hwnd = window->handle;
+            descriptor.nextInChain = &source.chain;
+            return wgpuInstanceCreateSurface(instance, &descriptor);
+        }
+        case NATIVE_DAWN_WINDOW_METAL_LAYER: {
+            WGPUSurfaceSourceMetalLayer source = WGPU_SURFACE_SOURCE_METAL_LAYER_INIT;
+            source.layer = window->handle;
+            descriptor.nextInChain = &source.chain;
+            return wgpuInstanceCreateSurface(instance, &descriptor);
+        }
+        case NATIVE_DAWN_WINDOW_ANDROID: {
+            WGPUSurfaceSourceAndroidNativeWindow source = WGPU_SURFACE_SOURCE_ANDROID_NATIVE_WINDOW_INIT;
+            source.window = window->handle;
+            descriptor.nextInChain = &source.chain;
+            return wgpuInstanceCreateSurface(instance, &descriptor);
+        }
+    }
+    return NULL;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* NATIVE_DAWN_WINDOW_H_ */

package/index.d.ts

@@ -0,0 +1,56 @@
+/// <reference types="@webgpu/types" />
+import type { NativeDawnPaths } from './paths.js'
+
+export { paths } from './paths.js'
+export type { NativeDawnPaths }
+
+/** An X11, Wayland, Win32 or Metal window, with pointers as BigInt. */
+export interface NativeWindow {
+  kind: 'xlib' | 'wayland' | 'win32' | 'metal-layer'
+  /** Display* (xlib), wl_display* (wayland) or HINSTANCE (win32). */
+  display?: bigint | number
+  /** wl_surface* (wayland), HWND (win32) or CAMetalLayer* (metal-layer). */
+  handle?: bigint | number
+  /** X11 Window id (xlib). */
+  xid?: bigint | number
+}
+
+export interface NativeSurfaceConfiguration {
+  width: number
+  height: number
+  format: GPUTextureFormat
+  usage: number
+  alphaMode?: 'opaque' | 'premultiplied'
+  presentMode?: 'fifo' | 'fifoRelaxed' | 'immediate' | 'mailbox'
+  viewFormats?: GPUTextureFormat[]
+}
+
+/** A swap chain for a native window. */
+export declare class NativeSurface {
+  /**
+   * @param window An @kmamal/sdl `window.native.gpu` buffer, or a NativeWindow.
+   * @param videoDriver For SDL buffers on Linux: 'x11' or 'wayland'
+   *   (sdl.info.drivers.video.current).
+   */
+  constructor(device: GPUDevice, window: Buffer | NativeWindow, videoDriver?: string)
+  configure(configuration: NativeSurfaceConfiguration): void
+  getCurrentTexture(): GPUTexture
+  present(): void
+  unconfigure(): void
+  destroy(): void
+}
+
+/** Dawn instance flags as `key=value` strings, e.g. `backend=vulkan`. */
+export declare function create(flags: string[]): GPU
+/** The WGPUDevice pointer behind a GPUDevice, for native code in this process. */
+export declare function deviceHandle(device: GPUDevice): bigint
+/** WebGPU interface objects and constants (GPUBufferUsage, GPUDevice, ...). */
+export declare const globals: Record<string, unknown>
+
+declare const addon: {
+  create: typeof create
+  globals: typeof globals
+  NativeSurface: typeof NativeSurface
+  deviceHandle: typeof deviceHandle
+}
+export default addon

package/index.js

@@ -0,0 +1,13 @@
+import { createRequire } from 'node:module'
+import { paths } from './paths.js'
+
+let addon
+try {
+  addon = createRequire(import.meta.url)(paths.addon)
+} catch (cause) {
+  throw new Error(`native-dawn: cannot load the ${paths.target} addon from ${paths.addon}. Run npm install, or npm run build in a source checkout. ${cause.message}`, { cause })
+}
+
+export { paths }
+export const { create, globals, NativeSurface, deviceHandle } = addon
+export default addon