VirtualGPU API Reference

Complete method reference for VirtualGPU and all subsystem managers. Source: engine/core/gpu/VirtualGPU.js (2300 lines).

Guide first: If you're new to vGPU, read the Virtual GPU Guide before this reference.

Global Functions

async getVGPU(options?) → Promise<VirtualGPU>

Returns the global VirtualGPU singleton. Creates it on first call. Subsequent calls return the same instance.

Param	Type	Description
`options`	`Object?`	Passed to `GpuDevice.create()` — `powerPreference`, `requiredFeatures`, etc.

vgpu() → VirtualGPU

Synchronous access to the global singleton. Throws if getVGPU() hasn't been called yet.

async initVGPU(options?) → Promise<VirtualGPU>

Alias for getVGPU(). Provided for semantic clarity in initialization code.

static async VirtualGPU.create(options?) → Promise<VirtualGPU>

Creates a new (non-singleton) VirtualGPU instance.

static VirtualGPU.fromDevice(gpuDevice) → VirtualGPU

Wraps an existing GpuDevice instance in a VirtualGPU.

vgpu.buffer — VGPUBufferManager

buffer.create(options) → { buffer: GPUBuffer, id: number }

Create a GPU buffer with simplified usage strings and optional pooling.

Param	Type	Description
`options.size`	`number`	Buffer size in bytes
`options.usage`	`string\|number`	Usage string (`'vertex'`, `'storage'`, `'uniform'`, `'index'`, `'indirect'`, `'map-read'`, `'map-write'`) or raw flags. Pipe-separated for combinations: `'storage\|vertex'`
`options.label`	`string?`	Debug label
`options.data`	`TypedArray?`	Initial data to upload
`options.pooled`	`boolean?`	If true, allocate from buffer pool for reuse

buffer.write(buffer, data, offset?)

Write data to a buffer via queue.writeBuffer().

Param	Type	Description
`buffer`	`GPUBuffer`	Target buffer
`data`	`TypedArray`	Data to write
`offset`	`number?`	Byte offset into buffer (default 0)

buffer.release(id)

Release a managed buffer. Pooled buffers return to the pool; non-pooled are destroyed.

vgpu.bindings — VGPUBindingManager

bindings.defineLayout(name, entries) → GPUBindGroupLayout

Define a named bind group layout. Returns cached layout if already defined.

Param	Type	Description
`name`	`string`	Layout name for caching
`entries[]`	`Object[]`	Array of entry descriptors
`entry.binding`	`number`	Binding index
`entry.type`	`string`	`'uniform'`, `'storage'`, `'read-only-storage'`, `'texture'`, `'sampler'`, `'storage-texture'`
`entry.visibility`	`string?`	Pipe-separated: `'vertex'`, `'fragment'`, `'compute'`, `'vertex\|fragment'`. Default: all stages.

bindings.createGroup(layout, entries, label?) → GPUBindGroup

Create a bind group using a named or direct layout. Cached by entry hash.

Param	Type	Description
`layout`	`string\|GPUBindGroupLayout`	Layout name (from `defineLayout`) or raw layout
`entries[]`	`Object[]`	Standard `GPUBindGroupEntry` array
`label`	`string?`	Debug label

bindings.getLayout(name) → GPUBindGroupLayout|null

Retrieve a previously defined layout by name.

vgpu.shader — VGPUShaderManager

shader.compile(name, code, defines?) → GPUShaderModule

Compile a WGSL shader module. Cached by name — second call returns cached module.

Param	Type	Description
`name`	`string`	Unique name for caching
`code`	`string`	WGSL source code
`defines`	`Object?`	Preprocessor defines: `{ MAX_LIGHTS: 16 }`

shader.recompile(name, newCode, defines?) → GPUShaderModule

Hot-reload a shader. Replaces the cached module.

shader.get(name) → GPUShaderModule|null

Retrieve a compiled module by name without recompiling.

vgpu.pipeline — VGPUPipelineManager

pipeline.render(options) → GPURenderPipeline

Create (or return cached) render pipeline. Cached by full configuration hash.

Param	Type	Description
`options.vertex`	`Object`	`{ module, entryPoint?, buffers? }`
`options.fragment`	`Object`	`{ module, entryPoint?, targets }`
`options.blend`	`string?`	`'none'`, `'alpha'`, `'additive'`, `'premultiplied'`. Applied to all targets.
`options.depthStencil`	`boolean\|Object?`	`true` = depth24plus with less/write. Or full descriptor.
`options.topology`	`string?`	Default `'triangle-list'`
`options.layout`	`GPUPipelineLayout\|string?`	Default `'auto'`
`options.label`	`string?`	Debug label

async pipeline.renderAsync(options) → Promise<GPURenderPipeline>

Non-blocking pipeline creation. Ideal for loading screens.

pipeline.compute(options) → GPUComputePipeline

Create (or return cached) compute pipeline.

Param	Type	Description
`options.module`	`GPUShaderModule`	Compiled shader
`options.entryPoint`	`string?`	Default `'main'`
`options.layout`	`GPUPipelineLayout\|string?`	Default `'auto'`
`options.label`	`string?`	Debug label

async pipeline.computeAsync(options) → Promise<GPUComputePipeline>

Non-blocking compute pipeline creation.

vgpu.texture — VGPUTextureManager

texture.create(options) → { texture, view, id }

Create a GPU texture with simplified usage strings.

Param	Type	Description
`options.width`	`number`	Texture width
`options.height`	`number`	Texture height
`options.depth`	`number?`	Depth for 3D textures
`options.format`	`string`	GPU texture format (e.g., `'rgba8unorm'`)
`options.usage`	`string\|number`	`'render'`, `'texture'`, `'storage'`, `'copy-src'`, `'copy-dst'`. Pipe-separated.
`options.label`	`string?`	Debug label

texture.sampler(options?) → GPUSampler

Create or return a cached sampler.

Param	Type	Description
`options.filter`	`string?`	`'linear'` or `'nearest'` (default `'linear'`)
`options.wrap`	`string?`	`'repeat'`, `'clamp'`, `'mirror'` (default `'clamp-to-edge'`)

texture.release(id)

Destroy a managed texture.

vgpu.command — VGPUCommandManager

command.encoder(label?) → GPUCommandEncoder

Create a new command encoder.

command.submit(commandBuffers)

Submit one or more command buffers to the GPU queue.

command.dispatchCompute(options)

One-shot compute dispatch: creates encoder, runs pass, submits immediately.

Param	Type	Description
`options.pipeline`	`GPUComputePipeline`	Pipeline to use
`options.bindGroups`	`GPUBindGroup\|GPUBindGroup[]`	Bind group(s) — array sets group 0, 1, 2...
`options.workgroups`	`number\|number[]`	Workgroup count(s) [x, y?, z?]
`options.label`	`string?`	Debug label

command.copyBuffer(src, dst, srcOffset?, dstOffset?, size)

GPU-side buffer-to-buffer copy.

async command.readBuffer(buffer, offset?, size?) → Promise<ArrayBuffer>

Read GPU buffer contents back to CPU. Creates a staging buffer, copies, maps, and returns the data.

Lifecycle Methods

vgpu.beginFrame()

Mark the start of a frame. Resets per-frame stats counters.

vgpu.endFrame()

Mark the end of a frame. Finalizes per-frame profiling data.

vgpu.getStats() → Object

Returns comprehensive statistics: buffer counts/sizes, shader cache size, pipeline counts, texture counts, memory usage, and profiler data.

vgpu.destroy()

Release all managed resources (buffers, textures, pipelines) and destroy the GPU device.

Factory Methods (Lazy)

These create heavy modules on first call and return cached instances thereafter.

vgpu.getRenderGraph() → VGPURenderGraph

Automatic render pass scheduling and resource aliasing.

vgpu.getIndirectRenderer() → VGPUIndirectRenderer

GPU-driven indirect draw calls for large instance counts.

vgpu.getHiZCulling() → VGPUHiZCulling

Hierarchical-Z occlusion culling.

vgpu.getStreaming() → VGPUStreamingManager

Texture and mesh streaming with priority queues.

vgpu.getDebugDraw() → VGPUDebugDraw

Immediate-mode debug line and shape rendering (boxes, spheres, frustums, arrows).

Properties

Property	Type	Description
`vgpu.device`	`GPUDevice`	Underlying WebGPU device
`vgpu.queue`	`GPUQueue`	GPU command queue
`vgpu.adapter`	`GPUAdapter`	GPU adapter info
`vgpu.limits`	`Object`	Device limits (maxBufferSize, etc.)
`vgpu.features`	`Set`	Supported feature strings
`vgpu.capabilities`	`Object`	Full capability descriptor