Overview

Share one GPUDevice between vgpu and a machine learning runtime so model outputs stay on the GPU.

The initFromDevice(device) entry point adopts a GPUDevice that another library created. Use it when an ML runtime such as ONNX Runtime Web already owns a WebGPU device and you want vgpu shaders to consume the model's output buffers without a CPU roundtrip. The API is model-agnostic: vision, diffusion, embedding, or LLM outputs are all just GPUBuffers to vgpu.

vgpu never takes ownership of an adopted device. gpu.dispose() releases the resources vgpu created, but it never calls device.destroy() on a device it did not request.

import * as ort from "onnxruntime-web/webgpu";
import { initFromDevice } from "vgpu";
 
declare const session: ort.InferenceSession;
declare const input: ort.Tensor;
 
const gpu = await initFromDevice(await ort.env.webgpu.device); // one shared GPUDevice
const output = (await session.run({ input })).output;      // model output stays on the GPU
const source = gpu.device.wrapBuffer(output.gpuBuffer);    // consume it with zero copies

There are two ways to consume a model output: snapshot copies it once, GPU-to-GPU, into a buffer vgpu owns; reference wraps the runtime's buffer directly with zero copies. Buffers & ownership explains when to use each and the lifetime contract that comes with them.

Start with the quickstart for your environment:

• Quickstart: Browser — share ONNX Runtime Web's device in a page and consume a model output.
• Quickstart: Node — the pinned Dawn and ORT recipe, plus the portable fallback for hosts the stock binaries reject.
• Buffers & ownership — snapshot vs reference, wrapBuffer semantics, errors, and lifetime.

For the full API surface, see the reference for init, initFromDevice, Device, and Buffer.