tp::Job class

A job represents a single instance of work to be done on the device.

A job is created in a recording state, in which its methods can be called for recording commands and allocating resources. The job can then be enqueued to a device queue by calling tp::Device::enqueueJob, returning ownership of the handle and transitioning it to the enqueued state. To actually schedule the job for execution, tp::Device::submitQueuedJobs needs to be called, moving it to the submitted state.

Buffers, images and descriptor sets can be allocated for use within the job and the render and compute lists it executes. This allocation is handled by the parent tp::JobResourcePool and may be more efficient than a global allocation. These resources have a limited lifetime bound to the execution of the job and they may not be accessed outside of it.

Public functions

auto allocateLocalBuffer(const BufferSetup& setup, const char* debugName = nullptr) -> BufferView
Allocates a job-local buffer for use within this job.
auto allocateLocalDescriptorSet(const DescriptorSetLayout* descriptorSetLayout, ArrayParameter<const FutureDescriptor> descriptors, const char* debugName = nullptr) -> DescriptorSetView
Allocates a job-local descriptor set for use within this job.
auto allocateLocalImage(const ImageSetup& setup, const char* debugName = nullptr) -> ImageView
Allocates a job-local image for use within this job.
auto allocatePreinitializedBuffer(const BufferSetup& setup, const MemoryPreference& memoryPreference, const char* debugName = nullptr) -> BufferView
Allocates a preinitialized buffer for use within this job, with initial contents provided outside of it.
void cmdBeginDebugLabel(const char* name, ArrayParameter<const float> color = {})
Begins a debug label, marking the following commands until the next tp::Job::cmdEndDebugLabel with the given name and optional color for display in validation and debugging tools.
void cmdBlitImage(const ImageView& srcImage, const ImageView& dstImage, ArrayParameter<const ImageBlitRegion> blitRegions, Filter filter = Filter::Linear)
Copies regions of one image's contents to another, potentially performing format conversion, arbitrary scaling and filtering.
void cmdClearImage(const ImageView& dstImage, ClearValue value)
Clears contents of the image to a fixed value.
void cmdClearImage(const ImageView& dstImage, ClearValue value, ArrayParameter<const ImageSubresourceRange> ranges)
Clears ranges of contents of the image to a fixed value.
void cmdCopyBuffer(const BufferView& srcBuffer, const BufferView& dstBuffer, ArrayParameter<const BufferCopyRegion> copyRegions)
Copies regions of one buffer's contents to another.
void cmdCopyBufferToImage(const BufferView& srcBuffer, const ImageView& dstImage, ArrayParameter<const BufferImageCopyRegion> copyRegions)
Copies regions of a buffer's contents to an image.
void cmdCopyImage(const ImageView& srcImage, const ImageView& dstImage, ArrayParameter<const ImageCopyRegion> copyRegions)
Copies regions of one image's contents to another.
void cmdCopyImageToBuffer(const ImageView& srcImage, const BufferView& dstBuffer, ArrayParameter<const BufferImageCopyRegion> copyRegions)
Copies regions of an image's contents to a buffer.
void cmdDiscardContents(const ImageView& image)
Discards the contents of the image, making them undefined for future accesses. Doing this may potentially improve performance.
void cmdDiscardContents(const ImageView& image, ImageSubresourceRange range)
Discards the contents of the image range, making them undefined for future accesses. Doing this may potentially improve performance.
void cmdEndDebugLabel()
Ends the last debug label. Must be preceded by tp::Job::cmdBeginDebugLabel.
void cmdExecuteComputePass(const ComputePassSetup& setup, std::variant<ArrayView<ComputeList>, ComputeInlineCallback> commandRecording, const char* debugName = nullptr)
Forms a compute pass that executes lists of compute commands.
void cmdExecuteRenderPass(const RenderPassSetup& setup, std::variant<ArrayView<RenderList>, RenderInlineCallback> commandRecording, const char* debugName = nullptr)
Forms a render pass that executes lists of render commands.
void cmdExportResource(const BufferView& buffer, ReadAccessMask readAccessMask, QueueType targetQueueType = QueueType::Undefined)
Prepares a buffer for future read-only usages.
void cmdExportResource(const ImageView& image, const ImageSubresourceRange& range, ReadAccessMask readAccessMask, QueueType targetQueueType = QueueType::Undefined)
Prepares an image for future read-only usages.
void cmdExportResource(const ImageView& image, ReadAccessMask readAccessMask, QueueType targetQueueType = QueueType::Undefined)
Prepares an image for future read-only usages.
void cmdFillBuffer(const BufferView& dstBuffer, uint32_t value)
Fills the buffer with a fixed value.
void cmdInsertDebugLabel(const char* name, ArrayParameter<const float> color = {})
Inserts a debug label, marking the following commands with the given name and optional color for display in validation and debugging tools.
void cmdResolveImage(const ImageView& srcImage, const ImageView& dstImage, ArrayParameter<const ImageCopyRegion> resolveRegions)
Resolves regions of a multisampled color image to a single sample color image.
void cmdUpdateBuffer(const BufferView& dstBuffer, ArrayParameter<const std::byte> data)
Updates a range of the buffer's contents with the passed data.
void cmdWriteTimestamp(const TimestampQuery& query, PipelineStage stage)
Queries the time on the device as part of the given pipeline stage and writes the result to the provided query object.
auto createCommandPool(const char* debugName = nullptr) -> CommandPool*
Creates a command pool for use with tp::ComputeList and tp::RenderList within this job.
void vkCmdImportExternalResource(const BufferView& buffer, VkPipelineStageFlags vkStageMask, VkAccessFlags vkAccessMask)
Updates the internal synchronization state for the buffer view to the given external access.
void vkCmdImportExternalResource(const ImageView& image, const ImageSubresourceRange& range, VkImageLayout vkImageLayout, VkPipelineStageFlags vkStageMask, VkAccessFlags vkAccessMask)
Updates the internal synchronization state for the subresource range to the given external access.
void vkCmdImportExternalResource(const ImageView& image, VkImageLayout vkImageLayout, VkPipelineStageFlags vkStageMask, VkAccessFlags vkAccessMask)
Updates the internal synchronization state for the image view to the given external access.

Function documentation

BufferView tp::Job::allocateLocalBuffer(const BufferSetup& setup, const char* debugName = nullptr)

Allocates a job-local buffer for use within this job.

Parameters
setup The setup structure describing the object.
debugName The debug name identifier for the object.

DescriptorSetView tp::Job::allocateLocalDescriptorSet(const DescriptorSetLayout* descriptorSetLayout, ArrayParameter<const FutureDescriptor> descriptors, const char* debugName = nullptr)

Allocates a job-local descriptor set for use within this job.

Parameters
descriptorSetLayout The layout to be used for the descriptor set and also the layout of the provided descriptors.
descriptors The array of descriptors following the given layout. See tp::DescriptorSet for details.
debugName The debug name identifier for the object.

ImageView tp::Job::allocateLocalImage(const ImageSetup& setup, const char* debugName = nullptr)

Allocates a job-local image for use within this job.

Parameters
setup The setup structure describing the object.
debugName The debug name identifier for the object.

BufferView tp::Job::allocatePreinitializedBuffer(const BufferSetup& setup, const MemoryPreference& memoryPreference, const char* debugName = nullptr)

Allocates a preinitialized buffer for use within this job, with initial contents provided outside of it.

Parameters
setup The setup structure describing the object.
memoryPreference The memory preference progression that will be used for allocating memory for the object.
debugName The debug name identifier for the object.

void tp::Job::cmdBeginDebugLabel(const char* name, ArrayParameter<const float> color = {})

Begins a debug label, marking the following commands until the next tp::Job::cmdEndDebugLabel with the given name and optional color for display in validation and debugging tools.

Parameters
name The name of the label.
color The color of the label. Only used by external tools.

void tp::Job::cmdBlitImage(const ImageView& srcImage, const ImageView& dstImage, ArrayParameter<const ImageBlitRegion> blitRegions, Filter filter = Filter::Linear)

Copies regions of one image's contents to another, potentially performing format conversion, arbitrary scaling and filtering.

Parameters
srcImage The source image.
dstImage The destination image.
blitRegions An array specifying the regions to copy.
filter The filter to apply when scaling is involved.

void tp::Job::cmdClearImage(const ImageView& dstImage, ClearValue value)

Clears contents of the image to a fixed value.

Parameters
dstImage The destination image.
value The value that the image will be cleared to. It must be valid for the format of the image.

void tp::Job::cmdClearImage(const ImageView& dstImage, ClearValue value, ArrayParameter<const ImageSubresourceRange> ranges)

Clears ranges of contents of the image to a fixed value.

Parameters
dstImage The destination image.
value The value that the image will be cleared to. It must be valid for the format of the image.
ranges An array specifying the ranges of the image to clear.

void tp::Job::cmdCopyBuffer(const BufferView& srcBuffer, const BufferView& dstBuffer, ArrayParameter<const BufferCopyRegion> copyRegions)

Copies regions of one buffer's contents to another.

Parameters
srcBuffer The source buffer.
dstBuffer The destination buffer.
copyRegions An array specifying the regions to copy.

void tp::Job::cmdCopyBufferToImage(const BufferView& srcBuffer, const ImageView& dstImage, ArrayParameter<const BufferImageCopyRegion> copyRegions)

Copies regions of a buffer's contents to an image.

Parameters
srcBuffer The source buffer.
dstImage The destination image.
copyRegions An array specifying the regions to copy.

void tp::Job::cmdCopyImage(const ImageView& srcImage, const ImageView& dstImage, ArrayParameter<const ImageCopyRegion> copyRegions)

Copies regions of one image's contents to another.

Parameters
srcImage The source image.
dstImage The destination image.
copyRegions An array specifying the regions to copy.

void tp::Job::cmdCopyImageToBuffer(const ImageView& srcImage, const BufferView& dstBuffer, ArrayParameter<const BufferImageCopyRegion> copyRegions)

Copies regions of an image's contents to a buffer.

Parameters
srcImage The source image.
dstBuffer The destination buffer.
copyRegions An array specifying the regions to copy.

void tp::Job::cmdDiscardContents(const ImageView& image)

Discards the contents of the image, making them undefined for future accesses. Doing this may potentially improve performance.

Parameters
image The image with contents to be discarded.

void tp::Job::cmdDiscardContents(const ImageView& image, ImageSubresourceRange range)

Discards the contents of the image range, making them undefined for future accesses. Doing this may potentially improve performance.

Parameters
image The image with a range of contents to be discarded.
range The range of contents to be discarded.

void tp::Job::cmdEndDebugLabel()

Ends the last debug label. Must be preceded by tp::Job::cmdBeginDebugLabel.

void tp::Job::cmdExecuteComputePass(const ComputePassSetup& setup, std::variant<ArrayView<ComputeList>, ComputeInlineCallback> commandRecording, const char* debugName = nullptr)

Forms a compute pass that executes lists of compute commands.

Parameters
setup The setup structure describing the compute pass and its use of resources.
commandRecording

Describes how compute commands are to be recorded for the compute pass. The parameter can be either:

  • A non-empty array view of null tp::ComputeList objects that will be initialized by the function call. Commands can be recorded to these lists while the job is in an enqueued state. The lists are executed in the order they are in this array and lists with no recorded commands will be skipped.
  • A function callback to record commands to a tp::ComputeList that will be provided as its parameter. This function will be called as a part of the next tp::Device::submitQueuedJobs call after the job has been enqueued to the same queue.
debugName The debug name identifier for the compute pass.

void tp::Job::cmdExecuteRenderPass(const RenderPassSetup& setup, std::variant<ArrayView<RenderList>, RenderInlineCallback> commandRecording, const char* debugName = nullptr)

Forms a render pass that executes lists of render commands.

Parameters
setup The setup structure describing the render pass, its attachments and its non-attachment resource usage.
commandRecording

Describes how render commands are to be recorded for the render pass. The parameter can be either:

  • A non-empty array view of null tp::RenderList objects that will be initialized by the function call. Commands can be recorded to these lists while the job is in an enqueued state. The lists are executed in the order they are in this array and lists with no recorded commands will be skipped.
  • A function callback to record commands to a tp::RenderList that will be provided as its parameter. This function will be called as a part of the next tp::Device::submitQueuedJobs call after the job has been enqueued to the same queue.
debugName The debug name identifier for the render pass.

void tp::Job::cmdExportResource(const BufferView& buffer, ReadAccessMask readAccessMask, QueueType targetQueueType = QueueType::Undefined)

Prepares a buffer for future read-only usages.

Parameters
buffer The buffer to be exported.
readAccessMask The mask of future read-only accesses.
targetQueueType If not tp::QueueType::Undefined, the resource is made accessible to all of the queues of the given type.

Makes the results of all previous accesses of the resource in this queue visible to the specified future read accesses in all queues of the target queue type. Any future access besides the one specified invalidates the export on the accessed range.

While synchronization and memory visibility is handled automatically between commands recorded to jobs in the same queue, exporting a resource is still useful for the following reasons:

  • Render and compute passes have to explicitly declare any accesses of resources that weren't previously exported.
  • If targetQueueType is not tp::QueueType::Undefined, the export operation additionally makes the resource accessible to all of the queues of the given type.
  • To read back data from the device, the resource has to be exported with readAccessMask that contains tp::ReadAccess::Host.
  • It reveals the future intended usage to the library beyond the scope of this job, allowing for potentially more efficient placement of Vulkan pipeline barriers.

void tp::Job::cmdExportResource(const ImageView& image, const ImageSubresourceRange& range, ReadAccessMask readAccessMask, QueueType targetQueueType = QueueType::Undefined)

Prepares an image for future read-only usages.

Parameters
image The image containing the range to be exported.
range The image subresource range to be exported.
readAccessMask The mask of future read-only accesses.
targetQueueType If not tp::QueueType::Undefined, the resource is made accessible to all of the queues of the given type.

void tp::Job::cmdExportResource(const ImageView& image, ReadAccessMask readAccessMask, QueueType targetQueueType = QueueType::Undefined)

Prepares an image for future read-only usages.

Parameters
image The image to be exported.
readAccessMask The mask of future read-only accesses.
targetQueueType If not tp::QueueType::Undefined, the resource is made accessible to all of the queues of the given type.

void tp::Job::cmdFillBuffer(const BufferView& dstBuffer, uint32_t value)

Fills the buffer with a fixed value.

Parameters
dstBuffer The buffer to be filled.
value The 4-byte word written repeatedly to fill the given buffer.

void tp::Job::cmdInsertDebugLabel(const char* name, ArrayParameter<const float> color = {})

Inserts a debug label, marking the following commands with the given name and optional color for display in validation and debugging tools.

Parameters
name The name of the label.
color The color of the label. Only used by external tools.

void tp::Job::cmdResolveImage(const ImageView& srcImage, const ImageView& dstImage, ArrayParameter<const ImageCopyRegion> resolveRegions)

Resolves regions of a multisampled color image to a single sample color image.

Parameters
srcImage The source multisampled image.
dstImage The destination image.
resolveRegions An array specifying the regions to resolve.

void tp::Job::cmdUpdateBuffer(const BufferView& dstBuffer, ArrayParameter<const std::byte> data)

Updates a range of the buffer's contents with the passed data.

Parameters
dstBuffer The buffer with contents to be updated.
data The data to update. The length of the array defines the size of the range to be updated.

void tp::Job::cmdWriteTimestamp(const TimestampQuery& query, PipelineStage stage)

Queries the time on the device as part of the given pipeline stage and writes the result to the provided query object.

Parameters
query The timestamp query object that the result will be written to.
stage The pipeline stage at which the timestamp should be measured. This means a time point at which all the previously submitted commands have finished executing the given pipeline stage.

CommandPool* tp::Job::createCommandPool(const char* debugName = nullptr)

Creates a command pool for use with tp::ComputeList and tp::RenderList within this job.

Parameters
debugName The debug name identifier for the object.

void tp::Job::vkCmdImportExternalResource(const BufferView& buffer, VkPipelineStageFlags vkStageMask, VkAccessFlags vkAccessMask)

Updates the internal synchronization state for the buffer view to the given external access.

Parameters
buffer The buffer to be imported.
vkStageMask The Vulkan pipeline stage mask of the external access.
vkAccessMask The Vulkan access mask of the external access.

This should be used after a resource has been accessed by an operation done outside of Tephra and before it is accessed by a Tephra command again. This command allows those future Tephra accesses to be synchronized against the external access properly.

void tp::Job::vkCmdImportExternalResource(const ImageView& image, const ImageSubresourceRange& range, VkImageLayout vkImageLayout, VkPipelineStageFlags vkStageMask, VkAccessFlags vkAccessMask)

Updates the internal synchronization state for the subresource range to the given external access.

Parameters
image The image to be imported.
range The affected subresource range.
vkImageLayout The Vulkan image layout that the image subresource is transitioned to by the external access.
vkStageMask The Vulkan pipeline stage mask of the external access.
vkAccessMask The Vulkan access mask of the external access.

void tp::Job::vkCmdImportExternalResource(const ImageView& image, VkImageLayout vkImageLayout, VkPipelineStageFlags vkStageMask, VkAccessFlags vkAccessMask)

Updates the internal synchronization state for the image view to the given external access.

Parameters
image The image to be imported.
vkImageLayout The Vulkan image layout that the image subresource is transitioned to by the external access.
vkStageMask The Vulkan pipeline stage mask of the external access.
vkAccessMask The Vulkan access mask of the external access.