GPUBuffer: mapAsync() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The mapAsync()
method of the
GPUBuffer
interface maps the specified range of the GPUBuffer
. It returns a Promise
that resolves when the GPUBuffer
's content is ready to be accessed. While the GPUBuffer
is mapped it cannot be used in any GPU commands.
Once the buffer is successfully mapped (which can be checked via GPUBuffer.mapState
), calls to GPUBuffer.getMappedRange()
will return an ArrayBuffer
containing the GPUBuffer
's current values, to be read and updated by JavaScript as required.
When you have finished working with the GPUBuffer
values, call GPUBuffer.unmap()
to unmap it, making it accessible to the GPU again.
Syntax
js
mapAsync(mode)
mapAsync(mode, offset, size)
Parameters
mode
-
A bitwise flag that specifies whether the
GPUBuffer
is mapped for reading or writing. Possible values are:GPUMapMode.READ
-
The
GPUBuffer
is mapped for reading. Values can be read, but any changes made to theArrayBuffer
returned byGPUBuffer.getMappedRange()
will be discarded onceGPUBuffer.unmap()
is called.Read-mode mapping can only be used on
GPUBuffer
s that have a usage ofGPUBufferUsage.MAP_READ
set on them (i.e. when created withGPUDevice.createBuffer()
). GPUMapMode.WRITE
-
The
GPUBuffer
is mapped for writing. Values can be read and updated — any changes made to theArrayBuffer
returned byGPUBuffer.getMappedRange()
will be saved to theGPUBuffer
onceGPUBuffer.unmap()
is called.Write-mode mapping can only be used on
GPUBuffer
s that have a usage ofGPUBufferUsage.MAP_WRITE
set on them (i.e. when created withGPUDevice.createBuffer()
).
offset
Optional-
A number representing the offset, in bytes, from the start of the buffer to the start of the range to be mapped. If
offset
is omitted, it defaults to 0. size
Optional-
A number representing the size, in bytes, of the range to be mapped. If
size
is omitted, the range mapped extends to the end of theGPUBuffer
.
Return value
Validation
The following criteria must be met when calling mapSync()
, otherwise an OperationError
DOMException
is thrown, the promise is rejected, and a GPUValidationError
is generated:
offset
is a multiple of 8.- The total range to be mapped (
size
if specified, orGPUBuffer.size
-offset
if not) is a multiple of 4. - The total range to be mapped is inside the bounds of the
GPUBuffer
. - If mode is
GPUMapMode.READ
, theGPUBuffer
has a usage ofGPUBufferUsage.MAP_READ
. - If mode is
GPUMapMode.WRITE
, theGPUBuffer
has a usage ofGPUBufferUsage.MAP_WRITE
.
Examples
See the main GPUBuffer
page for an example.
Specifications
Specification |
---|
WebGPU # dom-gpubuffer-mapasync |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API