GPUAdapter: requestDevice() method
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 requestDevice()
method of the
GPUAdapter
interface returns a Promise
that fulfills with a GPUDevice
object, which is the primary interface for communicating with the GPU.
Syntax
requestDevice()
requestDevice(descriptor)
Parameters
descriptor
Optional-
An object containing the following properties:
defaultQueue
Optional-
An object that provides information for the device's default
GPUQueue
(as returned byGPUDevice.queue
). This object has a single property —label
— which provides the default queue with alabel
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 inGPUError
messages or console warnings. requiredFeatures
Optional-
An array of strings representing additional functionality that you want supported by the returned
GPUDevice
. TherequestDevice()
call will fail if theGPUAdapter
cannot provide these features. SeeGPUSupportedFeatures
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
. TherequestDevice()
call will fail if theGPUAdapter
cannot provide these limits. Each key must be the name of a member ofGPUSupportedLimits
. This defaults to an empty object if no value is provided.
Return value
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
.
Exceptions
OperationError
DOMException
-
The promise rejects with an
OperationError
if the limits included in therequiredLimits
property are not supported by theGPUAdapter
, 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 therequiredFeatures
property are not supported by theGPUAdapter
.
Examples
Basic example
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();
// ...
}
Requesting specific features and limits
In the following code we:
- Check whether a
GPUAdapter
has thetexture-compression-astc
feature available. If so, we push it into the array ofrequiredFeatures
. - Query the
GPUAdapter.limits
value ofmaxBindGroups
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 therequiredLimits
object. - 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: "myqueue",
},
requiredFeatures,
requiredLimits,
});
// ...
}
Specifications
Specification |
---|
WebGPU # dom-gpuadapter-requestdevice |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API