一個 GPUPipelineLayout 物件，使用 GPUDevice.createPipelineLayout() 建立，允許 GPU 提前找出如何最有效地執行管線。
字串 "auto"，這將導致管線根據著色器程式碼中定義的任何繫結生成隱式繫結組佈局。如果使用 "auto"，生成的繫結組佈局只能與當前管線一起使用。

multisample 可選

一個物件（參見 multisample 物件結構），描述管線如何與渲染通道的多采樣附件互動。

primitive 可選

一個物件（參見 primitive 物件結構），描述管線如何從其頂點輸入構造和光柵化圖元。

頂點（vertex）

一個物件（參見 vertex 物件結構），描述管線的頂點著色器入口點及其輸入緩衝區佈局。

`depthStencil` 物件結構

depthStencil 物件可以包含以下屬性：

depthBias 可選

一個數字，表示新增到每個片段的常量深度偏差。如果省略，depthBias 預設為 0。

注意：對於線和點拓撲，即如果 topology 設定為 "line-list"、"line-strip" 或 "point-list"，則 depthBias、depthBiasClamp 和 depthBiasSlopeScale 屬性必須設定為 0。否則，將生成 GPUValidationError，並且返回的 GPURenderPipeline 將無效。

depthBiasClamp 可選

一個數字，表示片段的最大深度偏差。如果省略，depthBiasClamp 預設為 0。

depthBiasSlopeScale 可選

一個數字，表示隨片段斜率縮放的深度偏差。如果省略，depthBiasSlopeScale 預設為 0。

depthCompare 可選

一個列舉值，指定用於將片段深度與 depthStencilAttachment 深度值進行測試的比較操作。可能的值為：

"never"：比較測試永不透過。
"less"：如果提供的值小於取樣值，則透過比較測試。
"equal"：如果提供的值等於取樣值，則透過比較測試。
"less-equal"：如果提供的值小於或等於取樣值，則透過比較測試。
"greater"：如果提供的值大於取樣值，則透過比較測試。
"not-equal"：如果提供的值不等於取樣值，則透過比較測試。
"greater-equal"：如果提供的值大於或等於取樣值，則透過比較測試。
"always"：比較測試始終透過。

如果指定的 format 沒有深度分量，或者未使用比較操作，則不需要 depthCompare。

depthWriteEnabled 可選

一個布林值。值為 true 表示 GPURenderPipeline 可以在建立後修改 depthStencilAttachment 深度值。設定為 false 表示不能。

如果指定的 format 沒有深度分量，則不需要 depthWriteEnabled。

格式（format）

一個列舉值，指定 GPURenderPipeline 將相容的 depthStencilAttachment 格式。所有可用的 format 值請參閱規範的紋理格式部分。

stencilBack 可選

一個物件，定義如何對背面圖元執行模板比較和操作。其屬性可以包括：

compare 可選

一個列舉值，指定在將片段與 depthStencilAttachment 模板值進行測試時使用的比較操作。可能的值與 depthCompare 屬性相同；參見上文。如果省略，compare 預設為 "always"。

depthFailOp 可選

一個列舉值，指定如果 depthCompare 描述的片段深度比較失敗時執行的模板操作。可能的值為：

"decrement-clamp"：遞減當前渲染狀態的模板值，並將其鉗制到 0。
"decrement-wrap"：遞減當前渲染狀態的模板值，如果值小於 0，則將其迴圈到 depthStencilAttachment 模板方面的最大可表示值。
"invert"：按位反轉當前渲染狀態的模板值。
"increment-clamp"：遞增當前渲染狀態的模板值，並將其鉗制到 depthStencilAttachment 模板方面的最大可表示值。
"increment-wrap"：遞增當前渲染狀態的模板值，如果值超過 depthStencilAttachment 模板方面的最大可表示值，則將其迴圈到 0。
"keep"：保持當前模板值。
"replace"：將模板值設定為當前渲染狀態的模板值。
"zero"：將模板值設定為 0。

如果省略，depthFailOp 預設為 "keep"。

注意：渲染狀態模板值在渲染通道開始時初始化為 0。

failOp 可選

一個列舉值，指定如果 compare 描述的片段模板比較測試失敗時執行的模板操作。可能的值和預設值與 depthFailOp 相同。

passOp 可選

一個列舉值，指定如果 compare 描述的片段模板比較測試透過時執行的模板操作。可能的值和預設值與 depthFailOp 相同。

stencilFront 可選

一個物件，定義如何對正面圖元執行模板比較和操作。其屬性與 stencilBack 相同。

stencilReadMask 可選

一個位掩碼，控制在執行模板比較測試時讀取 depthStencilAttachment 模板值的哪些位。如果省略，stencilReadMask 預設為 0xFFFFFFFF。

stencilWriteMask 可選

一個位掩碼，控制在執行模板操作時寫入 depthStencilAttachment 模板值的哪些位。如果省略，stencilWriteMask 預設為 0xFFFFFFFF。

注意：depthStencilAttachment 值在 GPUCommandEncoder.beginRenderPass() 呼叫期間指定，即 GPURenderPipeline 實際用於執行渲染通道時。

`fragment` 物件結構

fragment 物件包含一個物件陣列，每個物件可以包含以下屬性：

constants 可選

一系列記錄型別，結構為 (id, value)，表示管線中可被覆蓋的 WGSL 常量的覆蓋值。這些行為類似於有序對映。在每種情況下，id 是用於識別或選擇記錄的鍵，constant 是表示 WGSL 的列舉值。

根據要覆蓋的常量，id 可以採用常量的數字 ID 形式（如果已指定），或者常量的識別符號名稱。

一個提供多個可覆蓋常量的覆蓋值的程式碼片段可能如下所示：

({
  // …
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  },
});

entryPoint 可選

module 中此階段將用於執行其工作的函式的名稱。相應的著色器函式必須具有 @fragment 屬性才能被識別為入口點。有關更多資訊，請參閱入口點宣告。

如果著色器程式碼包含一個設定了 @fragment 屬性的單個函式，則可以省略 entryPoint 屬性——瀏覽器將使用它作為預設入口點。如果省略 entryPoint 且瀏覽器無法確定預設入口點，則會生成 GPUValidationError，並且生成的 GPURenderPipeline 將無效。

模組

一個 GPUShaderModule 物件，包含此可程式設計階段將執行的 WGSL 程式碼。

目標（targets）

一個物件陣列，表示顏色狀態，這些顏色狀態表示片段著色器階段輸出的顏色的配置細節。這些物件可以包含以下屬性：

blend 可選

一個物件，描述要應用於輸出顏色的混合模式。blend 有兩個屬性：

alpha: 描述 Alpha 通道值。
color: 描述顏色值。

alpha 和 color 都接受一個物件作為值，該物件可以包含以下屬性：

dstFactor 可選

一個列舉值，定義要對來自目標附件的值執行的混合因子操作。可能的值為：

"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"

如果省略，dstFactor 預設為 "zero"。

注意：需要啟用 dual-source-blending 功能才能成功使用 src1、one-minus-src1、src1-alpha 和 one-minus-src1-alpha 混合因子操作。否則，將生成 GPUValidationError。

operation 可選

一個列舉值，定義用於組合源和目標混合因子以計算寫入目標附件元件的最終值的演算法。可能的值為：

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

如果省略，operation 預設為 "add"。

srcFactor 可選

一個列舉值，定義要對來自片段著色器的值執行的混合因子操作。可能的值與 dstFactor 相同。如果省略，srcFactor 預設為 "one"。

注意：有關每個 dstFactor/srcFactor 和 operation 列舉值定義的演算法的詳細說明，請參閱規範的混合狀態部分。

格式（format）

一個列舉值，指定輸出顏色所需的格式。所有可用的 format 值請參閱規範的紋理格式部分。

注意：對於 r32float、rg32float 和 rgba32float 格式與混合一起使用，裝置中必須提供 float32-blendable 功能。

writeMask 可選

一個或多個位標誌，定義應用於顏色目標狀態的寫入掩碼。可能的標誌值為：

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

如果省略，writeMask 預設為 GPUColorWrite.ALL。

請注意，可以透過使用按位或分隔值來指定多個標誌，例如：GPUColorWrite.RED | GPUColorWrite.ALPHA。

`multisample` 物件結構

multisample 物件可以包含以下屬性：

alphaToCoverageEnabled 可選

一個布林值。值為 true 表示片段的 alpha 通道應用於生成樣本覆蓋掩碼。如果省略，alphaToCoverageEnabled 預設為 false。

count 可選

一個數字，定義每個畫素的樣本數。管線將僅與具有匹配 sampleCounts 的附件紋理（colorAttachment 和 depthStencilAttachment）（參見 GPUTexture）相容。

如果省略，count 預設為 1。

mask 可選

一個位掩碼，確定寫入哪些樣本。如果省略，mask 預設為 0xFFFFFFFF。

注意：colorAttachment 和 depthStencilAttachment 值在 GPUCommandEncoder.beginRenderPass() 呼叫期間指定，即 GPURenderPipeline 實際用於執行渲染通道時。

`primitive` 物件結構

primitive 物件可以包含以下屬性：

cullMode 可選

一個列舉值，定義將剔除哪個多邊形方向（如果有）。可能的值為：

"back"：剔除背面多邊形。
"front"：剔除正面多邊形。
"none"：不剔除任何多邊形。

如果省略，cullMode 預設為 "none"。

frontFace 可選

一個列舉值，定義哪些多邊形被認為是正面。可能的值為：

"ccw"：頂點幀緩衝區座標以逆時針順序給出多邊形。
"cw"：頂點幀緩衝區座標以順時針順序給出多邊形。

如果省略，frontFace 預設為 "ccw"。

注意：frontFace 和 cullMode 值對 "point-list"、"line-list" 或 "line-strip" 拓撲沒有影響。

stripIndexFormat 可選

一個列舉值，在管線具有條帶拓撲（"line-strip" 或 "triangle-strip"）的情況下，確定索引緩衝區格式和圖元重啟值。圖元重啟值指定哪個索引值表示應該開始一個新的圖元，而不是繼續使用先前的索引頂點構造條帶。可能的值為：

"uint16"：表示位元組大小為 2，圖元重啟值為 0xFFFF。
"uint32"：表示位元組大小為 4，圖元重啟值為 0xFFFFFFFF。

指定條帶圖元拓撲的 GPU 圖元狀態必須在用於索引繪製（例如，透過 GPURenderPassEncoder.drawIndexed()）時指定條帶索引格式，以便在管線建立時知道將使用的圖元重啟值。具有列表圖元拓撲（"line-list"、"point-list" 或 "triangle-list"）的管線不應指定 stripIndexFormat 值。它們將轉而使用在進行索引渲染時傳遞給 GPURenderPassEncoder.setIndexBuffer() 的索引格式。

topology 可選

一個列舉值，定義要從指定的 vertex 輸入構造的圖元型別。可能的值為：

"line-list"：每連續一對兩個頂點定義一個線圖元。
"line-strip"：第一個頂點後的每個頂點都定義它與前一個頂點之間的線圖元。
"point-list"：每個頂點定義一個點圖元。
"triangle-list"：每連續三個頂點定義一個三角形圖元。
"triangle-strip"：前兩個頂點後的每個頂點都定義它與前兩個頂點之間的三角形圖元。

如果省略，topology 預設為 "triangle-list"。

unclippedDepth 可選

一個布林值。值為 true 表示停用深度裁剪。如果省略，unclippedDepth 預設為 false。請注意，要控制深度裁剪，必須在 GPUDevice 中啟用 depth-clip-control 功能。

注意：需要啟用 depth-clip-control 功能才能成功使用 unclippedDepth 屬性。否則，將生成 GPUValidationError。

`vertex` 物件結構

vertex 物件可以包含以下屬性：

constants 可選

根據要覆蓋的常量，id 可以採用常量的數字 ID 形式（如果已指定），或者常量的識別符號名稱。

一個提供多個可覆蓋常量的覆蓋值的程式碼片段可能如下所示：

({
  // …
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  },
});

entryPoint 可選

module 中此階段將用於執行其工作的函式的名稱。相應的著色器函式必須具有 @vertex 屬性才能被識別為入口點。有關更多資訊，請參閱入口點宣告。

如果著色器程式碼包含一個設定了 @vertex 屬性的單個函式，則可以省略 entryPoint 屬性——瀏覽器將使用它作為預設入口點。如果省略 entryPoint 且瀏覽器無法確定預設入口點，則會生成 GPUValidationError，並且生成的 GPURenderPipeline 將無效。

模組

一個 GPUShaderModule 物件，包含此可程式設計階段將執行的 WGSL 程式碼。

buffers 可選

一個物件陣列，每個物件表示管線中使用的頂點緩衝區的預期佈局。每個物件可以包含以下屬性：

陣列步長（arrayStride）

一個數字，表示緩衝區內不同結構（例如，頂點）之間的步長（以位元組為單位）。

attributes

一個物件陣列，定義每個結構中頂點屬性的佈局。每個物件具有以下屬性：

格式（format）: 一個列舉值，指定頂點的格式。有關所有可用值，請參閱規範中的 GPUVertexFormat 定義。
offset: 一個數字，指定從結構開始到屬性資料的偏移量（以位元組為單位）。
著色器位置（shaderLocation）: 與此屬性關聯的數字位置，該位置將與 vertex 物件的 module 屬性中引用的關聯 GPUShaderModule 的 WGSL 程式碼中宣告的 @location 屬性相對應。

stepMode 可選

一個列舉值，定義緩衝區內獨立結構是表示頂點還是例項。可能的值為：

"instance"：每個結構都是一個例項——每個例項的地址都按 arrayStride 遞增。
"vertex"：每個結構都是一個頂點——每個頂點的地址都按 arrayStride 遞增，並在例項之間重置。

如果省略，stepMode 預設為 "vertex"。

返回值

一個 GPURenderPipeline 物件例項。

驗證

呼叫 createRenderPipeline() 時必須滿足以下條件，否則將生成 GPUValidationError 並返回無效的 GPURenderPipeline 物件：

對於 depthStencil 物件：
- format 是 depth-or-stencil 格式。
- 對於線和點拓撲，即如果 topology 設定為 "line-list"、"line-strip" 或 "point-list"，則 depthBias、depthBiasClamp 和 depthBiasSlopeScale 屬性設定為 0。
- 如果 depthWriteEnabled 為 true 或 depthCompare 不為 "always"，則 format 具有深度分量。
- 如果 stencilFront 或 stencilBack 的屬性不為預設值，則 format 具有模板分量。
對於 fragment 物件：
- targets.length 小於或等於 GPUDevice 的 maxColorAttachments 限制。
- 對於每個 target，writeMask 的數值等價小於 16。
- 如果任何使用的混合因子操作使用源 alpha 通道（例如 "src-alpha-saturated"），則輸出具有 alpha 通道（即，它必須是 vec4）。
- 如果使用 src1、one-minus-src1、src1-alpha 或 one-minus-src1-alpha 混合因子操作，則啟用 dual-source-blending 功能。
- 如果省略 entryPoint 屬性，則著色器程式碼包含單個片段著色器入口點函式供瀏覽器用作預設入口點。
對於 primitive 物件：
- 如果使用 unclippedDepth 屬性，則啟用 depth-clip-control 功能。
對於 vertex 物件：
- 如果省略 entryPoint 屬性，則著色器程式碼包含單個頂點著色器入口點函式供瀏覽器用作預設入口點。

示例

注意：WebGPU 示例提供了更多示例。

基本示例

我們的基本渲染演示提供了一個有效渲染管線描述符物件的構建示例，該物件隨後透過 createRenderPipeline() 呼叫用於建立 GPURenderPipeline。

// …

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

// …

規範

規範
WebGPU # dom-gpudevice-createrenderpipeline

瀏覽器相容性

另見

WebGPU API

幫助改進 MDN

瞭解如何貢獻

本頁面最後由 MDN 貢獻者於 2025 年 6 月 24 日修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題