tp::Device class

Represents a connection to a tp::PhysicalDevice, through which its functionality can be accessed.

A device object is the main means of interacting with the actual device on the platform. Through it most other objects in Tephra are created. Such objects can only be used with this device and other objects created from it. The device also provides the means to submit work to the device, by enqueueing tp::Job objects to a particular tp::DeviceQueue with tp::Device::enqueueJob and then submitting them for execution with tp::Device::submitQueuedJobs.

Base classes

class Ownable
A customizable base class that is used for objects returned by the API in an OwningPtr.

Public functions

void addCleanupCallback(CleanupCallback callback)
Stores a function that will be called after all currently enqueued or submitted jobs have finished executing on the device, allowing it to free external resources that were used up until this point in time.
auto allocateBuffer(const BufferSetup& setup, const MemoryPreference& memoryPreference, const char* debugName = nullptr) -> OwningPtr<Buffer>
Creates a tp::Buffer object according to the given setup structure and allocates memory for it according to the memory preference.
auto allocateImage(const ImageSetup& setup, const char* debugName = nullptr) -> OwningPtr<Image>
Creates a tp::Image object according to the given setup structure and allocates memory for it.
void compileComputePipelines(ArrayParameter<const ComputePipelineSetup*const> pipelineSetups, const PipelineCache* pipelineCache, ArrayParameter<Pipeline*const> compiledPipelines)
Batch compiles multiple compute tp::Pipeline objects.
void compileGraphicsPipelines(ArrayParameter<const GraphicsPipelineSetup*const> pipelineSetups, const PipelineCache* pipelineCache, ArrayParameter<Pipeline*const> compiledPipelines)
Batch compiles multiple graphics tp::Pipeline objects.
auto createDescriptorPool(const DescriptorPoolSetup& setup, const char* debugName = nullptr) -> OwningPtr<DescriptorPool>
Creates a tp::DescriptorPool object according to the given setup structure.
auto createDescriptorSetLayout(ArrayParameter<const DescriptorBinding> descriptorBindings, const char* debugName = nullptr) -> DescriptorSetLayout
Creates a tp::DescriptorSetLayout object from the given bindings.
auto createJobResourcePool(const JobResourcePoolSetup& setup, const char* debugName = nullptr) -> OwningPtr<JobResourcePool>
Creates a tp::JobResourcePool object according to the given setup structure.
auto createPipelineCache(ArrayParameter<const std::byte> data = {}) -> PipelineCache
Creates a tp::PipelineCache object.
auto createPipelineLayout(ArrayParameter<const DescriptorSetLayout*const> descriptorSetLayouts, ArrayParameter<const PushConstantRange> pushConstantRanges = {}, const char* debugName = nullptr) -> PipelineLayout
Creates a tp::PipelineLayout object from the given descriptor set and push constant layouts.
void createRenderQueries(ArrayParameter<const RenderQueryType> queryTypes, ArrayParameter<RenderQuery*const> queries)
Creates multiple tp::RenderQuery objects.
auto createSampler(const SamplerSetup& setup, const char* debugName = nullptr) -> Sampler
Creates a tp::Sampler object according to the given setup structure.
auto createShaderModule(ArrayParameter<const uint32_t> shaderCode, const char* debugName = nullptr) -> ShaderModule
Creates a tp::ShaderModule object out of the given SPIR-V shader code.
auto createSwapchainKHR(const SwapchainSetup& setup, Swapchain* oldSwapchain = nullptr, const char* debugName = nullptr) -> OwningPtr<Swapchain>
Creates a tp::Swapchain object according to the given setup structure.
void createTimestampQueries(ArrayParameter<TimestampQuery*const> queries)
Creates multiple tp::TimestampQuery objects.
auto enqueueJob(const DeviceQueue& queue, Job job, ArrayParameter<const JobSemaphore> waitJobSemaphores = {}, ArrayParameter<const ExternalSemaphore> waitExternalSemaphores = {}, ArrayParameter<const ExternalSemaphore> signalExternalSemaphores = {}) -> JobSemaphore
Enqueues the given tp::Job to the specified queue, creating and initializing its local resources.
auto getMemoryHeapStatistics(uint32_t memoryHeapIndex) const -> MemoryHeapStatistics
Returns the statistics for the Vulkan memory heap with the given index.
auto isJobSemaphoreSignalled(const JobSemaphore& semaphore) -> bool
Returns true if the given tp::JobSemaphore has been signalled, meaning the job has finished executing on the device.
auto mergePipelineCaches(ArrayParameter<const PipelineCache*const> srcCaches) -> PipelineCache
Creates a new tp::PipelineCache object by merging together multiple existing tp::PipelineCache objects.
void submitPresentImagesKHR(const DeviceQueue& queue, ArrayParameter<Swapchain*const> swapchains, ArrayParameter<const uint32_t> imageIndices)
Submits a present operation to the specified queue for each of the given tp::Swapchain objects, queueing the given acquired image from each swapchain for presentation.
void submitQueuedJobs(const DeviceQueue& queue, const JobSemaphore& lastJobToSubmit = {}, ArrayParameter<const JobSemaphore> waitJobSemaphores = {}, ArrayParameter<const ExternalSemaphore> waitExternalSemaphores = {})
Submits all tp::Job objects previously enqueued to the specified queue and schedules them to be executed on the device.
void updateDeviceProgress()
Updates the status of job semaphores, retrieves query results, triggers the freeing of resources and calls cleanup callbacks for any jobs that have finished executing since the last update.
auto vkCreateExternalBuffer(const BufferSetup& setup, Lifeguard<VkBufferHandle>&& bufferHandle, Lifeguard<VmaAllocationHandle>&& memoryAllocationHandle, const char* debugName = nullptr) -> OwningPtr<Buffer>
Creates a tp::Buffer object out of a raw Vulkan buffer handle and an optional VMA memory allocation handle.
auto vkCreateExternalImage(const ImageSetup& setup, Lifeguard<VkImageHandle>&& imageHandle, Lifeguard<VmaAllocationHandle>&& memoryAllocationHandle, const char* debugName = nullptr) -> OwningPtr<Image>
Creates a tp::Image object out of a raw Vulkan image handle and an optional VMA memory allocation handle.
auto vkGetDeviceHandle() const -> VkDeviceHandle
Returns the Vulkan VkDevice handle.
auto vkGetQueueHandle(const DeviceQueue& queue) const -> VkQueueHandle
Returns the Vulkan VkQueue handle associated with the given tp::DeviceQueue.
auto vkLoadDeviceProcedure(const char* procedureName) const -> PFN_vkVoidFunction
Loads a Vulkan device procedure with the given name and returns a pointer to it, or nullptr if not successful.
template<typename TypedHandle>
auto vkMakeHandleLifeguard(TypedHandle vkHandle) -> Lifeguard<TypedHandle>
Wraps the given Vulkan handle object in an owning tp::Lifeguard, ensuring its safe deletion after the lifeguard gets destroyed. Example usage: device->vkMakeHandleLifeguard(VkImageHandle(vkImage))
auto vmaGetAllocatorHandle() const -> VmaAllocatorHandle
Returns the VMA <a href='https://gpuopen-librariesandsdks.github.io/VulkanMemoryAllocator/html/struct_vma_allocator.html">VmaAllocator handle.
void waitForIdle()
Waits until the device becomes idle. It guarantees that all submitted jobs have finished executing and their corresponding semaphores have been signalled.
auto waitForJobSemaphores(ArrayParameter<const JobSemaphore> semaphores, bool waitAll = true, Timeout timeout = Timeout::Indefinite()) -> bool
Waits until the given tp::JobSemaphore handles have been signalled or until the timeout has been reached.

Function documentation

void tp::Device::addCleanupCallback(CleanupCallback callback)

Stores a function that will be called after all currently enqueued or submitted jobs have finished executing on the device, allowing it to free external resources that were used up until this point in time.

Parameters
callback The function to be called.

OwningPtr<Buffer> tp::Device::allocateBuffer(const BufferSetup& setup, const MemoryPreference& memoryPreference, const char* debugName = nullptr)

Creates a tp::Buffer object according to the given setup structure and allocates memory for it according to the memory preference.

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.

OwningPtr<Image> tp::Device::allocateImage(const ImageSetup& setup, const char* debugName = nullptr)

Creates a tp::Image object according to the given setup structure and allocates memory for it.

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

void tp::Device::compileComputePipelines(ArrayParameter<const ComputePipelineSetup*const> pipelineSetups, const PipelineCache* pipelineCache, ArrayParameter<Pipeline*const> compiledPipelines)

Batch compiles multiple compute tp::Pipeline objects.

Parameters
pipelineSetups The setup structures describing the compute pipelines that are to be compiled.
pipelineCache The tp::PipelineCache object to be used to accelerate the compilation, can be nullptr.
compiledPipelines An output array of pointers to tp::Pipeline objects that will represent the compiled pipelines. The size of this array must match the size of pipelineSetups and all of the elements must point be valid pointers.

void tp::Device::compileGraphicsPipelines(ArrayParameter<const GraphicsPipelineSetup*const> pipelineSetups, const PipelineCache* pipelineCache, ArrayParameter<Pipeline*const> compiledPipelines)

Batch compiles multiple graphics tp::Pipeline objects.

Parameters
pipelineSetups The setup structures describing the graphics pipelines that are to be compiled.
pipelineCache The tp::PipelineCache object to be used to accelerate the compilation, can be nullptr.
compiledPipelines An output array of pointers to tp::Pipeline objects that will represent the compiled pipelines. The size of this array must match the size of pipelineSetups and all of the elements must point be valid pointers.

OwningPtr<DescriptorPool> tp::Device::createDescriptorPool(const DescriptorPoolSetup& setup, const char* debugName = nullptr)

Creates a tp::DescriptorPool object according to the given setup structure.

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

DescriptorSetLayout tp::Device::createDescriptorSetLayout(ArrayParameter<const DescriptorBinding> descriptorBindings, const char* debugName = nullptr)

Creates a tp::DescriptorSetLayout object from the given bindings.

Parameters
descriptorBindings The descriptor bindings that define the layout.
debugName The debug name identifier for the object.

OwningPtr<JobResourcePool> tp::Device::createJobResourcePool(const JobResourcePoolSetup& setup, const char* debugName = nullptr)

Creates a tp::JobResourcePool object according to the given setup structure.

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

PipelineCache tp::Device::createPipelineCache(ArrayParameter<const std::byte> data = {})

Creates a tp::PipelineCache object.

Parameters
data An optional parameter specifying the source binary data that the tp::PipelineCache should be initialized to. This data would previously come from tp::PipelineCache::getData.

PipelineLayout tp::Device::createPipelineLayout(ArrayParameter<const DescriptorSetLayout*const> descriptorSetLayouts, ArrayParameter<const PushConstantRange> pushConstantRanges = {}, const char* debugName = nullptr)

Creates a tp::PipelineLayout object from the given descriptor set and push constant layouts.

Parameters
descriptorSetLayouts An array describing the layout of descriptor sets that will be accessed by the pipelines and that will need to be bound to each set number.
pushConstantRanges The layout of push constants that will be accessed by the pipelines.
debugName The debug name identifier for the object.

void tp::Device::createRenderQueries(ArrayParameter<const RenderQueryType> queryTypes, ArrayParameter<RenderQuery*const> queries)

Creates multiple tp::RenderQuery objects.

Parameters
queryTypes The types of render queries that are to be created.
queries An output array of pointers to tp::RenderQuery objects that are to be created. The size of this array must match the size of the queryTypes array.

Sampler tp::Device::createSampler(const SamplerSetup& setup, const char* debugName = nullptr)

Creates a tp::Sampler object according to the given setup structure.

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

ShaderModule tp::Device::createShaderModule(ArrayParameter<const uint32_t> shaderCode, const char* debugName = nullptr)

Creates a tp::ShaderModule object out of the given SPIR-V shader code.

Parameters
shaderCode The SPIR-V code to be used to create the shader module.
debugName The debug name identifier for the object.

OwningPtr<Swapchain> tp::Device::createSwapchainKHR(const SwapchainSetup& setup, Swapchain* oldSwapchain = nullptr, const char* debugName = nullptr)

Creates a tp::Swapchain object according to the given setup structure.

Parameters
setup The setup structure describing the object.
oldSwapchain An old swapchain to reuse resources of. It will be switched to a retired state and new images can no longer be acquired from it.
debugName The debug name identifier for the object.

void tp::Device::createTimestampQueries(ArrayParameter<TimestampQuery*const> queries)

Creates multiple tp::TimestampQuery objects.

Parameters
queries An output array of pointers to tp::TimestampQuery objects that are to be created.

JobSemaphore tp::Device::enqueueJob(const DeviceQueue& queue, Job job, ArrayParameter<const JobSemaphore> waitJobSemaphores = {}, ArrayParameter<const ExternalSemaphore> waitExternalSemaphores = {}, ArrayParameter<const ExternalSemaphore> signalExternalSemaphores = {})

Enqueues the given tp::Job to the specified queue, creating and initializing its local resources.

Parameters
queue The queue that the job will be submitted to. The queue must match the queue used for creating the tp::JobResourcePool object that is the parent of the enqueued job.
job The tp::Job object to enqueue. The ownership is transferred from the user over to the implementation.
waitJobSemaphores A list of job semaphores that the job will wait on before actually executing on the device. It is not necessary to wait on semaphores of jobs submitted to the same queue.
waitExternalSemaphores A list of external semaphores the job will wait on before executing on the device.
signalExternalSemaphores A list of external semaphores the job will signal once it finishes executing on the device.
Returns Returns a job semaphore that will be signalled once the job finishes executing on the device.

When the job gets enqueued, all of the job-local resources get created and become accessible, and command lists can be recorded. To actually schedule execution of the job on the device, tp::Device::submitQueuedJobs must be called.

MemoryHeapStatistics tp::Device::getMemoryHeapStatistics(uint32_t memoryHeapIndex) const

Returns the statistics for the Vulkan memory heap with the given index.

bool tp::Device::isJobSemaphoreSignalled(const JobSemaphore& semaphore)

Returns true if the given tp::JobSemaphore has been signalled, meaning the job has finished executing on the device.

Parameters
semaphore The job semaphore to query the state of.

void tp::Device::submitPresentImagesKHR(const DeviceQueue& queue, ArrayParameter<Swapchain*const> swapchains, ArrayParameter<const uint32_t> imageIndices)

Submits a present operation to the specified queue for each of the given tp::Swapchain objects, queueing the given acquired image from each swapchain for presentation.

Parameters
queue The queue that the present operation will be submitted to.
swapchains An array of swapchains whose images will be presented.
imageIndices An array of indices of the acquired swapchain images to be presented. The indices should be the tp::AcquiredImageInfo::imageIndex of an image previously acquired from the corresponding swapchain in the swapchains array.

void tp::Device::submitQueuedJobs(const DeviceQueue& queue, const JobSemaphore& lastJobToSubmit = {}, ArrayParameter<const JobSemaphore> waitJobSemaphores = {}, ArrayParameter<const ExternalSemaphore> waitExternalSemaphores = {})

Submits all tp::Job objects previously enqueued to the specified queue and schedules them to be executed on the device.

Parameters
queue The queue to have its enqueued jobs submitted for execution.
lastJobToSubmit Optionally requests a partial submit of the enqueued jobs. If not empty, any job that was enqueued after the one associated with the given semaphore will not be submitted.
waitJobSemaphores A list of additional job semaphores the queue will wait on before executing any enqueued jobs. It is not necessary to wait on semaphores of jobs submitted to the same queue.
waitExternalSemaphores A list of additional external semaphores the queue will wait on before executing any enqueued jobs.

OwningPtr<Buffer> tp::Device::vkCreateExternalBuffer(const BufferSetup& setup, Lifeguard<VkBufferHandle>&& bufferHandle, Lifeguard<VmaAllocationHandle>&& memoryAllocationHandle, const char* debugName = nullptr)

Creates a tp::Buffer object out of a raw Vulkan buffer handle and an optional VMA memory allocation handle.

Parameters
setup The setup structure that would result in a similar buffer if created with tp::Device::allocateBuffer.
bufferHandle A lifeguard handle for a Vulkan buffer created from the same Vulkan device as returned by tp::Device::vkGetDeviceHandle.
memoryAllocationHandle A lifeguard handle for the associated VMA memory allocation that has been allocated with the same VMA allocator as returned by tp::Device::vmaGetAllocatorHandle. It can be null, but if it is, tp::Buffer::mapForHostAccess, tp::Buffer::getMemoryLocation and tp::Buffer::getRequiredViewAlignment must not be called on the resulting buffer.
debugName The debug name identifier for the object.

OwningPtr<Image> tp::Device::vkCreateExternalImage(const ImageSetup& setup, Lifeguard<VkImageHandle>&& imageHandle, Lifeguard<VmaAllocationHandle>&& memoryAllocationHandle, const char* debugName = nullptr)

Creates a tp::Image object out of a raw Vulkan image handle and an optional VMA memory allocation handle.

Parameters
setup The setup structure that would result in a similar image if created with tp::Device::allocateImage.
imageHandle A lifeguard handle for a Vulkan image created from the same Vulkan device as returned by tp::Device::vkGetDeviceHandle.
memoryAllocationHandle A lifeguard handle for the associated VMA memory allocation that has been allocated with the same VMA allocator as returned by tp::Device::vmaGetAllocatorHandle. It can be null, but if it is, tp::Image::getMemoryLocation must not be called on the resulting image.
debugName The debug name identifier for the object.

VkQueueHandle tp::Device::vkGetQueueHandle(const DeviceQueue& queue) const

Returns the Vulkan VkQueue handle associated with the given tp::DeviceQueue.

Parameters
queue The queue to return the handle for.

template<typename TypedHandle>
Lifeguard<TypedHandle> tp::Device::vkMakeHandleLifeguard(TypedHandle vkHandle)

Wraps the given Vulkan handle object in an owning tp::Lifeguard, ensuring its safe deletion after the lifeguard gets destroyed. Example usage: device->vkMakeHandleLifeguard(VkImageHandle(vkImage))

void tp::Device::waitForIdle()

Waits until the device becomes idle. It guarantees that all submitted jobs have finished executing and their corresponding semaphores have been signalled.

bool tp::Device::waitForJobSemaphores(ArrayParameter<const JobSemaphore> semaphores, bool waitAll = true, Timeout timeout = Timeout::Indefinite())

Waits until the given tp::JobSemaphore handles have been signalled or until the timeout has been reached.

Parameters
semaphores The semaphores to wait for.
waitAll If true, the function returns when all of the given semaphores have been signalled. Otherwise, it returns when at least one of them has been signalled.
timeout The timeout limit or waiting.
Returns Returns true if all (or at least one of, depending on the waitAll parameter) the semaphores have been signalled. Returns false when the timeout has been reached and the semaphores are still unsignalled.