GPUDevice: createRenderPipeline() Methode

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

depthStencil Optional

Ein Objekt (siehe depthStencil Objektstruktur), das Tiefen-Stencil-Eigenschaften beschreibt, einschließlich Tests, Operationen und Bias.

fragment Optional

Ein Objekt (siehe fragment Objektstruktur), das den Fragment-Shader-Einstiegspunkt der Pipeline und deren Ausgabefarben beschreibt. Wenn kein Fragment-Shader-Einstiegspunkt definiert ist, erzeugt die Pipeline keine Farbanhangausgaben, führt aber trotzdem Rasterisierung durch und erzeugt Tiefenwerte basierend auf der Vertexposition-Ausgabe. Tiefentests und Stencil-Operationen können dennoch verwendet werden.

label Optional

Ein String, der ein Label bereitstellt, das verwendet werden kann, um das Objekt zu identifizieren, beispielsweise in GPUError-Nachrichten oder Konsolenwarnungen.

layout

Definiert das Layout (Struktur, Zweck und Typ) aller GPU-Ressourcen (Buffers, Texturen usw.), die während der Ausführung der Pipeline verwendet werden. Mögliche Werte sind:

• Ein GPUPipelineLayout-Objekt, erstellt mit GPUDevice.createPipelineLayout(), das es der GPU ermöglicht, im Voraus zu ermitteln, wie die Pipeline am effizientesten ausgeführt wird.
• Ein String "auto", der die Pipeline veranlasst, ein implizites Bind-Group-Layout basierend auf den im Shader-Code definierten Bindungen zu generieren. Wenn "auto" verwendet wird, können die generierten Bind-Group-Layouts nur mit der aktuellen Pipeline verwendet werden.

multisample Optional

Ein Objekt (siehe multisample Objektstruktur), das beschreibt, wie die Pipeline mit den multigesampelten Anhängen eines Renderpass umgeht.

primitive Optional

Ein Objekt (siehe primitive Objektstruktur), das beschreibt, wie eine Pipeline Primitive aus ihren Vertexeingaben konstruiert und rasterisiert.

vertex

Ein Objekt (siehe vertex Objektstruktur), das den Vertex-Shader-Einstiegspunkt der Pipeline und deren Eingabepufferlayouts beschreibt.

Das depthStencil Objekt kann die folgenden Eigenschaften enthalten:

depthBias Optional

Eine Zahl, die einen konstanten Tiefenbias darstellt, der zu jedem Fragment hinzugefügt wird. Wenn nicht angegeben, ist depthBias standardmäßig 0.

Hinweis: Die Eigenschaften depthBias, depthBiasClamp und depthBiasSlopeScale müssen auf 0 gesetzt werden für Linien- und Punkt-Topologien, d.h. wenn topology auf "line-list", "line-strip" oder "point-list" eingestellt ist. Andernfalls wird ein GPUValidationError erzeugt und die zurückgegebene GPURenderPipeline ist ungültig.

depthBiasClamp Optional

Eine Zahl, die den maximalen Tiefenbias eines Fragments darstellt. Wenn nicht angegeben, ist depthBiasClamp standardmäßig 0.

depthBiasSlopeScale Optional

Eine Zahl, die einen Tiefenbias darstellt, der mit der Neigung des Fragments skaliert wird. Wenn nicht angegeben, ist depthBiasSlopeScale standardmäßig 0.

depthCompare

Ein enumerierter Wert, der die Vergleichsoperation angibt, die verwendet wird, um Fragmenttiefen gegen depthStencilAttachment Tiefenwerte zu testen. Mögliche Werte sind:

• "never": Vergleichstests schlagen immer fehl.
• "less": Ein gegebener Wert besteht den Vergleichstest, wenn er kleiner als der abgetastete Wert ist.
• "equal": Ein gegebener Wert besteht den Vergleichstest, wenn er gleich dem abgetasteten Wert ist.
• "less-equal": Ein gegebener Wert besteht den Vergleichstest, wenn er kleiner oder gleich dem abgetasteten Wert ist.
• "greater": Ein gegebener Wert besteht den Vergleichstest, wenn er größer als der abgetastete Wert ist.
• "not-equal": Ein gegebener Wert besteht den Vergleichstest, wenn er nicht gleich dem abgetasteten Wert ist.
• "greater-equal": Ein gegebener Wert besteht den Vergleichstest, wenn er größer oder gleich dem abgetasteten Wert ist.
• "always": Vergleichstests bestehen immer.

depthWriteEnabled

Ein Boolean. Ein Wert von true gibt an, dass die GPURenderPipeline die depthStencilAttachment Tiefenwerte nach der Erstellung ändern kann. Wenn false gesetzt ist, kann sie es nicht.

format

Ein enumerierter Wert, der das depthStencilAttachment-Format angibt, mit dem die GPURenderPipeline kompatibel sein wird. Lesen Sie den Abschnitt Texturformate der Spezifikation für alle verfügbaren format-Werte.

stencilBack Optional

Ein Objekt, das definiert, wie Stencil-Vergleiche und -Operationen für rückwärts gerichtete Primitive durchgeführt werden. Dessen Eigenschaften können umfassen:

compare Optional

Ein enumerierter Wert, der die Vergleichsoperation festlegt, die beim Testen von Fragmenten gegen depthStencilAttachment Stencil-Werte verwendet wird. Mögliche Werte sind die gleichen wie für die Eigenschaft depthCompare; siehe oben. Wenn nicht angegeben, ist compare standardmäßig "always".

depthFailOp Optional

Ein enumerierter Wert, der die Stencil-Operation beschreibt, die ausgeführt wird, wenn der Fragmenttiefenvergleich beschrieben durch depthCompare fehlschlägt. Mögliche Werte sind:

• "decrement-clamp": Der aktuelle Renderzustand-Wert wird dekrementiert und bei 0 geklammert.
• "decrement-wrap": Der aktuelle Renderzustand-Stencil-Wert wird dekrementiert und auf den maximal darstellbaren Wert des Stencil-Aspekts von depthStencilAttachment gewickelt, wenn der Wert unter 0 fällt.
• "invert": Der aktuelle Renderzustand-Stencil-Wert wird bitweise invertiert.
• "increment-clamp": Der aktuelle Renderzustand-Stencil-Wert wird inkrementiert und auf den maximal darstellbaren Wert des Stencil-Aspekts von depthStencilAttachment geklammert.
• "increment-wrap": Der aktuelle Renderzustand-Stencil-Wert wird inkrementiert und auf null gewickelt, wenn der Wert den maximal darstellbaren Wert des Stencil-Aspekts von depthStencilAttachment überschreitet.
• "keep": Der aktuelle Stencil-Wert bleibt erhalten.
• "replace": Der Stencil-Wert wird auf den aktuellen Renderzustand-Stencil-Wert gesetzt.
• "zero": Der Stencil-Wert wird auf 0 gesetzt.

Wenn nicht angegeben, ist depthFailOp standardmäßig "keep".

Hinweis: Der Renderzustand-Stencil-Wert wird zu Beginn eines Renderpass auf 0 gesetzt.

failOp Optional

Ein enumerierter Wert, der die Stencil-Operation beschreibt, die ausgeführt wird, wenn der Fragmentstencil-Vergleichstest beschrieben durch compare fehlschlägt. Die möglichen und Standardwerte sind die gleichen wie für depthFailOp.

passOp Optional

Ein enumerierter Wert, der die Stencil-Operation beschreibt, die ausgeführt wird, wenn der Fragmentstencil-Vergleichstest beschrieben durch compare besteht. Die möglichen und Standardwerte sind die gleichen wie für depthFailOp.

stencilFront Optional

Ein Objekt, das definiert, wie Stencil-Vergleiche und -Operationen für vorwärts gerichtete Primitive durchgeführt werden. Dessen Eigenschaften sind die gleichen wie für stencilBack.

stencilReadMask Optional

Eine Bitmaske, die steuert, welche depthStencilAttachment Stencil-Wert-Bits gelesen werden, wenn Stencil-Vergleichstests durchgeführt werden. Wenn nicht angegeben, ist stencilReadMask standardmäßig 0xFFFFFFFF.

stencilWriteMask Optional

Eine Bitmaske, die steuert, welche depthStencilAttachment Stencil-Wert-Bits geschrieben werden, wenn Stencil-Operationen durchgeführt werden. Wenn nicht angegeben, ist stencilWriteMask standardmäßig 0xFFFFFFFF.

Das fragment-Objekt enthält ein Array von Objekten, von denen jedes die folgenden Eigenschaften enthalten kann:

constants Optional

Eine Folge von Aufzeichnungstypen mit der Struktur (id, value), die Überschreibwerte für WGSL-Konstanten, die in der Pipeline überschrieben werden können, darstellen. Diese verhalten sich wie geordnete Karten. In jedem Fall ist id ein Schlüssel, der verwendet wird, um den Datensatz zu identifizieren oder auszuwählen, und das constant ist ein enumerierter Wert, der ein WGSL darstellt.

Abhängig davon, welche Konstante Sie überschreiben möchten, kann id die Form der numerischen ID der Konstante annehmen, falls eine angegeben ist, oder sonst der Bezeichnername der Konstante.

Ein Codeausschnitt, der Überschreibwerte für mehrere überschreibbare Konstanten bereitstellt, könnte folgendermaßen aussehen:

js

{
  // ...
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  }
}

entryPoint

Der Name der Funktion im module, die diese Phase verwenden wird, um ihre Aufgaben auszuführen. Die entsprechende Shader-Funktion muss das @fragment-Attribut haben, um als dieser Einstiegspunkt identifiziert zu werden. Siehe Einstiegspunktdeklaration für mehr Informationen.

module

Ein GPUShaderModule-Objekt, das den WGSL-Code enthält, den diese programmierte Phase ausführen wird.

targets

Ein Array von Objekten, die Farbzustände darstellen, welche Konfigurationsdetails für die Farben bieten, die von der Fragment-Shader-Phase ausgegeben werden. Diese Objekte können die folgenden Eigenschaften enthalten:

blend Optional

Ein Objekt, das einen Mischmodus beschreibt, der auf die Ausgabefarbe angewendet werden soll. blend hat zwei Eigenschaften:

alpha

Beschreibt den Alphakanalwert.

color

Beschreibt den Farbwert.

alpha und color nehmen beide ein Objekt als Wert, das die folgenden Eigenschaften enthalten können:

dstFactor Optional

Ein enumerierter Wert, der den Mischfaktor-Operation definiert, der auf Werte aus dem Zielanhäng durchgeführt wird. Mögliche Werte sind:

• "constant"
• "dst"
• "dst-alpha"
• "one"
• "one-minus-dst"
• "one-minus-src"
• "one-minus-src1"
• "one-minus-src-alpha"
• "one-minus-src1-alpha"
• "one-minus-dst-alpha"
• "one-minus-constant"
• "src"
• "src1"
• "src-alpha"
• "src1-alpha"
• "src-alpha-saturated"
• "zero"

Wenn nicht angegeben, ist dstFactor standardmäßig "zero".

Hinweis: Die dual-source-blending Funktion muss aktiviert sein, damit die src1, one-minus-src1, src1-alpha und one-minus-src1-alpha Mischfaktor-Operationen erfolgreich verwendet werden können. Andernfalls wird ein GPUValidationError erzeugt.

operation Optional

Ein enumerierter Wert, der den Algorithmus bestimmt, der verwendet wird, um Quell- und Zielmischfaktoren zu kombinieren, um die endgültigen an die Zielanhänge geschriebenen Werte zu berechnen. Mögliche Werte sind:

• "add"
• "max"
• "min"
• "reverse-subtract"
• "subtract"

Wenn nicht angegeben, ist operation standardmäßig "add".

srcFactor Optional

Ein enumerierter Wert, der den Mischfaktor-Operation definiert, der auf Werte aus dem Fragment-Shader ausgeführt wird. Mögliche Werte sind die gleichen wie für dstFactor. Wenn nicht angegeben, ist srcFactor standardmäßig "one".

Hinweis: Für eine detaillierte Erklärung der Algorithmen, die durch jeden dstFactor/srcFactor und operation enumerierten Wert definiert sind, siehe den Blend State Abschnitt der Spezifikation.

format

Ein enumerierter Wert, der das erforderliche Format für Ausgabefarben spezifiziert. Siehe den Abschnitt Texturformate der Spezifikation für alle verfügbaren format-Werte.

writeMask Optional

Eine oder mehrere Bitweise Flaggen, die die Schreibmasken für die Zustände des Farbziels definieren. Mögliche Flaggenwerte sind:

• GPUColorWrite.RED
• GPUColorWrite.GREEN
• GPUColorWrite.BLUE
• GPUColorWrite.ALPHA
• GPUColorWrite.ALL

Wenn nicht angegeben, ist writeMask standardmäßig GPUColorWrite.ALL.

Beachten Sie, dass mehrere Flaggen durch Trennzeichen mit Pipesymbolen angegeben werden können, zum Beispiel:

js

writeMask: GPUColorWrite.RED | GPUColorWrite.ALPHA;

Das multisample Objekt kann die folgenden Eigenschaften enthalten:

alphaToCoverageEnabled Optional

Ein Boolean. Ein Wert von true zeigt an, dass der Alphakanal eines Fragments verwendet werden soll, um eine Beispielabdeckungsmaske zu generieren. Wenn nicht angegeben, ist alphaToCoverageEnabled standardmäßig false.

count Optional

Eine Zahl, die die Anzahl der Samples pro Pixel definiert. Die Pipeline wird nur mit Anhängtexturen (colorAttachments und depthStencilAttachments) kompatibel sein, mit übereinstimmenden sampleCounts (siehe GPUTexture).

Wenn nicht angegeben, ist count standardmäßig 1.

mask Optional

Eine Bitmaske, die bestimmt, welche Samples geschrieben werden. Wenn nicht angegeben, ist mask standardmäßig 0xFFFFFFFF.

Das primitive Objekt kann die folgenden Eigenschaften enthalten:

cullMode Optional

Ein enumerierter Wert, der definiert, welche Ausrichtung des Polygons geschnitten wird, wenn überhaupt. Mögliche Werte sind:

• "back": Rückwärtsgerichtete Polygone werden geschnitten.
• "front": Vorwärtsgerichtete Polygone werden geschnitten.
• "none": Keine Polygone werden geschnitten.

Wenn nicht angegeben, ist cullMode standardmäßig "none".

frontFace Optional

Ein enumerierter Wert, der definiert, welche Polygone als vorwärtsgerichtet angesehen werden. Mögliche Werte sind:

• "ccw": Polygone mit Vertices, deren Framebuffer-Koordinaten im gegen den Uhrzeigersinn angegeben sind.
• "cw": Polygone mit Vertices, deren Framebuffer-Koordinaten im Uhrzeigersinn angegeben sind.

Wenn nicht angegeben, ist frontFace standardmäßig "ccw".

Hinweis: > frontFace und cullMode haben keine Auswirkungen auf "point-list", "line-list" oder "line-strip" Topologien.

stripIndexFormat Optional

Ein enumerierter Wert, der das Indexpufferformat und den primären Neustartwert im Fall von Pipelines mit Streifentopologien ("line-strip" oder "triangle-strip") bestimmt. Der primäre Neustartwert gibt an, welcher Indexwert anzeigt, dass ein neues Primäres gestartet werden soll, anstatt den Streifen mit den vorher indexierten Vertices fortzusetzen. Mögliche Werte sind:

• "uint16": Gibt eine Bytegröße von 2 und einen primären Neustartwert von 0xFFFF an.
• "uint32": Gibt eine Bytegröße von 4 und einen primären Neustartwert von 0xFFFFFFFF an.

GPU primäre Zustände, die eine Streifenprimäre-Topologie spezifizieren, müssen ein Streifenindexformat angeben, wenn sie für indizierte Zeichnungen verwendet werden (zum Beispiel über GPURenderPassEncoder.drawIndexed()), damit der primäre Neustartwert, der verwendet werden soll, zum Zeitpunkt der Pipelineerstellung bekannt ist. Pipelines mit listigen primären Topologien ("line-list", "point-list" oder "triangle-list") sollten keinen stripIndexFormat-Wert angeben. Sie verwenden stattdessen das Indexformat, das beispielsweise an GPURenderPassEncoder.setIndexBuffer() übergeben wird, wenn indiziertes Rendern durchgeführt wird.

topology Optional

Ein enumerierter Wert, der den Typ des Primitives definiert, der aus den angegebenen vertex-Eingaben konstruiert werden soll. Mögliche Werte sind:

• "line-list": Jedes aufeinanderfolgende Paar von zwei Vertices definiert ein Linienprimär.
• "line-strip": Jeder Vertex nach dem ersten definiert ein Linienprimär zwischen ihm und dem vorherigen Vertex.
• "point-list": Jeder Vertex definiert ein Punktprimär.
• "triangle-list": Jedes aufeinanderfolgende Tripel von drei Vertices definiert ein Dreiecksprimär.
• "triangle-strip": Jeder Vertex nach den ersten beiden definiert ein Dreiecksprimär zwischen ihm und den vorherigen zwei Vertices.

Wenn nicht angegeben, ist topology standardmäßig "triangle-list".

unclippedDepth Optional

Ein Boolean. Ein Wert von true zeigt an, dass die Tiefenausklammerung deaktiviert ist. Wenn nicht angegeben, ist unclippedDepth standardmäßig false. Beachten Sie, dass die depth-clip-control Funktion im GPUDevice aktiviert sein muss, um die Tiefenausklammerung zu steuern.

Hinweis: Die depth-clip-control Funktion muss aktiviert sein, damit die unclippedDepth-Eigenschaft erfolgreich verwendet werden kann. Andernfalls wird ein GPUValidationError erzeugt.

Das vertex Objekt kann die folgenden Eigenschaften enthalten:

constants Optional

Eine Folge von Aufzeichnungstypen mit der Struktur (id, value), die Überschreibwerte für WGSL-Konstanten, die in der Pipeline überschrieben werden können, darstellen. Diese verhalten sich wie geordnete Karten. In jedem Fall ist id ein Schlüssel, der verwendet wird, um den Datensatz zu identifizieren oder auszuwählen, und das constant ist ein enumerierter Wert, der ein WGSL darstellt.

Abhängig davon, welche Konstante Sie überschreiben möchten, kann id die Form der numerischen ID der Konstante annehmen, falls eine angegeben ist, oder sonst der Bezeichnername der Konstante.

Ein Codeausschnitt, der Überschreibwerte für mehrere überschreibbare Konstanten bereitstellt, könnte folgendermaßen aussehen:

js

{
  // ...
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  }
}

entryPoint

Der Name der Funktion im module, die diese Phase verwenden wird, um ihre Aufgaben auszuführen. Die entsprechende Shader-Funktion muss das @vertex-Attribut haben, um als dieser Einstiegspunkt identifiziert zu werden. Siehe Einstiegspunktdeklaration für mehr Informationen.

module

Ein GPUShaderModule-Objekt, das den WGSL-Code enthält, den diese programmierte Phase ausführen wird.

buffers Optional

Ein Array von Objekten, die jeweils das erwartete Layout eines Vertexpuffers darstellen, der in der Pipeline verwendet wird. Jedes Objekt kann die folgenden Eigenschaften enthalten:

arrayStride

Eine Zahl, die den Abstand, in Bytes, zwischen den verschiedenen Strukturen (z. B. Vertices) innerhalb des Puffers darstellt.

attributes

Ein Array von Objekten, die das Layout der Vertexattribute innerhalb jeder Struktur definieren. Jedes Objekt hat die folgenden Eigenschaften:

format

Ein enumerierter Wert, der das Format des Vertex spezifiziert. Für alle verfügbaren Werte siehe die Definition GPUVertexFormat in der Spezifikation.

offset

Eine Zahl, die den Versatz in Bytes vom Anfang der Struktur bis zu den Daten für das Attribut angibt.

shaderLocation

Die numerische Position, die mit diesem Attribut verknüpft ist, die mit einem @location Attribut im WGSL-Code des zugehörigen GPUShaderModule erklärt wird, das in der module Eigenschaft des vertex-Objekts referenziert wird.

stepMode Optional

Ein enumerierter Wert, der definiert, ob die separaten Strukturen im Puffer Vertices oder Instanzen darstellen. Mögliche Werte sind:

• "instance": Jede Struktur ist eine Instanz – die Adresse wird um arrayStride für jede Instanz erhöht.
• "vertex": Jede Struktur ist ein Vertex – die Adresse wird um arrayStride für jeden Vertex erhöht und zwischen Instanzen zurückgesetzt.

Wenn nicht angegeben, ist stepMode standardmäßig "vertex".

Eine Instanz des GPURenderPipeline-Objekts.

Die folgenden Kriterien müssen erfüllt sein, wenn createRenderPipeline() aufgerufen wird, ansonsten wird ein GPUValidationError erzeugt und ein ungültiges GPURenderPipeline-Objekt zurückgegeben:

• Für depthStencil-Objekte:
  • format ist ein depth-or-stencil-Format.
  • Die Eigenschaften depthBias, depthBiasClamp und depthBiasSlopeScale sind auf 0 gesetzt für Linien- und Punkt-Topologien, d.h. wenn topology auf "line-list", "line-strip" oder "point-list" eingestellt 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 sind, 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 Mischfaktor-Operationen den Alpha-Kanal der Quelle nutzen (z.B. "src-alpha-saturated"), muss die Ausgabe einen Alpha-Kanal haben (d.h. es muss sich um einen vec4 handeln).
  • Wenn die src1, one-minus-src1, src1-alpha oder one-minus-src1-alpha Mischfaktor-Operationen verwendet werden, muss die dual-source-blending Funktion aktiviert sein.
• Für primitive-Objekte:
  • Wenn die unclippedDepth-Eigenschaft verwendet wird, muss die depth-clip-control Funktion aktiviert sein.

Unser simples Render-Demo bietet ein einfaches Beispiel für die Konstruktion eines gültigen Renderpipeline-Deskriptor-Objekts, das dann verwendet wird, um eine GPURenderPipeline über einen createRenderPipeline()-Aufruf zu erstellen.

// ...

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 = device.createRenderPipeline(pipelineDescriptor);

// ...

• Die WebGPU API