# IndexBuffer

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/platform/graphics/index-buffer.js#L23

An index buffer stores index values into a [VertexBuffer](https://api.playcanvas.com/engine/classes/VertexBuffer.md). Indexed graphical primitives
can normally utilize less memory that unindexed primitives (if vertices are shared).

Typically, index buffers are set on [Mesh](https://api.playcanvas.com/engine/classes/Mesh.md) objects.

## Constructors

### constructor

```ts
new IndexBuffer(graphicsDevice: GraphicsDevice, format: number, numIndices: number, usage?: number, initialData?: ArrayBuffer | ArrayBufferView<ArrayBufferLike>, options?: object)
```

Create a new IndexBuffer instance.

**Parameters**

- `graphicsDevice` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device used to manage this index buffer.
- `format` (`number`): The type of each index to be stored in the index buffer. Can be:

  - [INDEXFORMAT_UINT8](https://api.playcanvas.com/engine/variables/INDEXFORMAT_UINT8.md)
  - [INDEXFORMAT_UINT16](https://api.playcanvas.com/engine/variables/INDEXFORMAT_UINT16.md)
  - [INDEXFORMAT_UINT32](https://api.playcanvas.com/engine/variables/INDEXFORMAT_UINT32.md)
- `numIndices` (`number`): The number of indices to be stored in the index buffer.
- `usage` (`number`, optional, default `BUFFER_STATIC`): The usage type of the vertex buffer. Can be:

  - [BUFFER_DYNAMIC](https://api.playcanvas.com/engine/variables/BUFFER_DYNAMIC.md)
  - [BUFFER_STATIC](https://api.playcanvas.com/engine/variables/BUFFER_STATIC.md)
  - [BUFFER_STREAM](https://api.playcanvas.com/engine/variables/BUFFER_STREAM.md)

  Defaults to [BUFFER_STATIC](https://api.playcanvas.com/engine/variables/BUFFER_STATIC.md).
- `initialData` (`ArrayBuffer | ArrayBufferView<ArrayBufferLike>`, optional): Initial data. Can be an
  [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or a typed array (for example a [Uint16Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array)). 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 index buffer will be initialized to zeros.
- `options` (`object`, optional): Object for passing optional arguments.
    - `options.storage` (`boolean`, optional): Defines if the index buffer can be used as a storage
      buffer by a compute shader. Defaults to false. Only supported on WebGPU.

**Example**

```ts
// Create an index buffer holding 3 16-bit indices. The buffer is marked as
// static, hinting that the buffer will never be modified.
const indices = new Uint16Array([0, 1, 2]);
const indexBuffer = new IndexBuffer(graphicsDevice,
                                       INDEXFORMAT_UINT16,
                                       3,
                                       BUFFER_STATIC,
                                       indices);
```

## Methods

### destroy

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

Frees resources associated with this index buffer.

### getFormat

```ts
getFormat(): number
```

Returns the data format of the specified index buffer.

**Returns** `number`: The data format of the specified index buffer. Can be:

- [INDEXFORMAT_UINT8](https://api.playcanvas.com/engine/variables/INDEXFORMAT_UINT8.md)
- [INDEXFORMAT_UINT16](https://api.playcanvas.com/engine/variables/INDEXFORMAT_UINT16.md)
- [INDEXFORMAT_UINT32](https://api.playcanvas.com/engine/variables/INDEXFORMAT_UINT32.md)

### getNumIndices

```ts
getNumIndices(): number
```

Returns the number of indices stored in the specified index buffer.

**Returns** `number`: The number of indices stored in the specified index buffer.

### lock

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

Gives access to the block of memory that stores the buffer's indices.

**Returns** `ArrayBuffer | ArrayBufferView<ArrayBufferLike>`: The memory that stores the buffer's indices. 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.

### unlock

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

Uploads the client side copy of the index 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:
indexBuffer.unlock(16, 16);
```