VGPUAdapter

VGPUAdapter is the minimal core adapter interface. Use it when code should request a vgpu Device without caring whether the backing implementation is browser WebGPU, Node/Dawn, or the mock adapter.

Import

import type { VGPUAdapter } from "vgpu/core";

Signature

import type { Device, RequiredDeviceLimits } from "vgpu/core";
 
interface CreateDeviceOptions {
  readonly powerPreference?: GPUPowerPreference;
  readonly requiredFeatures?: readonly GPUFeatureName[];
  readonly requiredLimits?: RequiredDeviceLimits;
  readonly label?: string;
}
 
interface VGPUAdapter {
  requestDevice(opts?: CreateDeviceOptions): Promise<Device>;
}

Parameters

requestDevice(opts?) / CreateDeviceOptions

Returns: requestDevice(opts?) returns Promise<Device> wrapping the raw GPUDevice created by the concrete adapter.

Throws:

• VGPU-RING1-UNSUPPORTED may be thrown by higher-level browser/node initialization paths when no adapter factory or browser adapter is available — provide a concrete adapter such as createMockAdapter() or run in a WebGPU-capable environment.
• Adapter-specific VGPU-* errors can be thrown before the core Device exists, for example Node adapter binary/adapter failures — inspect .code, .message, and .fix on VGPUError.
• VGPU-FEATURE-UNSUPPORTED is thrown before device creation when requiredFeatures names a feature the adapter does not support — remove the unsupported name(s) or use an adapter that supports them.
• Native WebGPU request errors may be thrown when requiredLimits values are unsupported — request only capabilities reported by the chosen adapter.

Examples

import type { Device, VGPUAdapter } from "vgpu/core";
import { createMockAdapter } from "vgpu/mock";
 
async function withDevice(adapter: VGPUAdapter): Promise<Device> {
  return adapter.requestDevice({ label: "example-device" });
}
 
const device = await withDevice(createMockAdapter());
console.log(device.queue.gpu);
device.destroy();

import type { VGPUAdapter } from "vgpu/core";
import { createMockAdapter } from "vgpu/mock";
 
const adapter: VGPUAdapter = createMockAdapter();
const device = await adapter.requestDevice({
  powerPreference: "high-performance",
  requiredFeatures: [],
  requiredLimits: {},
});
 
const buffer = device.createBuffer({ size: 4, usage: ["copy_dst", "copy_src"] });
buffer.write(new Uint32Array([42]));
console.log(new Uint32Array(await buffer.read(4))[0]);
 
device.destroy();

Notes

• VGPUAdapter is an interface, not a class. Import it with import type unless you only need documentation prose.
• The core interface intentionally has a small portable option set. Concrete adapters can extend it without changing VGPUAdapter.
• The mock adapter honors requiredFeatures against its declared createMockAdapter({ features }) set (default none) and ignores the other CreateDeviceOptions; do not use a passing mock request as proof that native required features/limits are available.
• Use Device.features and Device.limits after request to gate optional code paths.
• See also: Device, CreateDeviceOptions, VGPUError, createMockAdapter.