recursal/MDN huggingface dataset:
GPUDevice: pushErrorScope() method
==================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`pushErrorScope()`** method of the
 `GPUDevice` interface pushes a new GPU error scope onto the device's error scope stack, allowing you to capture errors of a particular type.

Once you are done capturing errors, you can end capture by invoking `GPUDevice.popErrorScope()`. This pops the scope from the stack and returns a `Promise` that resolves to an object describing the first error captured in the scope, or `null` if no errors were captured.

Syntax
------


```js
pushErrorScope(filter)
```

### Parameters

`filter`

An enumerated value that specifies what type of error will be caught in this particular error scope. Possible values are:

`"internal"`

The error scope will catch a `GPUInternalError`.

`"out-of-memory"`

The error scope will catch a `GPUOutOfMemoryError`.

`"validation"`

The error scope will catch a `GPUValidationError`.


### Return value

None (`Undefined`).

Examples
--------

The following example uses an error scope to capture a suspected validation error, logging it to the console.


```js
device.pushErrorScope("validation");

let sampler = device.createSampler({
  maxAnisotropy: 0, // Invalid, maxAnisotropy must be at least 1.
});

device.popErrorScope().then((error) => {
  if (error) {
    sampler = null;
    console.error(`An error occurred while creating sampler: ${error.message}`);
  }
});
```


See WebGPU Error Handling best practices for a lot more examples and information.

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-pusherrorscope |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
GPUDevice: importExternalTexture() method
=========================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`importExternalTexture()`** method of the
 `GPUDevice` interface takes an `HTMLVideoElement` or a `VideoFrame` object as an input and returns a `GPUExternalTexture` wrapper object containing a snapshot of the video that can be used as a frame in GPU rendering operations.

Syntax
------


```js
importExternalTexture(descriptor)
```

### Parameters

`descriptor`

An object containing the following properties:

`colorSpace` Optional

An enumerated value specifying the color space to use for the video frame. Possible values are `"srgb"` and `"display-p3"`. If omitted, `colorSpace` defaults to `"srgb"`.

`label` Optional

A string providing a label that can be used to identify the object, for example in `GPUError` messages or console warnings.

`source`

The `HTMLVideoElement` or `VideoFrame` source of the video snapshot.


### Return value

A `GPUExternalTexture` object instance.

Note that the moment when the `GPUExternalTexture` object expires (is destroyed) depends on what its source is:

* `GPUExternalTexture` objects with an `HTMLVideoElement` source expire as soon as they are used (for example in a bind group).
* `GPUExternalTexture` objects with an `VideoFrame` source expire only when the `VideoFrame` is closed, for example via a `VideoFrame.close()` call.
### Validation

The following criteria must be met when calling **`importExternalTexture()`**, otherwise a `GPUValidationError` is generated and an invalid `GPUExternalTexture` object is returned:

* The video snapshot is usable (e.g. the video source is loaded properly, and doesn't have a width or height of 0).
### Exceptions

`SecurityError` `DOMException`

Thrown if the video source data is cross-origin.

Examples
--------

In the WebGPU samples Video Uploading sample, an `importExternalTexture()` call is used as the value of a bind group entry `resource`, specified when creating a `GPUBindGroup` via a `GPUDevice.createBindGroup()` call:


```js
//...

const uniformBindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [
    {
      binding: 1,
      resource: sampler,
    },
    {
      binding: 2,
      resource: device.importExternalTexture({
        source: video,
      }),
    },
  ],
});

//...
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-importexternaltexture |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
GPUDevice: createBuffer() method
================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`createBuffer()`** method of the
 `GPUDevice` interface creates a `GPUBuffer` in which to store raw data to use in GPU operations.

Syntax
------


```js
createBuffer(descriptor)
```

### Parameters

`descriptor`

An object containing the following properties:

`label` Optional

A string providing a label that can be used to identify the object, for example in `GPUError` messages or console warnings.

`mappedAtCreation` Optional

A boolean. If set to `true`, the buffer will be mapped upon creation, meaning that you can set the values inside the buffer immediately by calling `GPUBuffer.getMappedRange()`. The default value is `false`.

Note that it is valid to set `mappedAtCreation: true` so you can set the buffer's initial data, even if the `GPUBufferUsage.MAP_READ` or `GPUBufferUsage.MAP_WRITE` usage flags are not set.

`size`

A number representing the size of the buffer, in bytes.

`usage`

The bitwise flags representing the allowed usages for the `GPUBuffer`. The possible values are in the `GPUBuffer.usage` value table.

Note that multiple possible usages can be specified by separating values with pipe symbols, for example:


```js
usage: GPUBufferUsage.COPY\_SRC | GPUBufferUsage.MAP\_WRITE;
```


### Return value

A `GPUBuffer` object instance.

### Validation

The following criteria must be met when calling **`createBuffer()`**, otherwise a `GPUValidationError` is generated and an invalid `GPUBuffer` object is returned:

* A valid `usage` is specified.
* `GPUBufferUsage.MAP_READ` is specified, and no additional flags are specified other than `GPUBufferUsage.COPY_DST`.
* `GPUBufferUsage.MAP_WRITE` is specified, and no additional flags are specified other than `GPUBufferUsage.COPY_SRC`.
* `mappedAtCreation: true` is specified, and the specified `size` is a multiple of 4.

**Note:** If the buffer allocation fails without any specific side-effects, a `GPUOutOfMemoryError` object is generated.

Examples
--------

In our basic 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,
});
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-createbuffer |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
GPUDevice: createPipelineLayout() method
========================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`createPipelineLayout()`** method of the
 `GPUDevice` interface creates a `GPUPipelineLayout` that defines the `GPUBindGroupLayout`s used by a pipeline. `GPUBindGroup`s used with the pipeline during command encoding must have compatible `GPUBindGroupLayout`s.

Syntax
------


```js
createPipelineLayout(descriptor)
```

### Parameters

`descriptor`

An object containing the following properties:

`bindGroupLayouts`

An array of `GPUBindGroupLayout` objects (which are in turn created via calls to `GPUDevice.createBindGroupLayout()`). Each one corresponds to a `@group` attribute in the shader code contained in the `GPUShaderModule` used in a related pipeline.

`label` Optional

A string providing a label that can be used to identify the object, for example in `GPUError` messages or console warnings.


### Return value

A `GPUPipelineLayout` object instance.

### Validation

The following criteria must be met when calling **`createPipelineLayout()`**, otherwise a `GPUValidationError` is generated and an invalid `GPUPipelineLayout` object is returned:

* The `GPUBindGroupLayout` objects in `bindGroupLayouts` are valid.
* The number of `GPUBindGroupLayout` objects in `bindGroupLayouts` is less than the `GPUDevice`'s `maxBindGroups` limit.
Examples
--------

**Note:** The WebGPU samples feature many more examples.

### Multiple bind group layouts, bind group, and pipeline layout

The following snippet:

* Creates a `GPUBindGroupLayout` that describes a binding with a buffer, a texture, and a sampler.
* Creates a `GPUPipelineLayout` based on the `GPUBindGroupLayout`.


```js
// ...

const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
      buffer: {},
    },
    {
      binding: 1,
      visibility: GPUShaderStage.FRAGMENT,
      texture: {},
    },
    {
      binding: 2,
      visibility: GPUShaderStage.FRAGMENT,
      sampler: {},
    },
  ],
});

const pipelineLayout = device.createPipelineLayout({
  bindGroupLayouts: [bindGroupLayout],
});

// ...
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-createpipelinelayout |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
GPUDevice: destroy() method
===========================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`destroy()`** method of the
 `GPUDevice` interface destroys the device, preventing further operations on it.

Note that:

* Any commands currently enqueued on the device's `GPUQueue` will be executed before the device is destroyed.
* Any WebGPU resources created using the device (buffers, textures, etc.) are also destroyed.
* Any mapped buffers created using the device will be unmapped.
Syntax
------


```js
destroy()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------


```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  let device = await adapter.requestDevice();

  // Some time later

  device.destroy();
}
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-destroy |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
GPUDevice: createCommandEncoder() method
========================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`createCommandEncoder()`** method of the
 `GPUDevice` interface creates a `GPUCommandEncoder`, used to encode commands to be issued to the GPU.

Syntax
------


```js
createCommandEncoder()
createCommandEncoder(descriptor)
```

### Parameters

`descriptor` Optional

An object containing the following properties:

`label` Optional

A string providing a label that can be used to identify the object, for example in `GPUError` messages or console warnings.


### Return value

A `GPUCommandEncoder` object instance.

Examples
--------

In our basic render demo, several commands are recorded via a `GPUCommandEncoder` created via `createCommandEncoder()`:


```js
// ...

// Create GPUCommandEncoder
const commandEncoder = device.createCommandEncoder();

// Create GPURenderPassDescriptor to tell WebGPU which texture to draw into, then initiate render pass
const renderPassDescriptor = {
  colorAttachments: [
    {
      clearValue: clearColor,
      loadOp: "clear",
      storeOp: "store",
      view: context.getCurrentTexture().createView(),
    },
  ],
};

const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

// Draw a triangle
passEncoder.setPipeline(renderPipeline);
passEncoder.setVertexBuffer(0, vertexBuffer);
passEncoder.draw(3);

// End the render pass
passEncoder.end();

// ...
```


The commands encoded by the `GPUCommandEncoder` are recoded into a `GPUCommandBuffer` using the `GPUCommandEncoder.finish()` method. The command buffer is then passed into the queue via a `submit()` call, ready to be processed by the GPU.


```js
device.queue.submit([commandEncoder.finish()]);
```


**Note:** Study the WebGPU samples to find more command encoding examples.

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpudevice-createcommandencoder |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
GPUDevice: label property
=========================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`label`** read-only property of the
 `GPUDevice` interface is a string providing a label that can be used to identify the object, for example in `GPUError` messages or console warnings.

Value
-----

A string. If no label value has previously been set, getting the label returns an empty string.

Examples
--------


```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  // Create a GPUDevice
  const device = await adapter.requestDevice();

  // Set a label
  device.label = "mylabel";

  // Get a label
  console.log(device.label);

  // ...
}
```

Specifications
--------------

| Specification |
| --- |
| WebGPU # dom-gpuobjectbase-label |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The WebGPU API
XRInputSourcesChangeEvent: session property
===========================================

 The `XRInputSourcesChangeEvent` property
 `session` specifies the
 `XRSession` to which the input source list change event applies.

Value
-----

 An `XRSession` indicating the WebXR session to which the input source list
 change applies.

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrinputsourceschangeevent-session |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRInputSourcesChangeEvent: added property
=========================================

 The read-only `XRInputSourcesChangeEvent`
 property `added` is a list of zero or
 more input sources, each identified using an `XRInputSource` object,
 which have been newly made available for use.

Value
-----

 An `Array` of zero or more `XRInputSource` objects, each
 representing one input device added to the XR system.

Examples
--------

 The example below creates a handler for the
 `inputsourceschange` event that
 processes the lists of added and removed from the WebXR system. It looks for new and
 removed devices whose `targetRayMode` is
 `tracked-pointer`.


```js
xrSession.oninputsourcescchange = (event) => {
  for (const input of event.added) {
    if (input.targetRayMode === "tracked-pointer") {
      addedPointerDevice(input);
    }
  }
  for (const input of event.removed) {
    if (input.targetRayMode === "tracked-pointer") {
      removedPointerDevice(input);
    }
  }
};
```

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrinputsourceschangeevent-added |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRInputSourcesChangeEvent: removed property
===========================================

 The read-only `XRInputSourcesChangeEvent` property `removed` is an array of
 zero or more `XRInputSource` objects representing the input sources that have been removed from the `XRSession`.

Value
-----

An `Array` of zero or more `XRInputSource` objects, each representing one input device removed from the XR system.

Examples
--------

See `XRInputSourcesChangeEvent.added` for example code.

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrinputsourceschangeevent-removed |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRInputSourcesChangeEvent: XRInputSourcesChangeEvent() constructor
==================================================================

 The **`XRInputSourcesChangeEvent()`**
 constructor creates and returns a new `XRInputSourcesChangeEvent` object,
 representing an update to the list of available WebXR input devices. You
 won't typically call this constructor yourself, as these events are created and sent to
 you by the WebXR system.

Syntax
------


```js
new XRInputSourcesChangeEvent(type, options)
```

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers always set it to `inputsourceschange`.


`options`

An object that, *in addition of the properties defined in `Event()`*, can have the following properties:

`added`

An array of zero or more `XRInputSource` objects, each representing one input device which is newly available to use.

`removed`

An array of zero or more `XRInputSource` objects representing the input devices which are no longer available.

`session`

The `XRSession` to which the event applies.


### Return value

 A new `XRInputSourcesChangeEvent` object configured based upon
 the input parameters provided.

Examples
--------

 The following snippet of code creates a new `XRInputSourcesChangeEvent`
 object indicating that a single new input source, described by an
 `XRInputSource` object named `newInputSource`, has been added to
 the system.


```js
let iscEvent = new XRInputSourcesChangeEvent("inputsourceschange", {
  session: xrSession,
  added: [newInputSource],
  removed: [],
});
```

Specifications
--------------

| Specification |
| --- |
| WebXR Device API # dom-xrinputsourceschangeevent-xrinputsourceschangeevent |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceCandidateStats: candidateType property
============================================

 The `RTCIceCandidateStats` interface's
 **`candidateType`** property is a string that indicates the
 type of ICE candidate the object represents.

Syntax
------


```js
rtcIceCandidateStats.candidateType
```

### Value

A string whose value is one of the strings found in `RTCIceCandidate.type`.

Specifications
--------------

| Specification |
| --- |
| Identifiers for WebRTC's Statistics API # dom-rtcicecandidatestats-candidatetype |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceCandidateStats: address property
======================================

 The **`address`** property of the
 `RTCIceCandidateStats` dictionary indicates the address of the
 ICE candidate. While it's preferred that the address be specified as
 an IPv4 or IPv6 numeric address, a fully-qualified domain name can be used as
 well.

 When a domain name is specified, the first IP address selected for that
 address is used, even if the domain name maps to multiple IP addresses.

Value
-----

 Either an IPv4 or IPv6 address or a fully-qualified domain name, which corresponds to
 the candidate.

* If the value of `address` is comprised entirely of digits from 0-9 with
 periods as separators, the value is interpreted as an IPv4 address.
* If the value is entirely comprised of hexadecimal digits and colon (":")
 characters, it is interpreted as an IPv6 address.
* Otherwise, the `address` is presumed to be a fully-qualified domain name,
 which is resolved first using an AAAA record (assuming IPv6 is available), then using
 an A record (if no result is found or the device only supports IPv4). If multiple IP
 addresses are returned in response to the query, the user agent
 selects one, which is then used for the duration of ICE processing.
Usage notes
-----------

 The `address` property was previously known as `ip`, and only
 permitted IPv4 and IPv6 addresses to be used. The addition of support for
 fully-qualified domain names to be used for the address brought about the renaming of
 the property.

Specifications
--------------

| Specification |
| --- |
| Identifiers for WebRTC's Statistics API # dom-rtcicecandidatestats-address |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCIceCandidateStats: deleted property
======================================

 The `RTCIceCandidateStats` dictionary's
 **`deleted`** property indicates whether or not the candidate
 has been deleted or released.

Value
-----

 A Boolean value indicating whether or not the candidate has been deleted or released.
 If this value is `true`, the candidate described by the
 `RTCIceCandidateStats` object is no longer under consideration. The exact
 meaning varies depending on the type of candidate:

`Local candidate`

 A value of `true` means the candidate has been deleted as described by
 RFC 5245, section 8.3.


`Host candidate`

 A value of `true` indicates that the candidate's network resources have
 been released. This generally mean that any associated socket(s) have been closed and
 released.


`Remote (TURN) candidate`

 A value of `true` means the candidate's TURN allocation
 is no longer active.



 The net result is the same; the candidate is no longer under consideration if this
 value is `true`.

Examples
--------

 In this example, `setInterval()`
 is used to set up a function that runs periodically to display the latest statistics for
 candidates. Only candidates which have not been deleted are included in the output.


```js
setInterval(() => {
  myPeerConnection.getStats(null).then((stats) => {
    let statsOutput = "";

    stats.forEach((report) => {
      if (
        (stats.type === "local-candidate" ||
          stats.type === "remote.candidate") &&
        !stats.deleted
      ) {
        statsOutput +=
          `<h2>Report: ${report.type}</h3>\n<strong>ID:</strong> ${report.id}<br>\n` +
          `<strong>Timestamp:</strong> ${report.timestamp}<br>\n`;

        // Now the statistics for this report; we intentionally drop the ones we
        // sorted to the top above
        Object.keys(report).forEach((statName) => {
          if (
            statName !== "id" &&
            statName !== "timestamp" &&
            statName !== "type"
          ) {
            statsOutput += `<strong>${statName}:</strong> ${report[statName]}<br>\n`;
          }
        });
      }
    });

    document.querySelector(".stats-box").innerHTML = statsOutput;
  });
}, 1000);
```

Specifications
--------------

#### No specification found

No specification data found for `api.RTCIceCandidateStats.deleted`.  
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.