GPUAdapter: requestDevice() method

descriptor Optional

An object containing the following properties:

defaultQueue Optional

An object that provides information for the device's default GPUQueue (as returned by GPUDevice.queue). This object has a single property — label — which provides the default queue with a label value. If no value is provided, this defaults to an empty object, and the default queue's label will be an empty string.

label Optional

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

requiredFeatures Optional

An array of strings representing additional functionality that you want supported by the returned GPUDevice. The requestDevice() call will fail if the GPUAdapter cannot provide these features. See GPUSupportedFeatures for a full list of possible features. This defaults to an empty array if no value is provided.

requiredLimits Optional

An object containing properties representing the limits that you want supported by the returned GPUDevice. The requestDevice() call will fail if the GPUAdapter cannot provide these limits. Each key must be the name of a member of GPUSupportedLimits. This defaults to an empty object if no value is provided.

A Promise that fulfills with a GPUDevice object instance.

If you make a duplicate call, i.e. call requestDevice() on a GPUAdapter that requestDevice() was already called on, the promise fulfills with a device that is immediately lost. You can then get information on how the device was lost via GPUDevice.lost.

OperationError DOMException

The promise rejects with an OperationError if the limits included in the requiredLimits property are not supported by the GPUAdapter, either because they are not valid limits, or because their values are higher than the adapter's values for those limits.

TypeError DOMException

The promise rejects with a TypeError if the features included in the requiredFeatures property are not supported by the GPUAdapter.

In the following code we:

1. Check whether a GPUAdapter has the texture-compression-astc feature available. If so, we push it into the array of requiredFeatures.
2. Query the GPUAdapter.limits value of maxBindGroups to see if it is equal to or greater than 6. Our theoretical example app ideally needs 6 bind groups, so if the returned value is >= 6, we add a maximum limit of 6 to the requiredLimits object.
3. Request a device with those feature and limit requirements, plus a defaultQueue label.

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.");
  }

  const requiredFeatures = [];

  if (adapter.features.has("texture-compression-astc")) {
    requiredFeatures.push("texture-compression-astc");
  }

  const requiredLimits = {};

  // App ideally needs 6 bind groups, so we'll try to request what the app needs
  if (adapter.limits.maxBindGroups >= 6) {
    requiredLimits.maxBindGroups = 6;
  }

  const device = await adapter.requestDevice({
    defaultQueue: {
      label: "my_queue",
    },
    requiredFeatures,
    requiredLimits,
  });

  // ...
}

• The WebGPU API