GPUAdapter: requestDevice() 方法

语法

requestDevice()
requestDevice(descriptor)

参数

descriptor 可选

包含以下属性的对象：

defaultQueue 可选

一个对象，为设备的默认 GPUQueue（由 GPUDevice.queue 返回）提供信息。此对象有一个名为 label 的属性，为默认队列提供一个 label 值。如果未提供值，则默认为一个空对象，默认队列的标签将是一个空字符串。

label 可选

一个字符串，提供一个标签，可用于标识 GPUDevice，例如在 GPUError 消息或控制台警告中。

requiredFeatures 可选

一个字符串数组，表示您希望返回的 GPUDevice 支持的附加功能。如果 GPUAdapter 无法提供这些功能，requestDevice() 调用将失败。有关可能的功能的完整列表，请参阅 GPUSupportedFeatures。如果未提供值，则默认为一个空数组。

requiredLimits 可选

一个对象，包含表示您希望返回的 GPUDevice 支持的限制的属性。如果 GPUAdapter 无法提供这些限制，requestDevice() 调用将失败。每个具有非 undefined 值的键必须是 GPUSupportedLimits 中成员的名称。

注意：您可以在请求 GPU 设备时请求未知限制，而不会导致错误。这些限制将为 undefined。这很有用，因为它使 WebGPU 代码更加健壮——代码库不会因为某个限制在适配器中不再存在而停止工作。

并非所有浏览器都支持 WebGPU 中的所有功能和限制，即使底层硬件支持它们。有关更多信息，请参阅 features 和 limits 页面。

返回值

一个 Promise，它解析（fulfills）为一个 GPUDevice 对象实例。

如果您进行了重复调用，即在已经调用过 requestDevice() 的 GPUAdapter 上再次调用 requestDevice()，则该 Promise 将会解析（fulfill）为一个立即丢失的设备。然后，您可以通过 GPUDevice.lost 获取有关设备丢失的信息。

异常

OperationError DOMException

如果 requiredLimits 属性中包含的限制未被 GPUAdapter 支持（因为它们不是有效限制，或者它们的值高于适配器中这些限制的值），则该 Promise 会以 OperationError 拒绝（reject）。

TypeError DOMException

如果 requiredFeatures 属性中包含的特征未被 GPUAdapter 支持，则该 Promise 会以 TypeError 拒绝（reject）。

示例

基本示例

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();

  // …
}

请求特定的功能和限制

在下面的代码中，我们

1. 检查 GPUAdapter 是否具有 texture-compression-astc 功能。如果具有，我们将其添加到 requiredFeatures 数组中。
2. 查询 GPUAdapter.limits 值 maxBindGroups，以查看它是否等于或大于 6。我们的理论示例应用程序理想情况下需要 6 个绑定组，因此如果返回的值大于等于 6，我们将最大限制 6 添加到 requiredLimits 对象中。
3. 使用这些功能和限制要求以及 defaultQueue 标签来请求设备。

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,
  });

  // …
}

规范

浏览器兼容性

另见

• WebGPU API