W3cubDocs

/Web APIs

GPU: requestAdapter() method

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

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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
requestAdapter
113Currently supported on ChromeOS, macOS, and Windows only.
113Currently supported on ChromeOS, macOS, and Windows only.
previewCurrently supported on Linux and Windows only.
No
99Currently supported on ChromeOS, macOS, and Windows only.
No No No No No No No
discrete_adapter_default_ac
115Currently supported on dual GPU macOS devices only.
115Currently supported on dual GPU macOS devices only.
No No
101Currently supported on dual GPU macOS devices only.
No No No No No No No

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/GPU/requestAdapter