Skip to main content

CommandEncoder

A CommandEncoder records GPU commands that can later be sealed into a CommandBuffer and submitted to a Device.

For conceptual guidance, start with GPU Commands.

Types​

CommandEncoderProps​

CommandEncoderProps extends ResourceProps.

PropertyTypeDefaultDescription
id?stringautogeneratedOptional human-readable label used for debugging.
handle?unknownundefinedSupply an existing backend handle instead of letting luma.gl create one.
userData?Record<string, unknown>undefinedApplication data stored on the encoder wrapper.
timeProfilingQuerySet?QuerySet | nullnullQuery set used for automatic pass-level GPU timestamp profiling.
measureExecutionTime?booleanbackend defaultReserved backend-specific hint for timing instrumentation.

Usage​

Record explicit copy work:

const commandEncoder = device.createCommandEncoder();

commandEncoder.copyBufferToBuffer({
  sourceBuffer,
  destinationBuffer,
  size: sourceBuffer.byteLength
});

const commandBuffer = commandEncoder.finish();
device.submit(commandBuffer);

Record a render pass:

const commandEncoder = device.createCommandEncoder();
const renderPass = commandEncoder.beginRenderPass({
  framebuffer,
  clearColor: [0, 0, 0, 1]
});

model.draw(renderPass);
renderPass.end();

device.submit(commandEncoder.finish());

Use the device's default encoder:

const renderPass = device.beginRenderPass({clearColor: [0, 0, 0, 1]});
model.draw(renderPass);
renderPass.end();
device.submit();

Members​

  • device: Device - holds a reference to the Device that created this CommandEncoder.
  • handle: unknown - holds the underlying WebGL or WebGPU command encoder handle
  • props: CommandEncoderProps - holds a copy of the CommandEncoderProps used to create this CommandEncoder.

Methods​

constructor(props: CommandEncoderProps)​

CommandEncoder is an abstract class and cannot be instantiated directly. Create with device.createCommandEncoder(...).

finish(props?: CommandBufferProps): CommandBuffer​

Completes recording and returns a finished CommandBuffer.

beginRenderPass(props?: RenderPassProps): RenderPass​

Begins a render pass recorded on this encoder.

beginComputePass(props?: ComputePassProps): ComputePass​

Begins a compute pass recorded on this encoder.

copyBufferToBuffer(options)​

Copies data from one GPU buffer to another.

copyBufferToTexture(options)​

Copies data from a GPU buffer into a texture subresource.

copyTextureToBuffer(options)​

Copies data from a texture subresource into a GPU buffer.

copyTextureToTexture(options)​

Copies one texture region into another texture region.

resolveQuerySet(querySet, destination, options?)​

Resolves query results into a GPU buffer.

writeTimestamp(querySet, queryIndex)​

Writes a timestamp into a QuerySet.

Remarks​

  • On WebGPU, commands are truly recorded onto the encoder and only execute after submit().
  • On WebGL, luma.gl provides a best-effort compatibility layer. Copy operations are portable, but render passes remain effectively immediate-mode.
  • If you do not need explicit command-stream control, the resource-level helpers such as Buffer.write(), Texture.writeData(), and Texture.copyExternalImage() are often the simpler choice.