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

js
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 calling GPUBuffer.getMappedRange(). The default value is false.

Note that it is valid to set mappedAtCreation: true so you can set the buffer's initial data, even if the GPUBufferUsage.MAP_READ or GPUBufferUsage.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 the GPUBuffer.usage value table.

Note that multiple possible usages can be specified by separating values with pipe symbols, for example:

js
usage: 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 than GPUBufferUsage.COPY_DST.
  • GPUBufferUsage.MAP_WRITE is specified, and no additional flags are specified other than GPUBufferUsage.COPY_SRC.
  • mappedAtCreation: true is specified, and the specified size 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.

js
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

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
createBuffer
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

See also