VPP  0.7
A high-level modern C++ API for Vulkan
Public Member Functions | Static Public Member Functions | List of all members
vpp::ComputePass Class Reference

Represents compute pass. More...

#include <vppComputePass.hpp>

Inheritance diagram for vpp::ComputePass:
vpp::NonRenderingCommands vpp::UniversalCommands vpp::Computation

Public Member Functions

 ComputePass (const Device &hDevice)
 Construct a compute pass.
 
 ComputePass (const Device &hDevice, const PipelineCache &hPipelineCache)
 Construct a compute pass with user-supplied pipeline cache.
 
const Devicedevice () const
 Retrieves the device associated with this compute pass.
 
const PipelineCachepipelineCache () const
 Retrieves the pipeline cache associated with this compute pass.
 
const ComputePipelinepipeline (std::uint32_t iPipeline) const
 Retrieves a pipeline associated with this compute pass and specified pipeline index.
 
template<class DefinitionT >
std::uint32_t addPipeline (const ComputePipelineLayout< DefinitionT > layout)
 Registers a pipeline with this compute pass. Returns pipeline index.
 
void operator<< (const std::function< void() > &cmds)
 Defines a command sequence for compute pass.
 

Static Public Member Functions

static void cmdDispatch (unsigned int nx=1, unsigned int ny=1, unsigned int nz=1, CommandBuffer hCmdBuffer=CommandBuffer())
 Generates a command which starts execution of currently selected pipeline in the compute pass. More...
 
static void cmdDispatchIndirect (const IndirectBufferView &data, unsigned int index, CommandBuffer hCmdBuffer=CommandBuffer())
 Generates a command to dispatch specified item of indirect dispatch buffer. More...
 
- Static Public Member Functions inherited from vpp::NonRenderingCommands
static void cmdFillBuffer (const Buf &hDstBuffer, size_t offset, size_t size, std::uint32_t value, CommandBuffer hCmdBuffer=CommandBuffer())
 Fills specified buffer (or a region of it) with constant value.
 
static void cmdCopyBuffer (const Buf &hSrcBuffer, const Buf &hDstBuffer, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies entire contents from one buffer to another.
 
static void cmdCopyBuffer (const Buf &hSrcBuffer, const Buf &hDstBuffer, const std::vector< VkBufferCopy > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies a list of regions from one buffer to another.
 
static void cmdUpdateBuffer (const Buf &hDstBuffer, size_t offset, size_t size, const std::uint32_t *pData, CommandBuffer hCmdBuffer=CommandBuffer())
 Modifies a buffer region with specified data. More...
 
static void cmdCopyImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies entire contents from one image to another.
 
static void cmdCopyImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, const std::vector< VkImageCopy > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies a list of regions from one image to another.
 
static void cmdCopyBufferToImage (const Buf &hSrcBuffer, const Img &hDstImage, VkImageLayout dstImageLayout, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies entire contents from a buffer to an image.
 
static void cmdCopyBufferToImage (const Buf &hSrcBuffer, const Img &hDstImage, VkImageLayout dstImageLayout, const std::vector< VkBufferImageCopy > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies a list of regions from a buffer to an image.
 
static void cmdCopyImageToBuffer (const Img &hSrcImage, VkImageLayout srcImageLayout, const Buf &hDstBuffer, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies entire contents from an image to a buffer.
 
static void cmdCopyImageToBuffer (const Img &hSrcImage, VkImageLayout srcImageLayout, const Buf &hDstBuffer, const std::vector< VkBufferImageCopy > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies a list of regions from an image to a buffer.
 
static void cmdBlitImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, const VkOffset3D &srcBegin, const VkOffset3D &srcEnd, const VkOffset3D &dstBegin, const VkOffset3D &dstEnd, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies source image region into destination image, potentially performing format conversion, arbitrary scaling and filtering.
 
static void cmdBlitImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, const VkOffset3D &srcBegin, const VkOffset3D &srcEnd, const VkOffset3D &dstBegin, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies source image region into destination image, potentially performing format conversion, but no scaling.
 
static void cmdBlitImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, const std::vector< VkImageBlit > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Copies source image regions into destination image, potentially performing format conversion, arbitrary scaling and filtering.
 
static void cmdResolveImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, const VkOffset3D &srcOffset, const VkOffset3D &dstOffset, const VkExtent3D &size, CommandBuffer hCmdBuffer=CommandBuffer())
 Resolves source multisampled image region into destination regular image. More...
 
static void cmdResolveImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, CommandBuffer hCmdBuffer=CommandBuffer())
 Resolves source multisampled image into destination regular image. More...
 
static void cmdResolveImage (const Img &hSrcImage, VkImageLayout srcImageLayout, const Img &hDstImage, VkImageLayout dstImageLayout, const std::vector< VkImageResolve > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Resolves a list of source multisampled image regions into destination regular image regions. More...
 
static void cmdClearColorImage (const Img &hImage, VkImageLayout imageLayout, const VkClearColorValue &color, CommandBuffer hCmdBuffer=CommandBuffer())
 Clears an image with specified color.
 
static void cmdClearColorImage (const Img &hImage, VkImageLayout imageLayout, const VkClearColorValue &color, const std::vector< VkImageSubresourceRange > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Clears a list of regions in specified image with specified color.
 
static void cmdClearDepthStencilImage (const Img &hImage, VkImageLayout imageLayout, float depth, std::uint32_t stencil, CommandBuffer hCmdBuffer=CommandBuffer())
 Clears a depth or stencil image with specified value.
 
static void cmdClearDepthStencilImage (const Img &hImage, VkImageLayout imageLayout, float depth, std::uint32_t stencil, const std::vector< VkImageSubresourceRange > &regions, CommandBuffer hCmdBuffer=CommandBuffer())
 Clears a list of regions in depth or stencil image with specified value.
 
static void cmdResetQueryPool (const QueryPool &hPool, std::uint32_t first, std::uint32_t count, CommandBuffer hCmdBuffer=CommandBuffer())
 Resets a range of queries in a query pool.
 
static void cmdResetQueryPool (const QueryPool &hPool, CommandBuffer hCmdBuffer=CommandBuffer())
 Resets all queries in a query pool.
 
static void cmdCopyQueryPoolResults (const Buf &hDstBuffer, const QueryPool &hPool, VkQueryResultFlags flags, std::uint32_t count, std::uint32_t first, VkDeviceSize dstOffset, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdCopyQueryPoolResults (const Buf &hDstBuffer, const QueryPool &hPool, VkQueryResultFlags flags, CommandBuffer hCmdBuffer=CommandBuffer())
 
- Static Public Member Functions inherited from vpp::UniversalCommands
static void cmdExecuteCommands (const VkCommandBuffer *pBuffers, size_t size, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdExecuteCommands (const CommandBuffer *pBuffers, size_t size, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdExecuteCommands (const std::vector< CommandBuffer > &buffers, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdWaitEvents (const std::vector< Event > &events, VkPipelineStageFlags srcStageMask, VkPipelineStageFlags dstStageMask, const Barriers &barriers=Barriers(), CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdPipelineBarrier (VkPipelineStageFlags srcStageMask, VkPipelineStageFlags dstStageMask, VkDependencyFlags dependencyFlags, const Barriers &barriers, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdImagePipelineBarrier (const Img &image, VkPipelineStageFlags srcStageMask, VkPipelineStageFlags dstStageMask, VkAccessFlags srcAccessMask, VkAccessFlags dstAccessMask, bool bByRegion, VkImageLayout oldLayout=VK_IMAGE_LAYOUT_GENERAL, VkImageLayout newLayout=VK_IMAGE_LAYOUT_GENERAL, int mipLevel=-1, int arrayLayer=-1, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBufferPipelineBarrier (const Buf &hBuffer, VkPipelineStageFlags srcStageMask, VkPipelineStageFlags dstStageMask, VkAccessFlags srcAccessMask, VkAccessFlags dstAccessMask, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetViewport (const VkViewport &viewport, std::uint32_t index=0, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetViewport (const std::vector< VkViewport > &viewports, std::uint32_t first=0, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetLineWidth (float lineWidth, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetDepthBias (float constantFactor, float clamp, float slopeFactor, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetDepthBounds (float minDepthBounds, float maxDepthBounds, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetScissor (const VkRect2D &scissor, std::uint32_t index=0, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetScissor (const std::vector< VkRect2D > &scissors, std::uint32_t first=0, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetStencilCompareMask (VkStencilFaceFlags faceMask, std::uint32_t compareMask, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetStencilWriteMask (VkStencilFaceFlags faceMask, std::uint32_t writeMask, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetStencilReference (VkStencilFaceFlags faceMask, std::uint32_t reference, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdSetBlendConstants (const float blendConstants [4], CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBeginQuery (const QueryPool &hPool, std::uint32_t query, VkQueryControlFlags flags, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdEndQuery (const QueryPool &hPool, std::uint32_t query, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdWriteTimestamp (const QueryPool &hPool, std::uint32_t query, VkPipelineStageFlagBits pipelineStage, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBindPipeline (const Pipeline &hPipeline, VkPipelineBindPoint pipelineBindPoint, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBindDescriptorSets (const ShaderDataBlock &hDataBlock, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBindIndexInput (const Buf &hBuffer, VkIndexType indexType, VkDeviceSize offset, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBindVertexBuffers (const std::vector< Buf > &buffers, const std::vector< VkDeviceSize > &offsets, std::uint32_t first=0, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdBindVertexBuffers (const std::vector< Buf > &buffers, std::uint32_t first=0, CommandBuffer hCmdBuffer=CommandBuffer())
 
static void cmdPushConstants (const PipelineLayoutBase &hPipelineLayout, VkShaderStageFlags stageFlags, const void *pValues, std::uint32_t size, std::uint32_t offset=0, CommandBuffer hCmdBuffer=CommandBuffer())
 

Detailed Description

Represents compute pass.

A compute pass is a single pass in GPU computation. It defines a set of input, output and intermediate resources and executes one or more computing pipelines on it.

Compute pass is generally similar concept to render pass, but does not render any graphics, and has neither a render graph, nor frame buffer. It can however generate images, as all types of resources are allowed for compute passes.

Compute passes contain compute pipelines instead of rendering pipelines. Use the ComputePipelineLayout template to define a compute pipeline. There can be multiple pipelines per pass. They are selected in the same way as in render passes (cmdBind() method).

In VPP, the ComputePass class is usually used in conjunction with CommandBufferRecorder class. CommandBufferRecorder produces a command buffer from given ComputePass. This command buffer, when submitted to a queue, instructs the device to do actual computing.

The computation involves calling the compute shader repeatedly, like in a multi-level loop. Individual executions are parallelized, according to device capabilities. As there is usually more calls than physical compute units, some calls will be serialized also.

There are two main levels of looping during the computation - the local level and global level. Each of these levels is further divided into three sub-levels, which can represent three dimensions.

The global looping logically divides computation into workgroups. A workgroup is a computation unit that does not share fast communication memory with other workgroups. Partition your computation work in such way, that no such communication is needed (otherwise the performance will be low). Specifically, for most GPUs currently being on the market, different workgroups are usually executed on different cores on chip (e.g. CUs). Sometimes they can also be executed on same core in parallel, but that should not be relied upon. If there are more workgroups than physical units, they will be executed sequentially.

The local level divides each workgroup into local threads. Local threads within same workgroup have access to special memory block on GPU allowing faster exchange of data than main GPU memory. Local threads are intended to be executed on single core, in a SIMD scheme. If there is more local threads than SIMD channels, they will be serialized.

A conceptual pseudocode for computation in Vulkan model is as follows:

// { nx, ny, nz } - dimensions of entire problem (counted in workgroups)
// { ni, nj, nk } - dimensions of single workgroup (counted in threads)
// This is implicit code executed by Vulkan (it does not really exist).
// The loops are being iterated in parallel when possible.
void compute ( int nx, int ny, int nz, int ni, int nj, int nk )
{
// global level
for ( int x = 0; i < nx; ++x )
for ( int y = 0; y < ny; ++y )
for ( int z = 0; z < nz; ++z )
{
// local level
for ( int i = 0; i < ni; ++i )
for ( int j = 0; y < nj; ++j )
for ( int k = 0; k < nk; ++k )
{
// Schedule the call to computeShaderRoutine.
callComputeShader ( x, y, z, i, j, k );
}
}
}
// This is real GPU code that you write for the compute shader,
// usually as a method in your ComputePass subclass. It works as
// a callback routine.
void computeShaderRoutine ( vpp::ComputeShader* pShader )
{
VArray< Int, 8 > privateArray;
Shared(); VArray< Int, 8 > sharedArray;
const IVec3 workgroupId = pShader->inWorkgroupId;
const IVec3 localId = pShader->inLocalInvocationId;
// workgroupId == { x, y, z }
// threadId == { i, j, k }
// Retrieve input data for your computation according to
// the indices in workgroupId and localId.
// For each triple { i, j, k } under the same { x, y, z },
// this will alter the same item. However, for differing
// { x, y, z } there will be separate copies of sharedArray.
sharedArray [ 0 ] = 0;
// This will alter private copy for each call.
privateArray [ 0 ] = 0;
// This ensures all threads in same workgroup will meet here
// (even when executed sequentially).
}

Member Function Documentation

◆ cmdDispatch()

static void vpp::ComputePass::cmdDispatch ( unsigned int  nx = 1,
unsigned int  ny = 1,
unsigned int  nz = 1,
CommandBuffer  hCmdBuffer = CommandBuffer() 
)
static

Generates a command which starts execution of currently selected pipeline in the compute pass.

This is a counterpart of RenderGraph::cmdDraw() command. It triggers actual computation. Call it inside the command sequence (lambda function passed to the << operator). Before calling cmdDispatch(), also call cmdBind() methods on selected pipeline and shader data block which specifies current resource set.

The arguments nx, ny and nz specify (in three dimensions) how many times the compute shader will be called in separate workgroup.

The ni, nj and nk values (local workgroup dimensions) are not specified here, but rather in the constructor of compute shader binding point - see the computeShader class and SLocalSize structure.

The command will be generated into specified command buffer, or the default command buffer if omitted.

An example of using cmdDispatch():

class MyComputePass : public vpp::ComputePass
{
public:
private:
ComputePipelineLayout< MyPipeline0 > m_plStep0;
ComputePipelineLayout< MyPipeline1 > m_plStep1;
ShaderDataBlock m_myShaderDataBlock0;
ShaderDataBlock m_myShaderDataBlock1;
};
MyComputePass :: MyComputePass ( const Device& dev, ... ) :
m_plStep0 ( dev ),
m_plStep1 ( dev ),
m_myShaderDataBlock0 ( m_plStep0 ),
m_myShaderDataBlock1 ( m_plStep1 )
{
// constructor of your ComputePass subclass
// ...
// register and compile pipelines
const unsigned int ipl0 = addPipeline ( m_plStep0 );
const unsigned int ipl1 = addPipeline ( m_plStep1 );
// ...
// register the command sequence as a lambda function
(*this) << [ this, ipl0, ipl1 ]()
{
// select resources and pipeline for the computation step
m_myShaderDataBlock0.cmdBind();
// this retrieves compiled pipeline object for m_plStep0
pipeline ( ipl0 ).cmdBind();
// execute the computation step
cmdDispatch ( 64, 1, 1 );
// wait for the results
cmdImagePipelineBarrier (
m_myGeneratedImage0,
VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT,
VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT,
VK_ACCESS_SHADER_WRITE_BIT,
VK_ACCESS_SHADER_READ_BIT,
false
);
// select resources and pipeline for another computation step
m_myShaderDataBlock1.cmdBind();
// this retrieves compiled pipeline object for m_plStep1
pipeline ( ipl1 ).cmdBind();
// execute second computation step
cmdDispatch ( width, height, 1 );
}
}

◆ cmdDispatchIndirect()

static void vpp::ComputePass::cmdDispatchIndirect ( const IndirectBufferView data,
unsigned int  index,
CommandBuffer  hCmdBuffer = CommandBuffer() 
)
static

Generates a command to dispatch specified item of indirect dispatch buffer.

The indirect dispatch buffer contains parameters for implicit dispatch commands which are internally generated. The buffer should contain an array of VkDispatchIndirectCommand structures. One of possibilities is to use the DispatchIndirectCommands container class for it.

This command triggers execution of single dispatch element, specified by index in the buffer.

The command will be generated into specified command buffer, or the default command buffer if omitted.


The documentation for this class was generated from the following file: