WebGPU PR #2 — Interfaces for representing pipeline resources (mdn#25140

) * Add GPUBuffer reference pages * update folder names * update folder names * Add GPUTexture reference pages * Add GPUTextureView reference pages * Add GPUSampler reference pages * Add GPUExternalTexture reference pages * Adding GPUShaderModule reference pages * Fixes for toji and dawei-wang comments * Update bitwise flags information, including adding glossary entry * Remove curly quote * Couple of updates to the Bitwise flags Glossary entry * Fixing typos, improving language * Update basic MDN demo links to use the dom-examples versions * fixing a couple of small errors
wbamberg · Apr 5, 2023 · 3996d67 · 3996d67
1 parent 840132f
commit 3996d67
Show file tree

Hide file tree

Showing 31 changed files with 2,009 additions and 0 deletions.
diff --git a/files/en-us/glossary/bitwise_flags/index.md b/files/en-us/glossary/bitwise_flags/index.md
@@ -0,0 +1,47 @@
+---
+title: "Bitwise flags"
+slug: Glossary/Bitwise_flags
+page-type: glossary-definition
+---
+
+**Bitwise flags** are sets of variables, usually simple number values, which can be used to enable or disable specific usages or features of a method or other code structure. They can do this quickly and efficiently because they operate at the bit level. Related flags in the same group are generally given complementary values representing different bit positions in a single value (e.g. hexadecimal), so that multiple flag settings can be represented by a single value.
+
+For example, in the {{domxref("WebGPU API", "WebGPU API", "", "nocode")}}, a {{domxref("GPUBuffer")}} object instance is created using the {{domxref("GPUDevice.createBuffer()")}} method. When invoking this method, you define a `usage` property in the descriptor containing one or more flags that enable different allowed usages of that buffer.
+
+```js
+usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE;
+```
+
+These values are defined inside the same namespace, and each one has a hexadecimal value:
+
+| Usage flag                     | Hexadecimal representation | Decimal equivalent |
+| ------------------------------ | -------------------------- | ------------------ |
+| `GPUBufferUsage.MAP_READ`      | 0x0001                     | 1                  |
+| `GPUBufferUsage.MAP_WRITE`     | 0x0002                     | 2                  |
+| `GPUBufferUsage.COPY_SRC`      | 0x0004                     | 4                  |
+| `GPUBufferUsage.COPY_DST`      | 0x0008                     | 8                  |
+| `GPUBufferUsage.INDEX`         | 0x0010                     | 16                 |
+| `GPUBufferUsage.VERTEX`        | 0x0020                     | 32                 |
+| `GPUBufferUsage.UNIFORM`       | 0x0040                     | 64                 |
+| `GPUBufferUsage.STORAGE`       | 0x0080                     | 128                |
+| `GPUBufferUsage.INDIRECT`      | 0x0100                     | 256                |
+| `GPUBufferUsage.QUERY_RESOLVE` | 0x0200                     | 512                |
+
+When you query the {{domxref("GPUBuffer.usage")}} property, you get a single decimal number returned, which is the sum of the different decimal values for the different usage flags. Returning to the above example, querying `GPUBuffer.usage` for the `GPUBuffer` created with the usage specified earlier would return the following:
+
+- `GPUBufferUsage.COPY_SRC`'s decimal equivalent, 4
+- Add `GPUBufferUsage.MAP_WRITE`'s decimal equivalent, 2
+- Equals 6.
+
+Because of the values chosen for the different flags, each combination of values is unique, so the program can tell at a glance which flags are set from a single value. In addition, you can easily test which flags are set in the combined value using the bitwise and operator:
+
+```js
+if (buffer.usage & GPUBufferUsage.MAP_WRITE) {
+  // Buffer has MAP_WRITE usage
+}
+```
+
+## See also
+
+- [Bitwise Flags are Beautiful, and Here's Why](https://www.hendrik-erz.de/post/bitwise-flags-are-beautiful-and-heres-why)
+- [Bitwise operation](https://en.wikipedia.org/wiki/Bitwise_operation) on Wikipedia
diff --git a/files/en-us/web/api/gpubuffer/destroy/index.md b/files/en-us/web/api/gpubuffer/destroy/index.md
@@ -0,0 +1,52 @@
+---
+title: GPUBuffer.destroy()
+slug: Web/API/GPUBuffer/destroy
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.GPUBuffer.destroy
+---
+
+{{APIRef("WebGPU API")}}{{SeeCompatTable}}
+
+The **`destroy()`** method of the
+{{domxref("GPUBuffer")}} interface destroys the `GPUBuffer`.
+
+## Syntax
+
+```js-nolint
+destroy()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+None ({{jsxref("Undefined")}}).
+
+## Examples
+
+```js
+const output = device.createBuffer({
+  size: 1000,
+  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+});
+
+// some time later
+
+output.destroy();
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API)
diff --git a/files/en-us/web/api/gpubuffer/getmappedrange/index.md b/files/en-us/web/api/gpubuffer/getmappedrange/index.md
@@ -0,0 +1,65 @@
+---
+title: GPUBuffer.getMappedRange()
+slug: Web/API/GPUBuffer/getMappedRange
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.GPUBuffer.getMappedRange
+---
+
+{{APIRef("WebGPU API")}}{{SeeCompatTable}}
+
+The **`getMappedRange()`** method of the
+{{domxref("GPUBuffer")}} interface returns an {{jsxref("ArrayBuffer")}} containing the mapped contents of the `GPUBuffer` in the specified range.
+
+This can only happen once the `GPUBuffer` has been successfully mapped with {{domxref("GPUBuffer.mapAsync()")}} (this can be checked via {{domxref("GPUBuffer.mapState")}}). While the `GPUBuffer` is mapped it cannot be used in any GPU commands.
+
+When you have finished working with the `GPUBuffer` values, call {{domxref("GPUBuffer.unmap()")}} to unmap it, making it accessible to the GPU again.
+
+## Syntax
+
+```js-nolint
+getMappedRange()
+getMappedRange(offset)
+getMappedRange(offset, size)
+```
+
+### Parameters
+
+- `offset` {{optional_inline}}
+  - : A number representing the offset, in bytes, from the start of the `GPUBuffer`'s mapped range to the start of the range to be returned in the {{jsxref("ArrayBuffer")}}. If `offset` is omitted, it defaults to 0.
+- `size` {{optional_inline}}
+  - : A number representing the size, in bytes, of the {{jsxref("ArrayBuffer")}} to return. If `size` is omitted, the range extends to the end of the `GPUBuffer`'s mapped range.
+
+### Return value
+
+An {{jsxref("ArrayBuffer")}}.
+
+### Validation
+
+The following criteria must be met when calling **`getMappedRange()`**, otherwise an `OperationError` {{domxref("DOMException")}} is thrown:
+
+- `offset` is a multiple of 8.
+- The total range to be mapped (`size` if specified, or mapped range length - `offset` if not) is a multiple of 4.
+- The total range is inside the bounds of the mapped range and does not overlap with the {{jsxref("ArrayBuffer")}} ranges specified by any other active `getMappedRange()` calls.
+
+### Exceptions
+
+- `TypeError` {{domxref("DOMException")}}
+  - : Thrown if an attempt is made to detach the {{jsxref("ArrayBuffer")}} in any way other than via {{domxref("GPUBuffer.unmap()")}}.
+
+## Examples
+
+See the [main `GPUBuffer` page](/en-US/docs/Web/API/GPUBuffer#examples) for an example.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API)
diff --git a/files/en-us/web/api/gpubuffer/index.md b/files/en-us/web/api/gpubuffer/index.md
@@ -0,0 +1,87 @@
+---
+title: GPUBuffer
+slug: Web/API/GPUBuffer
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.GPUBuffer
+---
+
+{{APIRef("WebGPU API")}}{{SeeCompatTable}}
+
+The **`GPUBuffer`** interface of the {{domxref("WebGPU API", "WebGPU API", "", "nocode")}} represents a block of memory that can be used to store raw data to use in GPU operations.
+
+A `GPUBuffer` object instance is created using the {{domxref("GPUDevice.createBuffer()")}} method.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+- {{domxref("GPUBuffer.label", "label")}} {{Experimental_Inline}}
+  - : A string providing a label that can be used to identify the object, for example in
+    {{domxref("GPUError")}} messages or console warnings.
+- {{domxref("GPUBuffer.mapState", "mapState")}} {{Experimental_Inline}} {{readonlyinline}}
+  - : An enumerated value representing the mapped state of the `GPUBuffer`.
+- {{domxref("GPUBuffer.size", "size")}} {{Experimental_Inline}} {{readonlyinline}}
+  - : A number representing the length of the `GPUBuffer`'s memory allocation, in bytes.
+- {{domxref("GPUBuffer.usage", "usage")}} {{Experimental_Inline}} {{readonlyinline}}
+  - : The {{glossary("bitwise flags")}} representing the allowed usages of the `GPUBuffer`.
+
+## Instance methods
+
+- {{domxref("GPUBuffer.destroy", "destroy()")}} {{Experimental_Inline}}
+  - : Destroys the `GPUBuffer`.
+- {{domxref("GPUBuffer.getMappedRange", "getMappedRange()")}} {{Experimental_Inline}}
+  - : Returns an {{jsxref("ArrayBuffer")}} containing the mapped contents of the `GPUBuffer` in the specified range.
+- {{domxref("GPUBuffer.mapAsync", "mapAsync()")}} {{Experimental_Inline}}
+  - : Maps the specified range of the `GPUBuffer`. Returns a {{jsxref("Promise")}} that resolves when the `GPUBuffer`'s content is ready to be accessed with {{domxref("GPUBuffer.getMappedRange()")}}.
+- {{domxref("GPUBuffer.unmap", "unmap()")}} {{Experimental_Inline}}
+  - : Unmaps the mapped range of the `GPUBuffer`, making its contents available for use by the GPU again.
+
+## Examples
+
+In our [basic compute demo](https://mdn.github.io/dom-examples/webgpu-compute-demo/), we create an output buffer to read GPU calculations to, and a staging buffer to be mapped for JavaScript access.
+
+```js
+const output = device.createBuffer({
+  size: BUFFER_SIZE,
+  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+});
+
+const stagingBuffer = device.createBuffer({
+  size: BUFFER_SIZE,
+  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+});
+```
+
+Later on, once the `stagingBuffer` contains the results of the GPU computation, a combination of `GPUBuffer` methods are used to read the data back to JavaScript so that it can then be logged to the console:
+
+- {{domxref("GPUBuffer.mapAsync()")}} is used to map the `GPUBuffer` for reading.
+- {{domxref("GPUBuffer.getMappedRange()")}} is used to return an {{jsxref("ArrayBuffer")}} containing the `GPUBuffer`'s contents.
+- {{domxref("GPUBuffer.unmap()")}} is used to unmap the `GPUBuffer` again, once we have read the content into JavaScript as needed.
+
+```js
+// map staging buffer to read results back to JS
+await stagingBuffer.mapAsync(
+  GPUMapMode.READ,
+  0, // Offset
+  BUFFER_SIZE // Length
+);
+
+const copyArrayBuffer = stagingBuffer.getMappedRange(0, BUFFER_SIZE);
+const data = copyArrayBuffer.slice();
+stagingBuffer.unmap();
+console.log(new Float32Array(data));
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API)
diff --git a/files/en-us/web/api/gpubuffer/label/index.md b/files/en-us/web/api/gpubuffer/label/index.md
@@ -0,0 +1,58 @@
+---
+title: GPUBuffer.label
+slug: Web/API/GPUBuffer/label
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.GPUBuffer.label
+---
+
+{{APIRef("WebGPU API")}}{{SeeCompatTable}}
+
+The **`label`** property of the
+{{domxref("GPUBuffer")}} interface provides a label that can be used to identify the object, for example in {{domxref("GPUError")}} messages or console warnings.
+
+This can be set by providing a `label` property in the descriptor object passed into the originating {{domxref("GPUDevice.createBuffer()")}} call, or you can get and set it directly on the `GPUBuffer` object.
+
+## Value
+
+A string. If this has not been previously set as described above, it will be an empty string.
+
+## Examples
+
+Setting and getting a label via `GPUBuffer.label`:
+
+```js
+const output = device.createBuffer({
+  size: BUFFER_SIZE,
+  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+});
+
+output.label = "mybuffer";
+
+console.log(output.label); // "mybuffer"
+```
+
+Setting a label via the originating {{domxref("GPUDevice.createBuffer()")}} call, and then getting it via `GPUBuffer.label`:
+
+```js
+const output = device.createBuffer({
+  size: BUFFER_SIZE,
+  usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+  label: "mybuffer",
+});
+
+console.log(output.label); // "mybuffer"
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API)
diff --git a/files/en-us/web/api/gpubuffer/mapasync/index.md b/files/en-us/web/api/gpubuffer/mapasync/index.md
@@ -0,0 +1,77 @@
+---
+title: GPUBuffer.mapAsync()
+slug: Web/API/GPUBuffer/mapAsync
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.GPUBuffer.mapAsync
+---
+
+{{APIRef("WebGPU API")}}{{SeeCompatTable}}
+
+The **`mapAsync()`** method of the
+{{domxref("GPUBuffer")}} interface maps the specified range of the `GPUBuffer`. It returns a {{jsxref("Promise")}} that resolves when the `GPUBuffer`'s content is ready to be accessed. While the `GPUBuffer` is mapped it cannot be used in any GPU commands.
+
+Once the buffer is successfully mapped (which can be checked via {{domxref("GPUBuffer.mapState")}}), calls to {{domxref("GPUBuffer.getMappedRange()")}} will return an {{jsxref("ArrayBuffer")}} containing the `GPUBuffer`'s current values, to be read and updated by JavaScript as required.
+
+When you have finished working with the `GPUBuffer` values, call {{domxref("GPUBuffer.unmap()")}} to unmap it, making it accessible to the GPU again.
+
+## Syntax
+
+```js-nolint
+mapAsync(mode)
+mapAsync(mode, offset, size)
+```
+
+### Parameters
+
+- `mode`
+
+  - : A {{glossary("bitwise flags", "bitwise flag")}} that specifies whether the `GPUBuffer` is mapped for reading or writing. Possible values are:
+
+    - `GPUMapMode.READ`
+
+      - : The `GPUBuffer` is mapped for reading. Values can be read, but any changes made to the {{jsxref("ArrayBuffer")}} returned by {{domxref("GPUBuffer.getMappedRange()")}} will be discarded once {{domxref("GPUBuffer.unmap()")}} is called.
+
+        Read-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_READ` set on them (i.e. when created with {{domxref("GPUDevice.createBuffer()")}}).
+
+    - `GPUMapMode.WRITE`
+
+      - : The `GPUBuffer` is mapped for writing. Values can be read and updated — any changes made to the {{jsxref("ArrayBuffer")}} returned by {{domxref("GPUBuffer.getMappedRange()")}} will be saved to the `GPUBuffer` once {{domxref("GPUBuffer.unmap()")}} is called.
+
+        Write-mode mapping can only be used on `GPUBuffer`s that have a usage of `GPUBufferUsage.MAP_WRITE` set on them (i.e. when created with {{domxref("GPUDevice.createBuffer()")}}).
+
+- `offset` {{optional_inline}}
+  - : A number representing the offset, in bytes, from the start of the buffer to the start of the range to be mapped. If `offset` is omitted, it defaults to 0.
+- `size` {{optional_inline}}
+  - : A number representing the size, in bytes, of the range to be mapped. If `size` is omitted, the range mapped extends to the end of the `GPUBuffer`.
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves to {{jsxref("Undefined")}} when the `GPUBuffer`'s content is ready to be accessed.
+
+### Validation
+
+The following criteria must be met when calling **`mapSync()`**, otherwise an `OperationError` {{domxref("DOMException")}} is thrown, the promise is rejected, and a {{domxref("GPUValidationError")}} is generated:
+
+- `offset` is a multiple of 8.
+- The total range to be mapped (`size` if specified, or {{domxref("GPUBuffer.size")}} - `offset` if not) is a multiple of 4.
+- The total range to be mapped is inside the bounds of the `GPUBuffer`.
+- If mode is `GPUMapMode.READ`, the `GPUBuffer` has a usage of `GPUBufferUsage.MAP_READ`.
+- If mode is `GPUMapMode.WRITE`, the `GPUBuffer` has a usage of `GPUBufferUsage.MAP_WRITE`.
+
+## Examples
+
+See the [main `GPUBuffer` page](/en-US/docs/Web/API/GPUBuffer#examples) for an example.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- The [WebGPU API](/en-US/docs/Web/API/WebGPU_API)