GPUDevice: createRenderPipeline() 方法

descriptor

包含以下属性的对象

depthStencil 可选

一个对象（参见 depthStencil 对象结构），描述深度模板属性，包括测试、操作和偏差。

fragment 可选

一个对象（参见 fragment 对象结构），描述管道的片段着色器入口点及其输出颜色。如果未定义片段着色器入口点，则管道不会生成任何颜色附件输出，但它仍然执行光栅化并根据顶点位置输出生成深度值。深度测试和模板操作仍然可以使用。

label 可选

一个字符串，提供一个标签，可用于标识对象，例如在 GPUError 消息或控制台警告中。

layout

定义在管道执行期间使用的所有 GPU 资源（缓冲区、纹理等）的布局（结构、用途和类型）。可能的值为

• 一个 GPUPipelineLayout 对象，使用 GPUDevice.createPipelineLayout() 创建，它允许 GPU 预先确定如何以最有效的方式运行管道。
• 字符串 "auto"，这会导致管道根据着色器代码中定义的任何绑定生成隐式绑定组布局。如果使用 "auto"，则生成的绑定组布局可能仅与当前管道一起使用。

multisample 可选

一个对象（参见 multisample 对象结构），描述管道如何与渲染通道的多采样附件交互。

primitive 可选

一个对象（参见 primitive 对象结构），描述管道如何从其顶点输入构建和光栅化图元。

vertex

一个对象（参见 vertex 对象结构），描述管道的顶点着色器入口点及其输入缓冲区布局。

depthStencil 对象可以包含以下属性

depthBias 可选

一个数字，表示添加到每个片段的恒定深度偏差。如果省略，则 depthBias 默认为 0。

depthBiasClamp 可选

一个数字，表示片段的最大深度偏差。如果省略，则 depthBiasClamp 默认为 0。

depthBiasSlopeScale 可选

一个数字，表示随片段斜率缩放的深度偏差。如果省略，则 depthBiasSlopeScale 默认为 0。

depthCompare

一个枚举值，指定用于测试片段深度与 depthStencilAttachment 深度值的比较操作。可能的值为

• "never"：比较测试永远不会通过。
• "less"：如果提供的值小于采样值，则通过比较测试。
• "equal"：如果提供的值等于采样值，则通过比较测试。
• "less-equal"：如果提供的值小于或等于采样值，则通过比较测试。
• "greater"：如果提供的值大于采样值，则通过比较测试。
• "not-equal"：如果提供的值不等于采样值，则通过比较测试。
• "greater-equal"：如果提供的值大于或等于采样值，则通过比较测试。
• "always"：比较测试始终通过。

depthWriteEnabled

一个布尔值。值为 true 指定 GPURenderPipeline 创建后可以修改 depthStencilAttachment 深度值。将其设置为 false 表示它不能修改。

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 的模板方面的最大可表示值，则将其环绕到零。
• "keep"：保留当前模板值。
• "replace"：将模板值设置为当前渲染状态模板值。
• "zero"：将模板值设置为 0。

如果省略，则 depthFailOp 默认为 "keep"。

注意：在渲染通道开始时，渲染状态模板值初始化为 0。

failOp 可选

一个枚举值，指定如果由 compare 描述的片段模板比较测试失败，则执行的模板操作。可能的值和默认值与 depthFailOp 相同。

passOp 可选

一个枚举值，指定如果由 compare 描述的片段模板比较测试通过，则执行的模板操作。可能的值和默认值与 depthFailOp 相同。

stencilFront 可选

一个对象，定义如何对正面图元执行模板比较和操作。其属性与 stencilBack 相同。

stencilReadMask 可选

一个位掩码，控制执行模板比较测试时读取哪些 depthStencilAttachment 模板值位。如果省略，则 stencilReadMask 默认为 0xFFFFFFFF。

stencilWriteMask 可选

一个位掩码，控制执行模板操作时写入哪些 depthStencilAttachment 模板值位。如果省略，则 stencilWriteMask 默认为 0xFFFFFFFF。

fragment 对象包含一个对象数组，每个对象可以包含以下属性

constants 可选

一系列记录类型，结构为 (id, value)，表示 管道中可以覆盖的 WGSL 常量 的覆盖值。它们的行为类似于 有序映射。在每种情况下，id 都是用于标识或选择记录的键，而 constant 是一个枚举值，表示 WGSL。

根据您要覆盖的常量，id 可以采用常量的数字 ID（如果指定了）或常量的标识符名称的形式。

提供几个可覆盖常量的覆盖值的代码片段可能如下所示

js

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

entryPoint

module 中函数的名称，此阶段将使用该函数执行其工作。相应的着色器函数必须具有 @fragment 属性才能被识别为此入口点。有关更多信息，请参阅 入口点声明。

module

一个 GPUShaderModule 对象，包含此可编程阶段将执行的 WGSL 代码。

targets

一个对象数组，表示颜色状态，这些状态表示片段着色器阶段输出的颜色配置详细信息。这些对象可以包括以下属性

blend 可选

一个对象，描述要应用于输出颜色的混合模式。blend 具有两个属性

alpha

描述 alpha 通道值。

color

描述颜色值。

alpha 和 color 都采用一个对象作为值，该对象可以包含以下属性

dstFactor 可选

一个枚举值，定义要对来自目标附件的值执行的混合因子操作。可能的值为

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

如果省略，则 dstFactor 默认为 "zero"。

operation 可选

一个枚举值，用于定义用于组合源和目标混合因子的算法，以计算写入目标附件组件的最终值。可能的取值包括：

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

如果省略，则operation默认为"add"。

srcFactor 可选

一个枚举值，用于定义对来自片段着色器的值执行的混合因子操作。可能的取值与dstFactor相同。如果省略，则srcFactor默认为"one"。

注意：有关每个dstFactor/srcFactor和operation枚举值定义的算法的详细说明，请参阅规范的混合状态部分。

format

一个枚举值，指定输出颜色的所需格式。有关所有可用的format值，请参阅规范的纹理格式部分。

writeMask 可选

一个或多个按位标志，用于定义要应用于颜色目标状态的写入掩码。可能的标志值包括：

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

如果省略，则writeMask默认为GPUColorWrite.ALL。

请注意，可以通过用管道符号分隔值来指定多个标志，例如：

js

writeMask: GPUColorWrite.RED | GPUColorWrite.ALPHA;

multisample对象可以包含以下属性：

alphaToCoverageEnabled 可选

布尔值。值为true表示应使用片段的alpha通道生成样本覆盖掩码。如果省略，则alphaToCoverageEnabled默认为false。

count 可选

一个数字，用于定义每个像素的样本数。管道将仅与具有匹配sampleCounts的附件纹理（colorAttachment和depthStencilAttachment）兼容（请参阅GPUTexture）。

如果省略，则count默认为1。

mask 可选

一个位掩码，用于确定写入哪些样本。如果省略，则mask默认为0xFFFFFFFF。

primitive对象可以包含以下属性：

cullMode 可选

一个枚举值，用于定义如果存在，将剔除哪个多边形方向。可能的取值包括：

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

如果省略，则cullMode默认为"none"。

frontFace 可选

一个枚举值，用于定义哪些多边形被视为正面。可能的取值包括：

• "ccw"：顶点的帧缓冲区坐标按逆时针顺序给出的多边形。
• "cw"：顶点的帧缓冲区坐标按顺时针顺序给出的多边形。

如果省略，则frontFace默认为"ccw"。

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功能。

vertex对象可以包含以下属性：

constants 可选

一系列记录类型，结构为 (id, value)，表示 管道中可以覆盖的 WGSL 常量 的覆盖值。它们的行为类似于 有序映射。在每种情况下，id 都是用于标识或选择记录的键，而 constant 是一个枚举值，表示 WGSL。

根据您要覆盖的常量，id 可以采用常量的数字 ID（如果指定了）或常量的标识符名称的形式。

提供几个可覆盖常量的覆盖值的代码片段可能如下所示

js

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

entryPoint

module中函数的名称，此阶段将使用该函数执行其工作。相应的着色器函数必须具有@vertex属性才能被识别为此入口点。有关更多信息，请参阅入口点声明。

module

一个 GPUShaderModule 对象，包含此可编程阶段将执行的 WGSL 代码。

buffers 可选

对象数组，每个对象表示管道中使用的顶点缓冲区的预期布局。每个对象可以包含以下属性：

arrayStride

一个数字，表示缓冲区内不同结构（例如顶点）之间的跨度（以字节为单位）。

attributes

对象数组，用于定义每个结构中顶点属性的布局。每个对象都具有以下属性：

format

一个枚举值，用于指定顶点的格式。有关所有可用值，请参阅规范中的GPUVertexFormat定义。

offset

一个数字，指定从结构的开头到属性数据的偏移量（以字节为单位）。

shaderLocation

与此属性关联的数字位置，它将与在关联的GPUShaderModule（在vertex对象的module属性中引用）的WGSL代码中声明的@location属性相对应。

stepMode 可选

一个枚举值，用于定义缓冲区内的单独结构表示顶点还是实例。可能的取值包括：

• "instance"：每个结构都是一个实例——对于每个实例，地址都会增加arrayStride。
• "vertex"：每个结构都是一个顶点——对于每个顶点，地址都会增加arrayStride，并在实例之间重置。

如果省略，则stepMode默认为"vertex"。

一个GPURenderPipeline对象实例。

调用createRenderPipeline()时必须满足以下条件，否则将生成GPUValidationError并返回无效的GPURenderPipeline对象：

• 对于depthStencil对象：
  • format是一个depth-or-stencil格式。
  • 如果depthWriteEnabled为true或depthCompare不为"always"，则format具有深度分量。
  • 如果stencilFront或stencilBack的属性不处于其默认值，则format具有模板分量。
• 对于fragment对象：
  • targets.length小于或等于GPUDevice的maxColorAttachments限制。
  • 对于每个target，writeMask的数字等价物小于16。
  • 如果任何使用的混合因子操作使用源alpha通道（例如"src-alpha-saturated"），则输出具有alpha通道（即，它必须是vec4）。

我们的基本渲染演示提供了一个有效的渲染管道描述符对象的构造的简单示例，然后使用该对象通过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 API