一个 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 上查看此页面 • 报告此内容的问题