# StorageBuffer

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/dfcc50fbbfba2388843041a875ec0ef5d1a586c5/src/platform/graphics/storage-buffer.js#L26

A storage buffer represents a memory which both the CPU and the GPU can access. Typically it is
used to provide data for compute shader, and to store the result of the computation.
Note that this class is only supported on the WebGPU platform.

After a graphics device is lost and restored, the GPU backing for a storage buffer is
recreated at the same byte size but its contents are undefined until you write to it again or
repopulate it via compute.

For debug identification in buffer memory listings (when the [TRACEID_BUFFERS](https://api.playcanvas.com/engine/variables/TRACEID_BUFFERS.md) trace
channel is enabled), call sites may assign the instance's `name` property to a descriptive
string.

## Constructors

### constructor

```ts
new StorageBuffer(graphicsDevice: GraphicsDevice, byteSize: number, bufferUsage?: number, addStorageUsage?: boolean)
```

Create a new StorageBuffer instance.

**Parameters**

- `graphicsDevice` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device used to manage this storage buffer.
- `byteSize` (`number`): The size of the storage buffer in bytes.
- `bufferUsage` (`number`, optional, default `0`): The usage type of the storage buffer. Can be a combination
  of [BUFFERUSAGE_READ](https://api.playcanvas.com/engine/variables/BUFFERUSAGE_READ.md), [BUFFERUSAGE_WRITE](https://api.playcanvas.com/engine/variables/BUFFERUSAGE_WRITE.md), [BUFFERUSAGE_COPY_SRC](https://api.playcanvas.com/engine/variables/BUFFERUSAGE_COPY_SRC.md) and
  [BUFFERUSAGE_COPY_DST](https://api.playcanvas.com/engine/variables/BUFFERUSAGE_COPY_DST.md) flags. This parameter can be omitted if no special usage is
  required.
- `addStorageUsage` (`boolean`, optional, default `true`): If true, automatically adds BUFFERUSAGE_STORAGE flag.
  Set to false for staging buffers that use BUFFERUSAGE_WRITE. Defaults to true.

## Methods

### clear

```ts
clear(offset?: number, size?: number): void
```

Clear the content of a storage buffer to 0.

**Parameters**

- `offset` (`number`, optional, default `0`): The byte offset of data to clear. Defaults to 0.
- `size` (`number`, optional): The byte size of data to clear. Defaults to the full size of the
  buffer minus the offset.

### copy

```ts
copy(srcBuffer: StorageBuffer, srcOffset?: number, dstOffset?: number, size?: number): void
```

Copy data from another storage buffer into this storage buffer.

**Parameters**

- `srcBuffer` ([`StorageBuffer`](https://api.playcanvas.com/engine/classes/StorageBuffer.md)): The source storage buffer to copy from.
- `srcOffset` (`number`, optional, default `0`): The byte offset in the source buffer. Defaults to 0.
- `dstOffset` (`number`, optional, default `0`): The byte offset in this buffer. Defaults to 0.
- `size` (`number`, optional): The byte size of data to copy. Defaults to the full size of the
  source buffer minus the source offset.

### destroy

```ts
destroy(): void
```

Frees resources associated with this storage buffer.

### read

```ts
read(offset?: number, size?: number, data?: ArrayBufferView<ArrayBufferLike> | null, immediate?: boolean): Promise<ArrayBufferView<ArrayBufferLike>>
```

Read the contents of a storage buffer.

**Parameters**

- `offset` (`number`, optional, default `0`): The byte offset of data to read. Defaults to 0.
- `size` (`number`, optional): The byte size of data to read. Defaults to the full size of the
  buffer minus the offset.
- `data` (`ArrayBufferView<ArrayBufferLike> | null`, optional, default `null`): Typed array to populate with the data read from the
  storage buffer. When typed array is supplied, enough space needs to be reserved, otherwise
  only partial data is copied. If not specified, the data is returned in an Uint8Array.
  Defaults to null.
- `immediate` (`boolean`, optional, default `false`): If true, the read operation will be executed as soon as
  possible. This has a performance impact, so it should be used only when necessary. Defaults
  to false.

**Returns** `Promise<ArrayBufferView<ArrayBufferLike>>`: A promise that resolves with the data read from the
storage buffer.

### write

```ts
write(bufferOffset?: number, data: ArrayBuffer | ArrayBufferView<ArrayBufferLike>, dataOffset?: number, size?: number): void
```

Issues a write operation of the provided data into a storage buffer.

**Parameters**

- `bufferOffset` (`number`, optional, default `0`): The offset in bytes to start writing to the storage buffer.
- `data` (`ArrayBuffer | ArrayBufferView<ArrayBufferLike>`): The data to write to the storage buffer.
- `dataOffset` (`number`, optional, default `0`): Offset in data to begin writing from. Given in elements if
  data is a TypedArray and bytes otherwise. Defaults to 0.
- `size` (`number`, optional): Size of content to write from data to buffer. Given in elements if
  data is a TypedArray and bytes otherwise. Defaults to the remaining size of the data.