Google Git
Sign in
dawn / dawn / refs/heads/chromium/4866 / . / src / dawn_node
tree: 03111352fce38d7b5b965f7b2baf2c3f690218d9 [path history] [tgz]
  1. binding/
  2. interop/
  3. tools/
  4. utils/
  5. CMakeLists.txt
  6. Module.cpp
  7. NapiSymbols.cpp
  8. OWNERS
  9. README.md
src/dawn_node/README.md

Dawn bindings for NodeJS

Note: This code is currently WIP. There are a number of known issues.

Building

System requirements

Install depot_tools

Dawn uses the Chromium build system and dependency management so you need to install depot_tools and add it to the PATH.

Fetch dependencies

First, the steps are similar to doc/building.md, but instead of the Get the code step, run:

# Clone the repo as "dawn"
git clone https://dawn.googlesource.com/dawn dawn && cd dawn

# Bootstrap the NodeJS binding gclient configuration
cp scripts/standalone-with-node.gclient .gclient

# Fetch external dependencies and toolchains with gclient
gclient sync

Optionally, on Linux install X11-xcb support:

sudo apt-get install libx11-xcb-dev

If you don't have those supporting libraries, then you must use the -DDAWN_USE_X11=OFF flag on Cmake.

Build

Currently, the node bindings can only be built with CMake:

mkdir <build-output-path>
cd <build-output-path>
cmake <dawn-root-path> -GNinja -DDAWN_BUILD_NODE_BINDINGS=1 -DDAWN_ENABLE_PIC=1 -DDAWN_USE_X11=OFF
ninja dawn.node

Running WebGPU CTS

  1. Build the dawn.node NodeJS module.
  2. Checkout the WebGPU CTS repo
  • Run npm install from inside the CTS directory to install its dependencies
./src/dawn_node/tools/run-cts --cts=<path-to-webgpu-cts> --dawn-node=<path-to-dawn.node> [WebGPU CTS query]

If this fails with the error message TypeError: expander is not a function or its return value is not iterable, try appending --build=false to the start of the run-cts command line flags.

To test against SwiftShader instead of the default Vulkan device, prefix ./src/dawn_node/tools/run-cts with VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json and append --flag=dawn-backend=vulkan to the start of run-cts command line flags. For example:

VK_ICD_FILENAMES=<swiftshader-cmake-build>/Linux/vk_swiftshader_icd.json ./src/dawn_node/tools/run-cts --cts=<path-to-webgpu-cts> --dawn-node=<path-to-dawn.node> --flag=dawn-backend=vulkan [WebGPU CTS query]

The --flag parameter must be passed in multiple times, once for each flag begin set. Here are some common arguments:

  • dawn-backend=<null|webgpu|d3d11|d3d12|metal|vulkan|opengl|opengles>
  • dlldir=<path> - used to add an extra DLL search path on Windows, primarily to load the right d3dcompiler_47.dll
  • enable-dawn-features=<features> - enable Dawn toggles, e.g. dump_shaders
  • disable-dawn-features=<features> - disable Dawn toggles

For example, on Windows, to use the d3dcompiler_47.dll from a Chromium checkout, and to dump shader output, we could run the following using Git Bash:

./src/dawn_node/tools/run-cts --verbose --dawn-node=/c/src/dawn/build/Debug/dawn.node --cts=/c/src/gpuweb-cts --flag=dlldir="C:\src\chromium\src\out\Release" --flag=enable-dawn-features=dump_shaders 'webgpu:shader,execution,builtin,abs:integer_builtin_functions,abs_unsigned:storageClass="storage";storageMode="read_write";containerType="vector";isAtomic=false;baseType="u32";type="vec2%3Cu32%3E"'

Note that we pass --verbose above so that all test output, including the dumped shader, is written to stdout.

Testing against a run-cts expectations file

You can write out an expectations file with the --output <path> command line flag, and then compare this snapshot to a later run with --expect <path>.

Debugging TypeScript with VSCode

Open or create the .vscode/launch.json file, and add:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug with node",
            "type": "node",
            "request": "launch",
            "outFiles": [ "./**/*.js" ],
            "args": [
                "-e", "require('./src/common/tools/setup-ts-in-node.js');require('./src/common/runtime/cmdline.ts');",
                "--", "dummy-arg",
                "--gpu-provider",
                "[path-to-dawn.node]", // REPLACE: [path-to-dawn.node]
                "[test-query]", // REPLACE: [test-query]
            ],
            "cwd": "[cts-root]" // REPLACE: [cts-root]
        }
    ]
}

Replacing:

  • [cts-root] with the path to the CTS root directory. If you are editing the .vscode/launch.json from within the CTS workspace, then you may use ${workspaceFolder}.
  • [path-to-dawn.node] this the path to the dawn.node module built by the build step
  • test-query with the test query string. Example: webgpu:shader,execution,builtin,abs:*

Known issues

  • Many WebGPU CTS tests are currently known to fail
  • Dawn uses special token values for some parameters / fields. These are currently passed straight through to dawn from the JavaScript. discussions: 1, 2, 3
  • Backend validation is currently always set to ‘full’ to aid in debugging. This can be extremely slow. discussion
  • Attempting to call new T in JavaScript, where T is an IDL interface type, should result in a TypeError “Illegal constructor”. discussion
  • GPUDevice currently maintains a list of “lost promises”. This should return the same promise. discussion

Remaining work