GPU: requestAdapter() method

Syntax

requestAdapter()
requestAdapter(options)

Parameters

options Optional

An object containing the following properties:

powerPreference Optional

An enumerated value that can be used to provide a hint to the user agent indicating what class of adapter should be chosen from the system's available adapters. Available values are:

• undefined (or not specified), which provides no hint.
• "low-power", which provides a hint to prioritize power savings over performance. If your app runs OK with this setting, it is recommended to use it, as it can significantly improve battery life on portable devices. This is usually the default if no options are provided.
• "high-performance", which provides a hint to prioritize performance over power consumption. You are encouraged to only specify this value if absolutely necessary, since it may significantly decrease battery life on portable devices. It may also result in increased GPUDevice loss — the system will sometimes elect to switch to a lower-power adapter to save power.

This hint's primary purpose is to influence which GPU is used in a multi-GPU system. For instance, some laptops have a low-power integrated GPU and a high-performance discrete GPU. Different factors may affect which adapter is returned including battery status, attached displays, or removable GPUs.

Note: On Chrome running on dual-GPU macOS devices, if requestAdapter() is called without a powerPreference option, the high-performance discrete GPU is returned when the user's device is on AC power. Otherwise, the low-power integrated GPU is returned.

Fallback adapters

The adapter provided by the user agent may be a fallback adapter, if it determines it to be the most appropriate option available. A fallback adapter generally has significant performance caveats in exchange for some combination of wider compatibility, more predictable behavior, or improved privacy. For example, some browsers may offer a software-based implementation of the API via a fallback adapter. A fallback adapter will not be available on every system.

If you wish to prevent your apps from running on fallback adapters, you should check the GPUAdapter.isFallbackAdapter attribute prior to requesting a GPUDevice.

Return value

A Promise that fulfills with a GPUAdapter object instance if the request is successful.

requestAdapter() will resolve to null if an appropriate adapter is not available.

Exceptions

None.

Examples

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 device = await adapter.requestDevice();

  // …
}

Specifications

Browser compatibility

See also

• The WebGPU API