GPUDevice: Methode createRenderPipelineAsync()

Limited availability

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

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die createRenderPipelineAsync()-Methode der GPUDevice-Schnittstelle gibt ein Promise zurück, das mit einem GPURenderPipeline erfüllt wird. Diese kann die Vertex- und Fragment-Shader-Stufen steuern und in einem GPURenderPassEncoder oder GPURenderBundleEncoder verwendet werden, sobald die Pipeline ohne Verzögerung verwendet werden kann.

Hinweis: Es ist im Allgemeinen vorzuziehen, diese Methode anstelle von GPUDevice.createRenderPipeline() zu verwenden, wann immer dies möglich ist, da sie das Blockieren der GPU-Betriebsausführung bei der Pipeline-Kompilierung verhindert.

Syntax

js
createRenderPipelineAsync(descriptor)

Parameter

descriptor

Siehe die Deskriptor-Definition für die Methode GPUDevice.createRenderPipeline().

Rückgabewert

Ein Promise, das mit einer GPURenderPipeline-Objektinstanz erfüllt wird, wenn die erstellte Pipeline bereit ist, ohne zusätzliche Verzögerung verwendet zu werden.

Validierung

Wenn die Pipelinenerstellung fehlschlägt und infolgedessen die resultierende Pipeline ungültig wird, wird das zurückgegebene Promise mit einem GPUPipelineError zurückgewiesen:

  • Wenn dies auf einen internen Fehler zurückzuführen ist, hat der GPUPipelineError einen reason von "internal".
  • Wenn dies aufgrund eines Validierungsfehlers geschieht, hat der GPUPipelineError einen reason von "validation".

Ein Validierungsfehler kann auftreten, wenn eine der folgenden Bedingungen falsch ist:

  • Für depthStencil-Objekte:
    • format ist ein depth-or-stencil Format.
    • Die Eigenschaften depthBias, depthBiasClamp und depthBiasSlopeScale sind für Linien- und Punkt-Topologien auf 0 gesetzt, das heißt, wenn topology auf "line-list", "line-strip" oder "point-list" gesetzt ist.
    • Wenn depthWriteEnabled true ist oder depthCompare nicht "always" ist, hat format eine Tiefenkomponente.
    • Wenn die Eigenschaften von stencilFront oder stencilBack nicht auf ihren Standardwerten liegen, hat format eine Stencil-Komponente.
  • Für fragment-Objekte:
    • targets.length ist kleiner oder gleich dem maxColorAttachments Limit des GPUDevice.
    • Für jedes target ist das numerische Äquivalent von writeMask kleiner als 16.
    • Wenn eine der verwendeten Blendfaktor-Operationen den Alphakanal der Quelle verwendet (zum Beispiel "src-alpha-saturated"), hat die Ausgabe einen Alphakanal (das heißt, es muss ein vec4 sein).
    • Wenn die entryPoint-Eigenschaft weggelassen wird, enthält der Shader-Code eine einzelne Fragment-Shader-Einstiegspunktfunktion, die vom Browser als Standardeinstiegspunkt verwendet werden kann.
  • Für primitive-Objekte:
    • Wenn die unclippedDepth-Eigenschaft verwendet wird, ist die depth-clip-control Funktion aktiviert.
  • Für vertex-Objekte:
    • Wenn die entryPoint-Eigenschaft weggelassen wird, enthält der Shader-Code eine einzelne Vertex-Shader-Einstiegspunktfunktion, die vom Browser als Standardeinstiegspunkt verwendet werden kann.

Beispiele

Hinweis: Die WebGPU-Beispiele enthalten viele weitere Beispiele.

Einfaches Beispiel

Das folgende Beispiel zeigt ein einfaches Beispiel für die Konstruktion eines gültigen Render-Pipeline-Deskriptor-Objekts, das dann verwendet wird, um eine GPURenderPipeline via einem createRenderPipelineAsync()-Aufruf zu erstellen.

js
async function init() {
  // ...

  const vertexBuffers = [
    {
      attributes: [
        {
          shaderLocation: 0, // position
          offset: 0,
          format: "float32x4",
        },
        {
          shaderLocation: 1, // color
          offset: 16,
          format: "float32x4",
        },
      ],
      arrayStride: 32,
      stepMode: "vertex",
    },
  ];

  const pipelineDescriptor = {
    vertex: {
      module: shaderModule,
      entryPoint: "vertex_main",
      buffers: vertexBuffers,
    },
    fragment: {
      module: shaderModule,
      entryPoint: "fragment_main",
      targets: [
        {
          format: navigator.gpu.getPreferredCanvasFormat(),
        },
      ],
    },
    primitive: {
      topology: "triangle-list",
    },
    layout: "auto",
  };

  const renderPipeline =
    await device.createRenderPipelineAsync(pipelineDescriptor);

  // ...
}

Spezifikationen

Specification
WebGPU
# dom-gpudevice-createrenderpipelineasync

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
createRenderPipelineAsync
Experimental
Dual-source blending: src1, one-minus-src1, src1-alpha, and one-minus-src1-alpha blend factors.
Experimental
depthCompare and depthWriteEnabled properties are optional when not needed (for example, formats without depth).
Experimental
entryPoint properties are optional for determined default fragment and vertex shader entry points.
Experimental
rgb10a2uint texture format
Experimental
Validates that depthBias, depthBiasSlopeScale, and depthBiasClamp must be 0 for line and point topologies.
Experimental
unorm10-10-10-2 vertex format
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

Siehe auch