GPU: requestAdapter() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Note: This feature is available in Web Workers.

The requestAdapter() method of the GPU interface returns a Promise that fulfills with a GPUAdapter object instance. From this you can request a GPUDevice, adapter info, features, and limits.

Note that the user agent chooses whether to return an adapter. If so, it chooses according to the provided options. If no options are provided, the device will provide access to the default adapter, which is usually good enough for most purposes.

Syntax

js
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.

Note: The specification includes a forceFallbackAdapter option for requestAdapter(). This is a boolean that, if set to true, forces the user agent to return a fallback adapter if one is available. This is not yet supported by any browser.

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

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

  const device = await adapter.requestDevice();

  //...
}

Specifications

Specification
WebGPU
# dom-gpu-requestadapter

Browser compatibility

BCD tables only load in the browser

See also