meshToReadable

Promotes a render Mesh into a CPU-readable shape by ensuring its vertex buffer has GPUBufferUsage.COPY_SRC. Use it before inspection tools (wireframe, byte comparisons) that need to read vertex data.

Import

import { meshToReadable } from "@vgpu/render/inspect";

Signature

export function meshToReadable(mesh: Mesh, device: Device): Promise<Mesh>;

Parameters

Returns: Promise<Mesh> — resolves to the original mesh when it already has copy_src usage or to a frozen clone that shares all metadata but replaces vertexBuffer with a readable copy.

Throws: VGPU-CORE-INVALID-USAGE when the source vertex buffer exposes an invalid GPUBuffer.usage mask (non-finite); fix by creating the geometry through geometry(gpu, ...) or adding copy_src when constructing buffers manually.

Examples

import { createMockAdapter } from "@vgpu/adapter-mock";
import { meshToReadable } from "@vgpu/render/inspect";
import { init, geometry } from "vgpu/mock";
import { box } from "vgpu/scene";
 
async function main(): Promise<void> {
  const adapter = createMockAdapter();
  const gpu = await init({ adapter });
  const geo = geometry(gpu, box({ size: 1 }));
 
  const readable = await meshToReadable(geo as never, gpu.device);
  const vertices = await readable.vertexBuffer.read(readable.vertexBuffer.options.size);
  console.log("Readable bytes", new Float32Array(vertices));
}
 
main().catch((error) => {
  console.error(error);
});

Notes

• When the input already includes copy_src, the function returns the exact same object; equality checks remain stable.
• Newly created readable buffers add copy_src (and copy_dst if it was missing) without removing the original usage flags.
• Index buffers and mesh metadata (vertexCount, attributes, etc.) are preserved by reference; only the vertex buffer identity changes.
• Await queue.onSubmittedWorkDone() in environments that expose it to guarantee the copy finished before reading.
• See also: meshToWireframe, wireframeMaterial