vgpu/coreAdvanced3 symbolsView source ↗

Symbols in this topic

createRenderBundlefunctionRenderBundleOptionsoptionsRenderBundleRecordertype

createRenderBundle

Low-level render bundle helper around GPUDevice.createRenderBundleEncoder. Prefer main API (vgpu) bundle(gpu, { target }, cb) when recording main API (vgpu) Draw/Effect commands because it derives formats from Target and performs stale-bundle checks (VGPU-R3-BUNDLE-STALE).

Import

TypeScript
1
2
import { createRenderBundle, RenderBundleRecorder } from "vgpu/core";
import type { RenderBundleOptions } from "vgpu/core";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import type { Buffer } from "vgpu/core";
 
declare interface RenderPassDrawOptions {
  readonly vertexCount: number;
  readonly instanceCount?: number;
  readonly firstVertex?: number;
  readonly firstInstance?: number;
}
 
type RenderPassDynamicOffsets = readonly GPUBufferDynamicOffset[] | Uint32Array;
 
declare interface RenderBundleOptions {
  readonly label?: string;
  readonly colorFormats: readonly (GPUTextureFormat | null)[];
  readonly depthStencilFormat?: GPUTextureFormat;
  readonly sampleCount?: number;
  readonly depthReadOnly?: boolean;
  readonly stencilReadOnly?: boolean;
  readonly record: (bundle: RenderBundleRecorder) => void;
}
 
declare class RenderBundleRecorder {
  readonly gpu: GPURenderBundleEncoder;
  constructor(gpu: GPURenderBundleEncoder);
  setPipeline(pipeline: GPURenderPipeline): void;
  setBindGroup(index: number, group: GPUBindGroup | null, dynamicOffsets?: RenderPassDynamicOffsets): void;
  setVertexBuffer(slot: number, buffer: Buffer | GPUBuffer | null, offset?: number, size?: GPUSize64): void;
  draw(options: RenderPassDrawOptions): void;
  draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
}
 
declare function createRenderBundle(device: { readonly gpu: GPUDevice }, opts: RenderBundleOptions): GPURenderBundle;

Parameters

ParamTypeRequiredDefaultNotes
device{ readonly gpu: GPUDevice }✔—Core Device or any wrapper exposing a native GPUDevice as .gpu.
optsRenderBundleOptions✔—Native render bundle encoder options plus callback.
opts.labelstring✖undefinedPassed to createRenderBundleEncoder and finish.
opts.colorFormatsreadonly (GPUTextureFormat | null)[]✔—Must match the render pass where the bundle will execute.
opts.depthStencilFormatGPUTextureFormat✖undefinedRequired when the replay pass has depth/stencil.
opts.sampleCountnumber✖WebGPU encoder default (1)Must match replay pass sample count. main API (vgpu) passes target.sampleCount.
opts.depthReadOnlyboolean✖undefinedForwarded to WebGPU encoder descriptor.
opts.stencilReadOnlyboolean✖undefinedForwarded to WebGPU encoder descriptor.
opts.record(bundle: RenderBundleRecorder) => void✔—Called synchronously before encoder.finish().
recorder.setPipeline.pipelineGPURenderPipeline✔—Native pipeline compatible with bundle formats.
recorder.setBindGroup.indexnumber✔—Bind group slot.
recorder.setBindGroup.groupGPUBindGroup | null✔—Native bind group or null.
recorder.setBindGroup.dynamicOffsetsreadonly GPUBufferDynamicOffset[] | Uint32Array✖undefinedForwarded to setBindGroup.
recorder.setVertexBuffer.slotnumber✔—Vertex buffer slot.
recorder.setVertexBuffer.bufferBuffer | GPUBuffer | null✔—Core Buffer is unwrapped to .gpu; native buffer and null pass through.
recorder.setVertexBuffer.offsetnumber✖0Byte offset.
recorder.setVertexBuffer.sizeGPUSize64✖undefinedByte size.
recorder.draw.options.vertexCountnumber✔—Object overload vertex count.
recorder.draw.options.instanceCountnumber✖1Object overload instance count.
recorder.draw.options.firstVertexnumber✖0Object overload first vertex.
recorder.draw.options.firstInstancenumber✖0Object overload first instance.

Returns: createRenderBundle() returns GPURenderBundle; recorder methods return void.

Throws: No custom VGPU-* errors are thrown here. Native WebGPU validation errors occur for incompatible formats, pipelines, bind groups, buffers, or draw parameters. main API (vgpu) stale errors (VGPU-R3-BUNDLE-STALE, VGPU-R3-BUNDLE-INVALID) are available only through bundle(gpu) / FramePass.bundles().

Examples

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
import { init } from "vgpu/mock";
import { createRenderBundle } from "vgpu/core";
 
const gpu = await init();
const bundle = createRenderBundle(gpu.device, {
  label: "empty",
  colorFormats: ["rgba8unorm"],
  sampleCount: 1,
  record(recorder) {
    void recorder;
  },
});
void bundle;
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { init, target } from "vgpu/mock";
import { createRenderBundle } from "vgpu/core";
 
const gpu = await init();
const colorTarget = target(gpu, { size: [16, 16] });
const bundle = createRenderBundle(gpu.device, {
  colorFormats: colorTarget.colors.map((color) => color.format),
  depthStencilFormat: colorTarget.depth?.format,
  sampleCount: colorTarget.sampleCount,
  record(recorder) {
    recorder.draw({ vertexCount: 0, instanceCount: 0 });
  },
});
void bundle;

Notes

  • This helper intentionally does not know about main API (vgpu) Draw, Effect, or Target; you must supply formats and native commands yourself.
  • Use bundle(gpu) for public API examples unless you are already managing native pipelines.
  • RenderBundleRecorder.draw(number, ...) defaults to (instanceCount=1, firstVertex=0, firstInstance=0); object overload has the same defaults.
  • See also: Bundle, FramePass.bundles, Draw, Target.