---
title: Queue
description: `Queue` is the core wrapper around a raw `GPUQueue`. Use it for explicit buffer writes and for awaiting completion of already-submitted GPU work.
---

# Queue



## Import

```ts
import { Queue } from "vgpu/core";
```

## Signature

```ts
import type { BufferWriteData } from "vgpu/core";

declare class Queue {
  readonly gpu: GPUQueue;
  constructor(gpu: GPUQueue);
  writeBuffer(buffer: GPUBuffer, offset: number, data: BufferWriteData): void;
  flush(): Promise<void>;
}
```

## Parameters

### Constructor

| Param | Type       | Required | Default | Notes                                                                                              |
| ----- | ---------- | -------: | ------- | -------------------------------------------------------------------------------------------------- |
| gpu   | `GPUQueue` |        ✔ | —       | Raw WebGPU queue exposed again as `queue.gpu`. `Device` constructs `new Queue(gpu.queue)` for you. |

### `writeBuffer(buffer, offset, data)`

| Param  | Type                                          | Required | Default | Notes                                                                                   |
| ------ | --------------------------------------------- | -------: | ------- | --------------------------------------------------------------------------------------- |
| buffer | `GPUBuffer`                                   |        ✔ | —       | Raw destination buffer. Pass `buffer.gpu` when you have a vgpu `Buffer`.                |
| offset | `number`                                      |        ✔ | —       | Destination byte offset. Unlike `Buffer.write(...)`, there is no default at this level. |
| data   | `ArrayBuffer \| ArrayBufferView<ArrayBuffer>` |        ✔ | —       | Bytes forwarded to `GPUQueue.writeBuffer(buffer, offset, data)`.                        |

### `flush()`

| Param | Type | Required | Default | Notes                                                      |
| ----- | ---- | -------: | ------- | ---------------------------------------------------------- |
| —     | —    |        — | —       | Takes no parameters. Awaits `gpu.onSubmittedWorkDone?.()`. |

**Returns:**

* `new Queue(gpu)` returns a queue wrapper.
* `writeBuffer(buffer, offset, data)` returns `void`.
* `flush()` returns `Promise<void>` after `GPUQueue.onSubmittedWorkDone()` resolves, or immediately if the queue implementation has no `onSubmittedWorkDone` method.

**Throws:** Native WebGPU validation errors may occur when `writeBuffer(...)` writes beyond the buffer bounds, uses an invalid offset/data size, or targets a buffer without `COPY_DST` usage — fix the buffer descriptor and write range.

## Examples

```ts
import { createMockAdapter } from "vgpu/mock";

const device = await createMockAdapter().requestDevice();
const buffer = device.createBuffer({ size: 8, usage: ["copy_dst", "copy_src"] });

device.queue.writeBuffer(buffer.gpu, 0, new Uint32Array([10, 20]));
await device.queue.flush();

const bytes = await buffer.read(8);
console.log(new Uint32Array(bytes)[1]); // 20

device.destroy();
```

```ts
import { Queue } from "vgpu/core";
import { createMockAdapter } from "vgpu/mock";

const device = await createMockAdapter().requestDevice();
const queue = new Queue(device.gpu.queue);
await queue.flush();

device.destroy();
```

## Notes

* `Buffer.write(data, offset = 0)` is the safer high-level call for vgpu buffers; it defaults the offset and checks wrapper lifecycle before reaching the queue.
* `Queue.writeBuffer(...)` intentionally accepts raw `GPUBuffer` so it can interoperate with native WebGPU resources.
* `flush()` waits for submitted work; it does not submit command buffers by itself.
* Do not use `flush()` as a per-frame synchronization point unless CPU/GPU synchronization is intentional.
* **See also:** `Device`, `Buffer`, `Texture`.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)