GraphicsAPI reference
Class CommandList
Namespace: MicroEngine.Graphics.Devices
Assembly: MicroEngine.Graphics.dll
Guide: The graphics device
A list of commands for one device, recorded on the render thread and validated here, in core, as it is recorded (before any backend sees it). Every violation throws at the call that causes it:
- a resource of another device: `ArgumentException`; a disposed one: `ObjectDisposedException`;
- wrong nesting (pass in a pass, draw or binding outside a pass, update inside a pass, recording after submit): `InvalidOperationException`;
- a pipeline whose attachment formats differ from the pass's, a draw without the bindings the pipeline needs, a range outside a buffer, sampling the pass's own colour target: `InvalidOperationException` or `ArgumentOutOfRangeException`;
- an undeclared capability (instancing): [GraphicsCapabilityException](/docs/api/microengine.graphics.devices.graphicscapabilityexception/).
Rules: commands execute in recording order (an update affects only draws recorded after it); bindings, pipeline, viewport and scissor are pass-scoped (each pass starts with none bound, the whole target as viewport and no scissor); uniform data persist for the rest of the list once set.
public sealed class CommandListInheritance
Constructors
CommandList(IGraphicsDevice)
Creates an empty list; backends call this from BeginCommands.
public CommandList(IGraphicsDevice device)Parameters
device IGraphicsDevice
Properties
Commands
The recorded commands (backend-facing).
public ReadOnlySpan<Command> Commands { get; }Property Value
Device
The device the list records for.
public IGraphicsDevice Device { get; }Property Value
IsInPass
True between BeginPass and EndPass.
public bool IsInPass { get; }Property Value
IsSubmitted
True once submitted; a submitted list cannot record or be submitted again.
public bool IsSubmitted { get; }Property Value
Methods
BeginPass(in PassDescription)
Begins a pass; resets bindings, viewport (whole target) and scissor (none).
public void BeginPass(in PassDescription pass)Parameters
pass PassDescription
Draw(int, int, int)
Draws vertexCount vertices from firstVertex.
public void Draw(int vertexCount, int firstVertex = 0, int instances = 1)Parameters
vertexCount int
firstVertex int
instances int
DrawIndexed(int, int, int, int)
Draws indexCount indices from firstIndex; each index plus baseVertex
selects a vertex. Index values are not validated (they live in device memory): an index that selects a vertex
outside the bound buffer is undefined behaviour (a tier-0 backend may throw at Submit).
public void DrawIndexed(int indexCount, int firstIndex = 0, int baseVertex = 0, int instances = 1)Parameters
indexCount int
firstIndex int
baseVertex int
instances int
EndPass()
Ends the current pass.
public void EndPass()Payload(in Command)
The data of an update or uniform command (backend-facing).
public ReadOnlySpan<byte> Payload(in Command command)Parameters
command Command
Returns
SetIndices(GpuBuffer, IndexSize)
Binds the index buffer.
public void SetIndices(GpuBuffer buffer, IndexSize size = IndexSize.Bits16)Parameters
buffer GpuBuffer
size IndexSize
SetPipeline(Pipeline)
Binds a pipeline; its colour and depth formats must equal the pass attachments’.
public void SetPipeline(Pipeline pipeline)Parameters
pipeline Pipeline
SetScissor(RectI?)
Sets the scissor in target pixels (absolute, independent of the viewport), clipped to the target; null = none. Clears ignore it.
public void SetScissor(RectI? scissor)Parameters
scissor RectI?
SetTexture(int, Texture, Sampler)
Binds a texture and sampler to a fragment slot. The pass’s own colour target cannot be sampled.
public void SetTexture(int slot, Texture texture, Sampler sampler)Parameters
slot int
texture Texture
sampler Sampler
SetUniforms(ShaderStage, int, ReadOnlySpan<byte>)
Pushes uniform data for a slot of a stage of the bound custom pipeline (built-in pipelines have none).
public void SetUniforms(ShaderStage stage, int slot, ReadOnlySpan<byte> data)Parameters
stage ShaderStage
slot int
data ReadOnlySpan<byte>
SetUniforms<T>(ShaderStage, int, in T)
Typed overload of SetUniforms: the bytes of data, as laid out in memory.
public void SetUniforms<T>(ShaderStage stage, int slot, in T data) where T : unmanagedParameters
stage ShaderStage
slot int
data T
Type Parameters
T
SetVertices(GpuBuffer)
Binds the vertex buffer (slot 0).
public void SetVertices(GpuBuffer buffer)Parameters
buffer GpuBuffer
SetViewport(in RectI)
Sets the viewport: built-in vertex positions are pixels relative to its origin, and it clips. Must lie inside the colour target.
public void SetViewport(in RectI viewport)Parameters
viewport RectI
UpdateBuffer(GpuBuffer, int, ReadOnlySpan<byte>)
Writes data into a buffer at offset, outside passes; draws recorded later see it.
public void UpdateBuffer(GpuBuffer buffer, int offset, ReadOnlySpan<byte> data)Parameters
buffer GpuBuffer
offset int
data ReadOnlySpan<byte>
UpdateBuffer<T>(GpuBuffer, int, ReadOnlySpan<T>)
Typed overload of UpdateBuffer.
public void UpdateBuffer<T>(GpuBuffer buffer, int offset, ReadOnlySpan<T> data) where T : unmanagedParameters
buffer GpuBuffer
offset int
data ReadOnlySpan<T>
Type Parameters
T
UpdateTexture(Texture, in RectI, ReadOnlySpan<byte>)
Writes tightly packed texel data into a region of mip level 0, outside passes.
public void UpdateTexture(Texture texture, in RectI region, ReadOnlySpan<byte> data)Parameters
texture Texture
region RectI
data ReadOnlySpan<byte>