GPUDevice: createBuffer() method
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Note: This feature is available in Web Workers.
The createBuffer()
method of the
GPUDevice
interface creates a GPUBuffer
in which to store raw data to use in GPU operations.
Syntax
createBuffer(descriptor)
Parameters
descriptor
-
An object containing the following properties:
label
Optional-
A string providing a label that can be used to identify the object, for example in
GPUError
messages or console warnings. mappedAtCreation
Optional-
A boolean. If set to
true
, the buffer will be mapped upon creation, meaning that you can set the values inside the buffer immediately by callingGPUBuffer.getMappedRange()
. The default value isfalse
.Note that it is valid to set
mappedAtCreation: true
so you can set the buffer's initial data, even if theGPUBufferUsage.MAP_READ
orGPUBufferUsage.MAP_WRITE
usage flags are not set. size
-
A number representing the size of the buffer, in bytes.
usage
-
The bitwise flags representing the allowed usages for the
GPUBuffer
. The possible values are in theGPUBuffer.usage
value table.Note that multiple possible usages can be specified by separating values with pipe symbols, for example:
jsusage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE;
Return value
A GPUBuffer
object instance.
Validation
The following criteria must be met when calling createBuffer()
, otherwise a GPUValidationError
is generated and an invalid GPUBuffer
object is returned:
- A valid
usage
is specified. GPUBufferUsage.MAP_READ
is specified, and no additional flags are specified other thanGPUBufferUsage.COPY_DST
.GPUBufferUsage.MAP_WRITE
is specified, and no additional flags are specified other thanGPUBufferUsage.COPY_SRC
.mappedAtCreation: true
is specified, and the specifiedsize
is a multiple of 4.
Note:
If the buffer allocation fails without any specific side-effects, a GPUOutOfMemoryError
object is generated.
Examples
In our basic compute demo, we create an output buffer to read GPU calculations to, and a staging buffer to be mapped for JavaScript access.
const output = device.createBuffer({
size: BUFFER_SIZE,
usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
});
const stagingBuffer = device.createBuffer({
size: BUFFER_SIZE,
usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
});
Specifications
Specification |
---|
WebGPU # dom-gpudevice-createbuffer |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API