class
render::GpuCommandBuffer
Contains a list of render API commands that can be queued for execution on the GPU.
User is allowed to populate the command buffer from any thread, ensuring render API command generation can be multi-threaded. Command buffers must always be created on the render thread. Same command buffer cannot be used on multiple threads simulateously without external synchronization.
Public
Methods
~GpuCommandBuffer
GetGpuDevice
Returns the GPU device the command buffer is created on.
GetQueueType
Returns the queue type that determines on which queue is the command buffer allowed to be submitted on, and which commands may be recorded.
SetName
Assigns an name to the command buffer, primarily used for easier debugging.
SetGpuParameterSet
Binds the parameters so that the following draw or dispatch call uses the provided parameters in their GPU programs.
The caller must ensure the provided parameters match the bound graphics/compute pipeline at the time of the draw/dispatch call.
SetDynamicBufferOffset
Applies an offset from which reads in a buffer should start in a GPU program.
This allows caller to quickly change buffer contents as seen by the shader, without having to rebind GPU program parameters. You should only call this after binding all parameter sets, as the offsets will be reset when parameters are changed.
- set
- Descriptor set index.
- bufferIndex
- Dynamic buffer index within the set, as retrieved from GpuPipelineParameterLayout::GetDynamicOffsetIndex.
- offset
- Offset to apply. Must be within the range of the currently bound buffer size and respect hardware alignment requirements.
SetGpuGraphicsPipelineState
Sets a pipeline state that controls how will subsequent draw commands render primitives.
SetGpuComputePipelineState
Sets a pipeline state that controls how will subsequent dispatch commands execute.
SetVertexBuffers
Sets the provided vertex buffers starting at the specified source index. Set buffer to nullptr to clear the buffer at the specified index.
- index
- Index at which to start binding the vertex buffers.
- buffers
- A list of buffers to bind to the pipeline.
- bufferCount
- Number of buffers in the list.
SetIndexBuffer
Sets an index buffer to use when drawing.
Indices in an index buffer reference vertices in the vertex buffer, which increases cache coherency and reduces the size of vertex buffers by eliminating duplicate data.
- buffer
- Index buffer to bind, null to unbind.
SetVertexDescription
Sets the description of vertex elements in the vertex buffers that will be bound when executing the vertex GPU program.
- vertexDescription
- Vertex description to bind.
SetDrawOperation
Sets the draw operation that determines how to interpret the elements of the index or vertex buffers.
- operation
- Draw operation to enable.
Draw
Draw an object based on currently bound GPU programs, vertex declaration and vertex buffers.
Draws directly from the vertex buffer without using indices.
- vertexOffset
- Offset into the currently bound vertex buffer to start drawing from.
- vertexCount
- Number of vertices to draw.
- instanceCount
- Number of times to draw the provided geometry, each time with an (optionally) separate per-instance data.
- firstInstance
- ID of the first instance to draw.
DrawIndexed
Draw an object based on currently bound GPU programs, vertex declaration, vertex and index buffers.
- startIndex
- Offset into the currently bound index buffer to start drawing from.
- indexCount
- Number of indices to draw.
- vertexOffset
- Offset to apply to each vertex index.
- vertexCount
- Number of vertices to draw.
- instanceCount
- Number of times to draw the provided geometry, each time with an (optionally) separate per-instance data.
- firstInstance
- ID of the first instance to draw.
DispatchCompute
Executes the currently bound compute shader.
- groupCountX
- Number of groups to start in the X direction. Must be in range [1, 65535].
- groupCountY
- Number of groups to start in the Y direction. Must be in range [1, 65535].
- groupCountZ
- Number of groups to start in the Z direction. Must be in range [1, 64].
BeginRenderPass
Begins a new render pass, allowing rendering commands to be recorded.
All resources referenced by the provided GPU parameters will be registered with the command buffer and necessary barriers/layout transitions will be issued before the render pass begins.
- createInformation
- Structure containing render target, masks, and all parameters that will be used during the render pass.
EndRenderPass
Ends the current render pass.
IsInRenderPass
Returns true if the command buffer is currently recording a render pass.
IssueBarriers
Issues a memory and/or execution barrier that guarantees that the contents of GPU buffers will be correctly visible for the provided destination stages.
Additionally, transitions the images to the correct layout to be used in the destination.
Note that system automatically issues barriers when needed, you do not need to call this method manually in almost all cases. Currently the only case you need to call this manually is when you read from a non-staging buffer that was written by the GPU, and you want to read the data on the CPU right after GPU execution completes.
SetViewport
Sets the active viewport that will be used for all following render operations.
- area
- Area of the viewport, in normalized ([0,1] range) coordinates.
ClearRenderTarget
Clears the currently active render target.
- mask
- Mask determining which surfaces of the render target to clear.
- color
- The color to clear the color buffer with, if enabled.
- depth
- The value to initialize the depth buffer with, if enabled.
- stencil
- The value to initialize the stencil buffer with, if enabled.
ClearViewport
Clears the currently active viewport (meaning it clears just a sub-area of a render-target that is covered by the viewport, as opposed to ClearRenderTarget() which always clears the entire render target).
- mask
- Mask determining which surfaces of the render target to clear.
- color
- The color to clear the color buffer with, if enabled.
- depth
- The value to initialize the depth buffer with, if enabled.
- stencil
- The value to initialize the stencil buffer with, if enabled.
EnableScissorTest
Allows you to set up a region in which rendering can take place.
Coordinates are in pixels. No rendering will be done to render target pixels outside of the provided region.
- left
- Left border of the scissor rectangle, in pixels.
- top
- Top border of the scissor rectangle, in pixels.
- right
- Right border of the scissor rectangle, in pixels.
- bottom
- Bottom border of the scissor rectangle, in pixels.
EnableScissorTest
Allows you to set up a region in which rendering can take place.
Coordinates are in pixels. No rendering will be done to render target pixels outside of the provided region.
DisableScissorTest
Disables scissor test set via EnableScissorTest().
SetStencilReferenceValue
Sets a reference value that will be used for stencil compare operations.
- value
- Reference value to set.
CopyBufferToBuffer
Copies the contents of the source buffer to the destination buffer.
Caller must ensure the provided offsets and length are within valid bounds of both buffers. Command buffer must not currently be in a render pass.
- source
- Source buffer to copy from.
- destination
- Destination buffer to copy to.
- sourceOffset
- Offset into the source buffer, from which to start copying, in bytes.
- destinationOffset
- Offset into the destination buffer, at which to place the copied data, in bytes.
- length
- Size of the data to copy, in bytes.
CopyBufferToTexture
Copies data from a buffer to a texture subresource.
The buffer must contain pixel data in the same format as the texture, accounting for the required row and depth pitch. Command buffer must not currently be in a render pass.
- source
- Source buffer containing pixel data.
- destination
- Destination texture to copy into.
- bufferOffset
- Offset into the source buffer, in bytes.
- mipLevel
- Destination mipmap level.
- arrayLayer
- Destination texture face (array slice or cubemap face).
CopyTextureToBuffer
Copies data from a texture subresource to a buffer.
The buffer must have enough space to receive all pixel data in the same format as the texture, accounting for the row and depth pitch. Command buffer must not currently be in a render pass.
- source
- Source texture to copy from.
- destination
- Destination buffer to receive pixel data.
- mipLevel
- Source mipmap level.
- arrayLayer
- Source texture face (array slice or cubemap face).
- bufferOffset
- Offset into the destination buffer, in bytes.
CopyTexture
Copies data between texture subresources without format conversion or scaling.
Both textures must have matching formats. For multisampled source textures copying to a non-multisampled destination, a resolve operation is performed. Command buffer must not currently be in a render pass.
- source
- Source texture to copy from.
- destination
- Destination texture to copy into.
- copyInformation
- Describes which subresources to copy and where.
BlitTexture
Copies data between texture subresources with optional format conversion and scaling.
Uses filtering when scaling. Does not support multisampled textures. Command buffer must not currently be in a render pass.
- source
- Source texture to copy from.
- destination
- Destination texture to copy into.
- blitInformation
- Describes which subresources to copy and where, including source/destination regions for scaling.
WriteTimestamp
Schedules the timestamp to be recorded in the command buffer.
The timestamp will record the time at which the command has been executed by the GPU. The timestamp will be written to the associated query pool, which should only be accessed when the query pool has resolved the query.
- query
- Query to use for referencing the recorded timestamp.
- queryPool
- Query pool that was created from.
BeginQuery
Schedules the query start in the command buffer.
The query will capture information about GPU execution depending on the query type. Query start operation must be followed by EndQuery(). If a query is started within a render pass, it must be ended within the same render pass. Queries can also be started outside of a render pass, in which case they should end outside of a render pass. The query results will be written to the associated query pool, which should only be accessed when the query pool has resolved the query.
- query
- Query to use for referencing the recorded data.
- queryPool
- Query pool that was created from.
- flags
- Flags used to control the query.
EndQuery
Records the timestamp when this particular command executes on the GPU.
- query
- Query to use for referencing the recorded data.
- queryPool
- Query pool that was created from.
ResetQueries
Resets the pool when the command buffer execution reaches this point.
After resetting the pool previously allocated queries are no longer valid, and new AllocateQuery() calls return queries from the start of the pool. Must be done outside of a render pass.
BeginLabel
Surrounds all following commands with the provided label, until EndLabel() is called.
This may be used by external tools for easier debugging.
EndLabel
Closes the label scope as provided by the previous call to BeginLabel().
InsertLabel
Inserts a label at the specified location in the command buffer.
This may be used by external tools for easier debugging.
End
Ends command recording on the command buffer and makes it ready for submission.
AddQueueSyncMask
Ensures that this command buffer will wait for work to finish on all queues specified in the provided mask, before the command buffer starts executing.
This value is utilized at the time the command buffer is submitted to a queue. Submissions on the same queue are automatically synchronized. The provided mask is OR-ed with existing mask.
For example if you are performing GPU buffer updates on the transfer (copy) queue, you usually need to wait for those transfers to finish before you start executing a command buffer that uses that buffer.
GetQueueSyncMask
Returns a mask containing all the queues the command buffer needs to wait on before executing.
See AddQueueSync.
BeginProfiling
Returns a profiler that can be used for profiling calls on this command buffer. results from GpuProfiler.
EndProfiling
Finishes profiling the command buffer.
Requested samples will be sent for resolve to GpuProfiler.
GetProfiler
Returns the currently active GPU profiler.
Only valid in-between Begin/EndProfiling calls.
Fields
OnDidComplete
Triggers when the command buffer finishes execution on the GPU. triggers on the thread that owns the command buffer (the thread the command buffer pool was created on).
OnDestroyed
Triggered just before a command buffer is about to be destroyed.
Provided parameter determines if the command buffer was ever submitted or not.
Internal
Methods
Protected
Constructors
GpuCommandBuffer
Methods
Cleanup
Performs internal cleanup of command buffer state without resetting the underlying API command buffer.
This is called by the owning pool during pool-level reset, which resets all command buffers together. Can also be called internally by individual command buffer Reset() implementations.
Cleanup includes:
- Resource tracker notifications and clearing
- Queue sync mask reset
- Event clearing (OnDidComplete, OnDestroyed)
Destroy
Destroys command buffer.
Command buffer must not be used after this is called.
IsDestroyed
Returns true if the command buffer has been destroyed.
EnsureValidThread
Reports an error if the current thread is not the thread associated with the object.