GPUDevice: createRenderPipelineAsync() 方法

实验性： 这是一种实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表。

安全上下文： 此功能仅在安全上下文（HTTPS）中可用，在某些或所有支持的浏览器中可用。

GPUDevice 接口的 createRenderPipelineAsync() 方法返回一个 Promise，该 Promise 使用一个 GPURenderPipeline 填充，该管道可以控制顶点和片段着色器阶段，并且可以在 GPURenderPassEncoder 或 GPURenderBundleEncoder 中使用，一旦管道可以使用而不会有任何停顿。

注意： 只要有可能，一般来说最好使用此方法而不是 GPUDevice.createRenderPipeline()，因为它可以防止在管道编译时阻塞 GPU 操作执行。

语法

createRenderPipelineAsync(descriptor)

参数

descriptor: 有关 GPUDevice.createRenderPipeline() 方法的描述符定义，请参见描述符定义。

返回值

一个 Promise，当创建的管道准备好在没有额外延迟的情况下使用时，该 Promise 将使用一个 GPURenderPipeline 对象实例填充。

验证

如果管道创建失败，导致生成的管道无效，则返回的 promise 将使用 GPUPipelineError 拒绝。

如果这是由于内部错误，则 GPUPipelineError 将具有 "internal" 的 reason。
如果这是由于验证错误，则 GPUPipelineError 将具有 "validation" 的 reason。

如果以下任何一项为假，则可能会发生验证错误

对于 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）。

示例

注意： WebGPU 示例提供了许多其他示例。

基本示例

以下示例展示了构建有效渲染管道描述符对象的示例，然后使用该对象通过 createRenderPipelineAsync() 调用创建 GPURenderPipeline。

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

  // ...
}

规范

规范
WebGPU # dom-gpudevice-createrenderpipelineasync

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

另请参见

WebGPU API