Future follow-up, not part of the current vNext API iteration. Issue #320 keeps only f.raw() as its low-level command-encoder escape hatch. This issue records a possible target-aware raw render-pass API for a later version, after concrete usage justifies it.

Future API: target-aware f.rawPass() escape hatch

Motivation

f.raw() provides complete access to the frame's GPUCommandEncoder, but creating a native render pass through it requires callers to reconstruct vgpu-managed presentation details: the current surface texture/view, depth attachment, MSAA attachment and resolve target, plus load/store behavior.

A future f.rawPass() could preserve that target/attachment convenience while giving the caller full ownership of commands inside the render pass. It would cover advanced integration cases without exposing a raw encoder inside a cache-managed f.pass().

Possible API

frame(gpu, (f) => {
  f.rawPass(
    {
      target: screen,
      clear: [0, 0, 0, 1],
    },
    (pass) => {
      pass.setPipeline(prepared.gpu);
      pass.setBindGroup(0, customBindings);
      pass.setVertexBuffer(0, vertices);
      pass.drawIndexedIndirect(argumentsBuffer, 0);
    },
  );
});

Ownership contract

• vgpu owns the frame GPUCommandEncoder, resolves the Surface/Target attachments, begins and ends the render pass, and performs the frame submit.
• The callback owns all render state and commands inside that pass. vgpu performs no pipeline/bind-group/vertex-state caching there.
• The callback receives a borrowed render-pass encoder and must not retain it, end it, or return a promise.
• Managed p.draw() calls and arbitrary raw commands are not interleaved inside one cache-managed pass. There is no p.raw() in this proposal.
• f.rawPass() remains ordered with compute, copies and other passes encoded through the same frame and does not submit independently.

Intended use cases

• Integrating an external renderer that already encodes into a GPURenderPassEncoder.
• Using WebGPU functionality not yet modeled by vgpu, such as specialized indirect drawing, query workflows or custom native pipelines.
• Gradually adopting vgpu frame/surface management around an existing low-level renderer.

Non-goals

• This is not part of the API selected in #320 and should not block that iteration.
• It is not a performance promise, a worker-transfer mechanism, or a way to bypass WebGPU validation.
• It does not introduce cache-preservation flags or shared ownership of render-pass state.

Before adopting

Require concrete examples showing that f.raw() plus raw resource access is materially too verbose. Then settle the exact name, borrowed-encoder type, attachment overrides, error semantics and interaction with device loss before adding the API.