GPUCanvasContext: configure() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The configure()
method of the
GPUCanvasContext
interface configures the context to use for rendering with a given GPUDevice
. When called the canvas will initially be cleared to transparent black.
Syntax
js
configure(configuration)
Parameters
configuration
-
An object containing the following properties:
alphaMode
Optional-
An enumerated value that specifies the effect that alpha values will have on the content of textures returned by
getCurrentTexture()
when read, displayed, or used as an image source. Possible values are:opaque
: Alpha values are ignored — if a texture is not already opaque, the alpha channel is cleared to 1.0 when it is used as an image source or displayed to the screen. This is the default value.premultiplied
: Color values are premultiplied by their alpha value. For example, 100% red at 50% alpha is[0.5, 0, 0, 0.5]
.
colorSpace
Optional-
The color space that values written into textures returned by
getCurrentTexture()
should be displayed with. Possible values aresrgb
(the default) anddisplay-p3
. device
-
The
GPUDevice
that the rendering information for the context will come from. format
-
The format that textures returned by
getCurrentTexture()
will have. This can bebgra8unorm
,rgba8unorm
, orrgba16float
. The optimal canvas texture format for the current system can be returned byGPU.getPreferredCanvasFormat()
. Using this is recommended — if you don't use the preferred format when configuring the canvas context, you may incur additional overhead, such as additional texture copies, depending on the platform. usage
Optional-
Bitwise flags specifying the allowed usage for textures returned by
getCurrentTexture()
. Possible values are:GPUTextureUsage.COPY_SRC
: The texture can be used as the source of a copy operation, for example the source argument of aGPUCommandEncoder.copyTextureToBuffer()
call.GPUTextureUsage.COPY_DST
: The texture can be used as the destination of a copy/write operation, for example the destination argument of aGPUCommandEncoder.copyTextureToTexture()
call.GPUTextureUsage.RENDER_ATTACHMENT
: The texture can be used as a color attachment in a render pass, for example in a color attachment view in aGPUCommandEncoder.beginRenderPass()
call.GPUTextureUsage.RENDER_ATTACHMENT
is the defaultusage
, but note that it is not automatically included if a different value is explicitly set; in such cases you need to include it in addition.GPUTextureUsage.TEXTURE_BINDING
: The texture can be bound for use as a sampled texture in a shader, for example in a bind group entry in aGPUDevice.createBindGroup()
call.GPUTextureUsage.STORAGE_BINDING
: The texture can be bound for use as a storage texture in a shader, for example in a bind group entry in aGPUDevice.createBindGroup()
call.
Note that multiple possible usages can be specified using the bitwise OR operator. For example,
usage: GPUTextureUsage.COPY_SRC | GPUTextureUsage.RENDER_ATTACHMENT
. viewFormats
Optional-
An array of formats that views created from textures returned by
getCurrentTexture()
may use. See Texture Formats for all the possible values.
Return value
None (undefined
).
Examples
js
const canvas = document.querySelector("#gpuCanvas");
const context = canvas.getContext("webgpu");
context.configure({
device: device,
format: navigator.gpu.getPreferredCanvasFormat(),
alphaMode: "premultiplied",
});
Specifications
Specification |
---|
WebGPU # dom-gpucanvascontext-configure |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API