GPUCanvasContext: configure() 方法

可用性有限

此特性不是基线特性,因为它在一些最广泛使用的浏览器中不起作用。

安全上下文: 此功能仅在安全上下文(HTTPS)中可用,且支持此功能的浏览器数量有限。

注意:此功能在 Web Workers 中可用。

GPUCanvasContext 接口的 configure() 方法使用给定的 GPUDevice 配置上下文以用于渲染。调用时,画布将最初被清除为透明黑色。

语法

js
configure(configuration)

参数

configuration

包含以下属性的对象:

alphaMode 可选

一个枚举值,指定当通过 getCurrentTexture() 返回的纹理被读取、显示或用作图像源时,alpha 值将对其内容产生的影响。可能的值为:

  • opaque:alpha 值将被忽略——如果纹理本身不是不透明的,那么当它被用作图像源或显示在屏幕上时,alpha 通道将被清除为 1.0。这是默认值。
  • premultiplied:颜色值将与其 alpha 值预乘。例如,50% alpha 的 100% 红色是 [0.5, 0, 0, 0.5]
colorSpace 可选

写入 getCurrentTexture() 返回的纹理中的值的显示应使用的颜色空间。可能的值为 srgb(默认值)和 display-p3

device

上下文的渲染信息将从中获取的 GPUDevice

格式(format)

getCurrentTexture() 返回的纹理的格式。可以是 bgra8unormrgba8unormrgba16float。当前系统的最佳画布纹理格式可以通过 GPU.getPreferredCanvasFormat() 返回。建议使用它——如果您在配置画布上下文时没有使用首选格式,可能会产生额外的开销,例如额外的纹理复制,具体取决于平台。

toneMapping 可选

一个对象,用于指定定义上下文的色调映射参数——即关联纹理的内容将如何显示。这允许 WebGPU 绘制比 white#FFFFFF)更亮的颜色。可能的属性包括:

mode 可选

指定画布的色调映射模式的枚举值。可能的值包括:

standard

默认值。将渲染内容限制在显示器的标准动态范围(SDR)内。此模式通过将颜色空间中的所有颜色值裁剪到 [0, 1] 间隔来实现。

extended

如果可用,允许内容以显示器的全高动态范围(HDR)进行渲染。HDR 模式允许显示更宽的颜色和亮度级别范围,并提供更精确的指示,说明每种情况应显示什么颜色。此模式匹配屏幕的 [0, 1] 范围内的 "standard"。裁剪或投影到屏幕的扩展动态范围,而不是 [0, 1]

usage 可选

指定 getCurrentTexture() 返回的纹理允许使用的 按位标志。可能的值为:

  • GPUTextureUsage.COPY_SRC:纹理可以用作复制操作的源,例如 GPUCommandEncoder.copyTextureToBuffer() 调用的源参数。
  • GPUTextureUsage.COPY_DST:纹理可以用作复制/写入操作的目标,例如 GPUCommandEncoder.copyTextureToTexture() 调用的目标参数。
  • GPUTextureUsage.RENDER_ATTACHMENT:纹理可以用作渲染通道中的颜色附件,例如 GPUCommandEncoder.beginRenderPass() 调用中的颜色附件视图。GPUTextureUsage.RENDER_ATTACHMENT 是默认的 usage,但请注意,如果显式设置了不同的值,它不会自动包含;在这种情况下,您需要额外包含它。
  • GPUTextureUsage.TEXTURE_BINDING:纹理可以绑定以在着色器中用作采样纹理,例如 GPUDevice.createBindGroup() 调用中的绑定组条目。
  • GPUTextureUsage.STORAGE_BINDING:纹理可以绑定以在着色器中用作存储纹理,例如 GPUDevice.createBindGroup() 调用中的绑定组条目。

请注意,可以使用 按位 OR 运算符指定多个可能的用法。例如,usage: GPUTextureUsage.COPY_SRC | GPUTextureUsage.RENDER_ATTACHMENT

viewFormats 可选

getCurrentTexture() 返回的纹理创建的视图可能使用的格式数组。有关所有可能值的详细信息,请参阅 纹理格式

返回值

无 (undefined)。

示例

基本用法

js
const canvas = document.querySelector("#gpuCanvas");
const context = canvas.getContext("webgpu");

context.configure({
  device,
  format: navigator.gpu.getPreferredCanvasFormat(),
  alphaMode: "premultiplied",
});

HDR toneMapping 演示

请参阅 Particles (HDR) 示例和 HDR 支持测试。

规范

规范
WebGPU
# dom-gpucanvascontext-configure

浏览器兼容性

另见