[web] add doc for importing and webgpu config/flags (#311)

* [web] add doc for importing

* [web] add webgpu config/flags

Author: fs-eire

js/README.md

@@ -22,6 +22,14 @@ Click links for README of each examples.
 
 * [Quick Start - Web (using bundler)](quick-start_onnxruntime-web-bundler) - a demonstration of basic usage of ONNX Runtime Web using a bundler.
 
+### Importing
+
+* [Importing - Nodejs Binding](importing_onnxruntime-node) - a demonstration of how to import ONNX Runtime Node.js binding.
+
+* [Importing - Web](importing_onnxruntime-web) - a demonstration of how to import ONNX Runtime Web.
+
+* [Importing - React Native](importing_onnxruntime-react-native) - a demonstration of how to import ONNX Runtime React Native.
+
 ### API usage
 
 * [API usage - Tensor](api-usage_tensor) - a demonstration of basic usage of `Tensor`.

js/api-usage_ort-env-flags/README.md

@@ -62,6 +62,21 @@ ort.env.webgl.pack = true;
 
 See also [WebGL flags](https://onnxruntime.ai/docs/api/js/interfaces/Env.WebGLFlags.html) in API reference document.
 
+### WebGPU flags (ONNX Runtime Web)
+WebGPU flags are used to customize behaviors of WebGPU execution provider.
+
+Following are some example code snippets:
+
+```js
+// enable WebGPU profiling.
+ort.env.webgpu.profilingMode = 'default';
+
+// get the gpu device object.
+const device = ort.env.webgpu.device;
+```
+
+See also [WebGPU flags](https://onnxruntime.ai/docs/api/js/interfaces/Env.WebGpuFlags.html) in API reference document.
+
 ### SessionOptions vs. ort.env
 
 Both `SessionOptions` and `ort.env` allow to specify configurations for inferencing behaviors. The biggest difference of them is: `SessionOptions` is set for one inference session instance, while `ort.env` is set global.

js/api-usage_session-options/README.md

@@ -21,6 +21,7 @@ An [execution provider](https://onnxruntime.ai/docs/reference/execution-provider
 | `dml`   | GPU (Direct ML)   | onnxruntime-node (Windows)        |
 | `wasm`  | CPU (WebAssembly) | onnxruntime-web, onnxruntime-node |
 | `webgl` | GPU (WebGL)       | onnxruntime-web                   |
+| `webgpu`| GPU (WebGPU)      | onnxruntime-web                   |
 
 Execution provider is specified by `sessionOptions.executionProviders`. Multiple EPs can be specified and the first available one will be used.
 
@@ -64,6 +65,17 @@ const sessionOption = { executionProviders: ['wasm'] };
 const sessionOption = { executionProviders: ['webgl'] };
 ```
 
+```js
+// [ONNX Runtime Web example] Use WebGPU EP.
+const sessionOption = { executionProviders: ['webgpu'] };
+
+// [ONNX Runtime Web example] Use WebGPU EP with extra config.
+const sessionOption2 = { executionProviders: [{
+  name: 'webgpu',
+  preferredLayout: 'NCHW'
+}] }
+```
+
 ### other common options
 
 There are also some other options available for all EPs.

js/importing_onnxruntime-node/README.md

@@ -0,0 +1,14 @@
+# Importing ONNX Runtime Node.js binding
+
+## Summary
+
+This example is a demonstration of how to import ONNX Runtime Node.js binding in your project.
+
+## Usage
+
+Please use the following code snippet to import ONNX Runtime Node.js binding:
+
+```js
+// Common.js import syntax
+const ort = require('onnxruntime-node');
+```

js/importing_onnxruntime-react-native/README.md

@@ -0,0 +1,19 @@
+# Importing ONNX Runtime React Native
+
+## Summary
+
+This example is a demonstration of how to import ONNX Runtime React Native in your project.
+
+## Usage
+
+Please use the following code snippet to import ONNX Runtime React Native:
+
+```js
+// Common.js import syntax
+const ort = require('onnxruntime-react-native');
+```
+
+```js
+// ES Module import syntax
+import * as ort from 'onnxruntime-react-native';
+```

js/importing_onnxruntime-web/README.md

@@ -0,0 +1,83 @@
+# Importing ONNX Runtime Web
+
+## Summary
+
+This example is a demonstration of how to import ONNX Runtime Web in your project.
+
+ONNX Runtime Web can be consumed by either using a script tag in HTML or using a modern web app framework with bundler.
+
+## Usage - Using Script tag in HTML
+
+Please use the following HTML snippet to import ONNX Runtime Web:
+
+```html
+<!-- import ONNXRuntime Web from CDN (IIFE) -->
+<script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort.min.js"></script>
+```
+
+```html
+<!-- import ONNXRuntime Web from CDN (ESM) -->
+<script type="module">
+    import * as ort from "https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/esm/ort.min.js";
+
+    // use "ort"
+    // ...
+</script>
+```
+
+See also [Quick Start - Web (using script tag)](../quick-start_onnxruntime-web-script-tag) for an example of using script tag.
+
+## Usage - Using a bundler
+
+Please use the following code snippet to import ONNX Runtime Web:
+
+```js
+// Common.js import syntax
+const ort = require('onnxruntime-web');
+```
+
+```js
+// ES Module import syntax
+import * as ort from 'onnxruntime-web';
+```
+
+See also [Quick Start - Web (using bundler)](../quick-start_onnxruntime-web-bundler) for an example of using bundler.
+
+### Conditional Importing
+
+ONNX Runtime Web supports conditional importing. Please refer to the following table:
+
+| Description | IIFE Filename | Common.js / ES Module import path |
+|--------------|-----------|------------|
+| Default import. Includes all official released features | ort.min.js | `onnxruntime-web` |
+| Experimental. Includes all features | ort.all.min.js | `onnxruntime-web/experimental` |
+| Wasm. Includes WebAssembly backend only | ort.wasm.min.js | `onnxruntime-web/wasm` |
+| Wasm-core. Includes WebAssembly backend with core features only. Proxy support and Multi-thread support are excluded | ort.wasm-core.min.js | `onnxruntime-web/wasm-core` |
+| Webgl. Includes WebGL backend only | ort.webgl.min.js | `onnxruntime-web/webgl` |
+| Webgpu. Includes WebGPU backend only | ort.webgpu.min.js | `onnxruntime-web/webgpu` |
+| Training. Includes WebAssembly single-threaded only, with training support | ort.training.wasm.min.js | `onnxruntime-web/training` |
+
+Use the following syntax to import different target:
+* for script tag usage, replace the URL's file name from the table ("IIFE Filename" column) above:
+  ```html
+  <script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/<file-name>"></script>
+  ```
+  ```html
+  <script type="module">
+    import * as ort from "https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/esm/<file-name>";
+
+    // use "ort"
+    // ...
+  </script>
+  ```
+
+* for Common.js module usage, use
+  ```js
+  const ort = require('<path>');
+  ```
+  with the path from the table ("Common.js / ES Module import path" column) above
+* for ES Module usage, use
+  ```js
+  import * as ort from '<path>';
+  ```
+  with the path from the table ("Common.js / ES Module import path" column) above

js/quick-start_onnxruntime-web-bundler/main.js

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+// see also advanced usage of importing ONNX Runtime Web:
+// https://github.com/microsoft/onnxruntime-inference-examples/tree/main/js/importing_onnxruntime-web
 const ort = require('onnxruntime-web');
 
 // use an async context to call onnxruntime functions.

js/quick-start_onnxruntime-web-script-tag/index.html

@@ -4,6 +4,9 @@
         <title>ONNX Runtime JavaScript examples: Quick Start - Web (using script tag)</title>
     </header>
     <body>
+        <!-- see also advanced usage of importing ONNX Runtime Web: -->
+        <!-- https://github.com/microsoft/onnxruntime-inference-examples/tree/main/js/importing_onnxruntime-web -->
+
         <!-- import ONNXRuntime Web from CDN -->
         <script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort.min.js"></script>
         <script>

js/quick-start_onnxruntime-web-script-tag/index_esm.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html>
+    <header>
+        <title>ONNX Runtime JavaScript examples: Quick Start - Web (using script tag)</title>
+    </header>
+    <body>
+        <script type="module">
+            // see also advanced usage of importing ONNX Runtime Web:
+            // https://github.com/microsoft/onnxruntime-inference-examples/tree/main/js/importing_onnxruntime-web
+
+            // import ONNXRuntime Web from CDN
+            import * as ort from "https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/esm/ort.min.js";
+            // set wasm path override
+            ort.env.wasm.wasmPaths = "https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/";
+
+            // use an async context to call onnxruntime functions.
+            async function main() {
+                try {
+                    // create a new session and load the specific model.
+                    //
+                    // the model in this example contains a single MatMul node
+                    // it has 2 inputs: 'a'(float32, 3x4) and 'b'(float32, 4x3)
+                    // it has 1 output: 'c'(float32, 3x3)
+                    const session = await ort.InferenceSession.create('./model.onnx');
+
+                    // prepare inputs. a tensor need its corresponding TypedArray as data
+                    const dataA = Float32Array.from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);
+                    const dataB = Float32Array.from([10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120]);
+                    const tensorA = new ort.Tensor('float32', dataA, [3, 4]);
+                    const tensorB = new ort.Tensor('float32', dataB, [4, 3]);
+
+                    // prepare feeds. use model input names as keys.
+                    const feeds = { a: tensorA, b: tensorB };
+
+                    // feed inputs and run
+                    const results = await session.run(feeds);
+
+                    // read from results
+                    const dataC = results.c.data;
+                    document.write(`data of result tensor 'c': ${dataC}`);
+
+                } catch (e) {
+                    document.write(`failed to inference ONNX model: ${e}.`);
+                }
+            }
+
+            main();
+        </script>
+    </body>
+</html>