GPUAdapter: requestDevice() メソッド

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

GPUAdapter インターフェイスの requestDevice() メソッドは、GPU とのやりとり用の第一インターフェイスである GPUDevice オブジェクトで解決する Promise を返します。

構文

js
requestDevice()
requestDevice(descriptor)

引数

descriptor 省略可

以下のプロパティを持つオブジェクトです。

defaultQueue 省略可

デバイスのデフォルトの (GPUDevice.queue が返す) GPUQueue の情報を提供するオブジェクトです。このオブジェクトは 1 個のプロパティ label を持ち、label の値を指定したデフォルトキューを提供します。値が指定されない場合のデフォルト値は空のオブジェクトであり、デフォルトキューのラベルは空文字列になります。

label 省略可

GPUDevice の特定に用いることができるラベルを表す文字列です。たとえば、コンソールでの警告や GPUError のメッセージで使用できます。

requiredFeatures 省略可

返される GPUDevice が対応することを要求する追加機能を表す文字列の配列です。GPUAdapter がこれらの機能を提供できない場合は、requestDevice() の呼び出しは失敗します。とりうる機能の完全なリストは、GPUSupportedFeatures を参照してください。値が指定されない場合のデフォルトは空の配列です。

requiredLimits 省略可

返される GPUDevice が対応することを要求する制限を表すプロパティが格納されたオブジェクトです。GPUAdapter がこれらの制限を提供できない場合は、requestDevice() の呼び出しは失敗します。それぞれのキーは GPUSupportedLimits のメンバーである名前でなければなりません。値が指定されない場合のデフォルトは空のオブジェクトです。

メモ: 下層のハードウェアが対応している場合でも、すべての機能と制限が対応しているすべてのブラウザーの WebGPU で利用可能なわけではありません。詳しくは、features および limits のページを参照してください。

返値

GPUDevice オブジェクトのインスタンスで解決する Promise です。

重複して呼び出した場合、すなわち requestDevice() が既に呼び出されている GPUAdapter で requestDevice() を呼び出した場合、プロミスは即ロストするデバイスで解決します。そして、デバイスがどうしてロストしたのかの情報を GPUDevice.lost から取得できます。

例外

OperationError DOMException

requiredLimits プロパティに含まれる制限が有効な制限でないか、値がアダプターの制限値より高いために GPUAdapter が対応していない場合、プロミスは OperationError で拒否されます。

TypeError DOMException

requiredFeatures プロパティに含まれる機能に GPUAdapter が対応していない場合、プロミスは TypeError で拒否されます。

例

基本的な例

js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU に対応していません。");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("WebGPU アダプターを要求できませんでした。");
  }

  const device = await adapter.requestDevice();

  // ...
}

特定の機能と制限を要求する

以下のコードでは、

  1. GPUAdapter で texture-compression-astc 機能が利用可能かをチェックします。利用可能であれば、それを配列 requiredFeatures にプッシュします。
  2. GPUAdapter.limits の maxBindGroups の値を問い合わせ、6 以上であるかをチェックします。理論上のサンプルアプリケーションは理想的には 6 個のバインドグループを必要とするので、返された値が 6 以上の場合は requiredLimits オブジェクトに最大値 6 を追加適用します。
  3. これらの機能および制限の要件に defaultQueue ラベルを追加し、デバイスを要求します。
js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU に対応していません。");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("WebGPU アダプターを要求できませんでした。");
  }

  const requiredFeatures = [];

  if (adapter.features.has("texture-compression-astc")) {
    requiredFeatures.push("texture-compression-astc");
  }

  const requiredLimits = {};

  // アプリケーションは理想的には 6 個のバインドグループを必要とするので、
  // アプリケーションが必要とする分の要求を試みる
  if (adapter.limits.maxBindGroups >= 6) {
    requiredLimits.maxBindGroups = 6;
  }

  const device = await adapter.requestDevice({
    defaultQueue: {
      label: "myqueue",
    },
    requiredFeatures,
    requiredLimits,
  });

  // ...
}

仕様書

Specification
WebGPU
# dom-gpuadapter-requestdevice

ブラウザーの互換性

BCD tables only load in the browser

関連情報