# VertexBuffer

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/platform/graphics/vertex-buffer.js#L18

A vertex buffer is the mechanism via which the application specifies vertex data to the graphics
hardware.

## Constructors

### constructor

```ts
new VertexBuffer(graphicsDevice: GraphicsDevice, format: VertexFormat, numVertices: number, options?: object, ...args: any[])
```

Create a new VertexBuffer instance.

**Parameters**

- `graphicsDevice` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device used to manage this vertex
  buffer.
- `format` ([`VertexFormat`](https://api.playcanvas.com/engine/classes/VertexFormat.md)): The vertex format of this vertex buffer.
- `numVertices` (`number`): The number of vertices that this vertex buffer will hold.
- `options` (`object`, optional): Object for passing optional arguments.
    - `options.data` (`ArrayBuffer | ArrayBufferView<ArrayBufferLike>`, optional): Initial data. Can be an
      `ArrayBuffer` or a typed array (for example a `Float32Array`). The data is
      stored by reference and is not copied, so a typed array that is a view into a larger buffer
      is kept as-is. If left unspecified, the vertex buffer will be initialized to zeros.
    - `options.storage` (`boolean`, optional): Defines if the vertex buffer can be used as a storage
      buffer by a compute shader. Defaults to false. Only supported on WebGPU.
    - `options.usage` (`number`, optional): The usage type of the vertex buffer (see BUFFER_*).
      Defaults to BUFFER_STATIC.
- `args` (`any[]`)

## Methods

### destroy

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

Frees resources associated with this vertex buffer.

### getFormat

```ts
getFormat(): VertexFormat
```

Returns the data format of the specified vertex buffer.

**Returns** [`VertexFormat`](https://api.playcanvas.com/engine/classes/VertexFormat.md): The data format of the specified vertex buffer.

### getNumVertices

```ts
getNumVertices(): number
```

Returns the number of vertices stored in the specified vertex buffer.

**Returns** `number`: The number of vertices stored in the vertex buffer.

### getUsage

```ts
getUsage(): number
```

Returns the usage type of the specified vertex buffer. This indicates whether the buffer can
be modified once and used many times [BUFFER_STATIC](https://api.playcanvas.com/engine/variables/BUFFER_STATIC.md), modified repeatedly and used
many times [BUFFER_DYNAMIC](https://api.playcanvas.com/engine/variables/BUFFER_DYNAMIC.md) or modified once and used at most a few times
[BUFFER_STREAM](https://api.playcanvas.com/engine/variables/BUFFER_STREAM.md).

**Returns** `number`: The usage type of the vertex buffer (see BUFFER_*).

### lock

```ts
lock(): ArrayBuffer | ArrayBufferView<ArrayBufferLike>
```

Returns a mapped memory block representing the content of the vertex buffer.

**Returns** `ArrayBuffer | ArrayBufferView<ArrayBufferLike>`: The memory that stores the buffer's vertices. This
matches whatever was supplied as the initial data: an [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) when none was
provided, otherwise the [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or typed array that was passed in. Use
[ArrayBufferConstructor.isView](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView) to distinguish the two before accessing it.

### setData

```ts
setData(data?: ArrayBuffer | ArrayBufferView<ArrayBufferLike>): boolean
```

Sets the data of the vertex buffer and uploads it to the GPU.

**Parameters**

- `data` (`ArrayBuffer | ArrayBufferView<ArrayBufferLike>`, optional): Source data. Can be an [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or
  a typed array. Stored by reference, not copied.

**Returns** `boolean`: True if function finished successfully, false otherwise.

### unlock

```ts
unlock(byteOffset?: number, byteLength?: number): void
```

Uploads the client side copy of the vertex buffer to the GPU. When called without arguments,
uploads the entire buffer. An explicit range uploads only those bytes at the same GPU offset.
The first upload always initializes the entire GPU buffer, regardless of the requested range.
A zero byte length does nothing, including before the first upload.

Partial uploads do not resize the buffer or change its CPU storage. The caller must upload
every modified range before expecting those changes on the GPU. Context restoration uploads
the entire CPU storage. Invalid ranges are ignored in all builds and report an assertion
in debug builds.

**Parameters**

- `byteOffset` (`number`, optional): Offset in bytes from the start of the buffer's storage.
  Defaults to 0. Must be a non-negative integer and a multiple of 4 on all graphics backends.
- `byteLength` (`number`, optional): Number of bytes to upload. Defaults to the remaining bytes
  after byteOffset. The length must be a non-negative integer and the range must fit within
  the buffer. Partial ranges require a length that is a multiple of 4. Full-buffer uploads
  support any byte length, whether the range is explicit or the arguments are omitted.

**Example**

```ts
// After modifying bytes 16 through 31 of the CPU storage:
vertexBuffer.unlock(16, 16);
```