initial commit

.github/workflows/build-and-deploy.yml

@@ -0,0 +1,34 @@
+name: Build and Deploy
+on:
+  push:
+    tags:
+      - v*
+permissions:
+  contents: write
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment: deploy
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+
+      - name: Use Node.js 😂
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install and Build 🔧
+        run: |
+          npm ci
+          npm run build-ci
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: .
+
+      - name: Publish to NPM 📖
+        uses: JS-DevTools/npm-publish@v2
+        with:
+          token: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🍔🍟🥤
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+
+      - name: Use Node.js 😂
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Test 🧪
+        run: |
+          npm ci
+          npm run check-ci

.gitignore

@@ -0,0 +1,28 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# -- clip-for-deploy-start --
+
+/docs
+/dist
+index.html
+
+# -- clip-for-deploy-end --
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Gregg Tavares
+
+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.

README.md

@@ -0,0 +1,56 @@
+# webgpu-debug-helper
+
+![](https://img.shields.io/npm/v/webgpu-debug-helper)
+
+## A WebGPU debugging helper script
+
+This script makes it easier to debug WebGPU apps.
+
+You can use it in your own projects via a script OR, you can
+[use it as an extension](https://github.com/greggman/webgpu-dev-extension).
+
+At the moment, if you want to use it to help debug workers, you'll need
+to use this script version.
+
+## What does it do?
+
+* It makes as many errors as possible to return the line they happened on
+
+  This is in contrast to normal WebGPU where errors are returned asynchronously
+  and so the command that caused the error is long forgotten.
+
+* It adds errors to command encoders and pass encoders
+
+  In normal WebGPU, command encoders and pass encoders often do not report errors.
+  Rather, they record the error, make the encoder as *invalid*, and then only report
+  the error when the encoder is ended/finished. This can make it hard to find errors.
+
+  With this script, many of these types of errors will be generated immediately.
+
+## Usage:
+
+```js
+import './webgpu-debug-helper.js';
+```
+
+or
+
+```js
+import 'https://greggman.github.io/webgpu-debug-helper/dist/0.x/webgpu-debug-helper.js';
+```
+
+There is nothing else to do. The webgpu-debug-helper will wrap the WebGPU API and
+star generating errors.
+
+If you wanted to import programmatically you could do something like this
+
+```js
+if (debugging) {
+  await import('./webgpu-debug-helper.js');
+}
+```
+
+## License
+
+[MIT](LICENSE.md)
+

TODO.md

@@ -0,0 +1,6 @@
+# To Do
+
+* add encoder and pass error checking
+* track group layouts,
+* track pipeline layouts,
+* track look up layouts via webgpu-utils

build/tools/fixup.d.ts.js

@@ -0,0 +1,18 @@
+import fs from 'fs';
+import path from 'path';
+import * as url from 'url';
+
+const dirname = url.fileURLToPath(new URL('.', import.meta.url));
+const readTextFile = n => fs.readFileSync(n, {encoding: 'utf-8'});
+
+const pkg = JSON.parse(readTextFile(path.join(dirname, '..', '..', 'package.json')));
+const majorVersion = pkg.version.split('.')[0];
+
+const dtsFilename = path.join(dirname, '..', '..', 'dist', `${majorVersion}.x`, 'buffer-views.d.ts');
+const s = readTextFile(dtsFilename);
+const newS = s.replace(
+  /export\s+type\s+ArrayBufferViews\s+=\s+{\s+views:\s+TypedArrayOrViews;/m,
+  `export type ArrayBufferViews = {
+    views: any; // because otherwise this is too much of a PITA to use in typescript`);
+console.assert(s !== newS, `fixup failed: did you build first?\n`);
+fs.writeFileSync(dtsFilename, newS);

build/tools/makeindex.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import path from 'path';
+import MarkdownIt from 'markdown-it';
+import * as url from 'url';
+const dirname = url.fileURLToPath(new URL('.', import.meta.url));
+
+// eslint-disable-next-line new-cap
+const md = MarkdownIt({
+  html: true,
+  langPrefix: 'lang-',
+  typographer: true,
+  quotes: '“”‘’',
+});
+
+const pkg = JSON.parse(fs.readFileSync(path.join(dirname, '..', '..', 'package.json'), {encoding: 'utf8'}));
+
+function getLicense(pkg) {
+  return `@license webgpu-utils ${pkg.version} Copyright (c) 2023, Gregg Tavares All Rights Reserved.
+Available via the MIT license.
+see: http://github.com/greggman/webgpu-utils for details`;
+}
+
+/**
+ * Replace %(id)s in strings with values in objects(s)
+ *
+ * Given a string like `"Hello %(name)s from %(user.country)s"`
+ * and an object like `{name:"Joe",user:{country:"USA"}}` would
+ * return `"Hello Joe from USA"`.
+ *
+ * @param {string} str string to do replacements in
+ * @param {Object|Object[]} params one or more objects.
+ * @returns {string} string with replaced parts
+ */
+const replaceParams = (function () {
+  const replaceParamsRE = /%\(([^)]+)\)s/g;
+
+  return function (str, params) {
+    if (!params.length) {
+      params = [params];
+    }
+
+    return str.replace(replaceParamsRE, function (match, key) {
+      const colonNdx = key.indexOf(':');
+      if (colonNdx >= 0) {
+        /*
+        try {
+          const args = hanson.parse("{" + key + "}");
+          const handlerName = Object.keys(args)[0];
+          const handler = replaceHandlers[handlerName];
+          if (handler) {
+            return handler(args[handlerName]);
+          }
+          console.error("unknown substitution handler: " + handlerName);
+        } catch (e) {
+          console.error(e);
+          console.error("bad substitution: %(" + key + ")s");
+        }
+        */
+        throw new Error('unsupported');
+      } else {
+        // handle normal substitutions.
+        const keys = key.split('.');
+        for (let ii = 0; ii < params.length; ++ii) {
+          let obj = params[ii];
+          for (let jj = 0; jj < keys.length; ++jj) {
+            const key = keys[jj];
+            obj = obj[key];
+            if (obj === undefined) {
+              break;
+            }
+          }
+          if (obj !== undefined) {
+            return obj;
+          }
+        }
+      }
+      console.error('unknown key: ' + key);
+      return '%(' + key + ')s';
+    });
+  };
+}());
+
+const html = md.render(fs.readFileSync('README.md', {encoding: 'utf8'}));
+const template = fs.readFileSync('build/templates/index.template', {encoding: 'utf8'});
+let content = replaceParams(template, {
+  content: html,
+  license: getLicense(pkg),
+  srcFileName: 'README.md',
+  title: 'webgpu-utils, a WebGPU helper library',
+  version: pkg.version,
+});
+content = content.replace(/href="https:\/\/greggman\.github\.io\/webgpu-utils\//g, 'href="./');
+fs.writeFileSync('index.html', content);
+
+

build/tools/prep-for-deploy.js

@@ -0,0 +1,9 @@
+import fs from 'fs';
+import path from 'path';
+import * as url from 'url';
+const dirname = url.fileURLToPath(new URL('.', import.meta.url));
+
+const ignoreFilename = path.join(dirname, '..', '..', '.gitignore');
+const ignore = fs.readFileSync(ignoreFilename, {encoding: 'utf8'});
+const newIgnore = ignore.replace(/# -- clip-for-deploy-start --[\s\S]*?# -- clip-for-deploy-end --/, '');
+fs.writeFileSync(ignoreFilename, newIgnore);