Raven::VulkanGPUQuery Class Reference

Vulkan implementation of GPU timestamp query profiling. More...

#include <VulkanGPUQuery.h>

Inherits Raven::GPUQuery.

Public Member Functions
	VulkanGPUQuery ()=default
ILLUMINE_API	VulkanGPUQuery (u32 queryCount)
	Constructs the query system and allocates per-frame Vulkan query pools.
	VulkanGPUQuery (VulkanGPUQuery &&) noexcept=default
VulkanGPUQuery &	operator= (VulkanGPUQuery &&) noexcept=default
	VulkanGPUQuery (const VulkanGPUQuery &)=delete
VulkanGPUQuery &	operator= (const VulkanGPUQuery &)=delete
ILLUMINE_API void	Destroy () override
	Destroys all Vulkan query pools.
ILLUMINE_API void	BeginFrame (VkCommandBuffer cmd, u32 frameIndex)
	Resets the query pool for the given frame and marks it as active.
ILLUMINE_API void	EndFrame (u32 frameIndex)
	Reads back timestamp results and marks the frame slot as inactive.
ILLUMINE_API void	BeginGPUQuery (Ref< RenderCommandBuffer > commandBuffer, const std::string &name) override
	Records a begin timestamp for a named GPU scope.
ILLUMINE_API void	EndGPUQuery (Ref< RenderCommandBuffer > commandBuffer) override
	Records an end timestamp, closing the innermost open scope.
ILLUMINE_API const std::vector< GPUTimeSpan > &	GetTimeStampResults () const override
	Returns the timing results from the most recently completed frame.
Public Member Functions inherited from Raven::GPUQuery
virtual	~GPUQuery ()=default

Detailed Description

Vulkan implementation of GPU timestamp query profiling.

Manages per-frame Vulkan query pools to measure GPU execution time of arbitrary named scopes. Each in-flight frame owns its own query pool, eliminating cross-frame data hazards without requiring a device wait.

Usage

// On render thread, each frame:
query.BeginFrame(cmd, frameIndex);
 
query.BeginGPUQuery(commandBuffer, "Shadow Pass");
// ... record commands ...
query.EndGPUQuery(commandBuffer);
 
// After vkQueueSubmit:
query.EndFrame(frameIndex);
 
// Results from the previous frame are available via:
const auto& results = query.GetTimeStampResults();

Note

All Begin/End calls must occur on the render thread within an active frame.

Nested queries are supported — End closes the innermost open scope.

Warning

Query slots are finite. Increase QUERY_COUNT if the exceeded error fires.

Constructor & Destructor Documentation

VulkanGPUQuery() [1/4]

Raven::VulkanGPUQuery::VulkanGPUQuery ( )

default

VulkanGPUQuery() [2/4]

Raven::VulkanGPUQuery::VulkanGPUQuery ( u32 queryCount )

explicit

Constructs the query system and allocates per-frame Vulkan query pools.

Parameters

queryCount

Maximum number of individual timestamp writes per frame. Each Begin/End pair consumes two slots, so this supports queryCount / 2 named scopes per frame.

VulkanGPUQuery() [3/4]

Raven::VulkanGPUQuery::VulkanGPUQuery ( VulkanGPUQuery && )

defaultnoexcept

VulkanGPUQuery() [4/4]

Raven::VulkanGPUQuery::VulkanGPUQuery ( const VulkanGPUQuery & )

delete

Member Function Documentation

BeginFrame()

void Raven::VulkanGPUQuery::BeginFrame	(	VkCommandBuffer	cmd,
		u32	frameIndex )

Resets the query pool for the given frame and marks it as active.

Must be called at the start of each frame on the render thread, before any BeginGPUQuery calls for that frame. Issues a vkCmdResetQueryPool into the provided command buffer.

Parameters

cmd	The command buffer currently being recorded for this frame.
frameIndex	Swapchain frame index in range [0, FramesInFlight).

BeginGPUQuery()

void Raven::VulkanGPUQuery::BeginGPUQuery ( Ref< RenderCommandBuffer > commandBuffer, const std::string & name )

overridevirtual

Records a begin timestamp for a named GPU scope.

Writes a VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT timestamp and pushes the scope onto the active query stack. Supports nesting — scopes are closed in LIFO order by EndGPUQuery.

Parameters

commandBuffer	The active command buffer to record into.
name	Display name for this scope in profiling output.

Implements Raven::GPUQuery.

Destroy()

void Raven::VulkanGPUQuery::Destroy ( )

overridevirtual

Destroys all Vulkan query pools.

Note

Must be called before the VkDevice is destroyed.

Implements Raven::GPUQuery.

EndFrame()

void Raven::VulkanGPUQuery::EndFrame

(

u32

frameIndex

)

Reads back timestamp results and marks the frame slot as inactive.

Must be called after vkQueueSubmit on the render thread. Results are retrieved with VK_QUERY_RESULT_WITH_AVAILABILITY_BIT so incomplete queries are skipped safely rather than blocking.

Parameters

frameIndex

Swapchain frame index in range [0, FramesInFlight).

EndGPUQuery()

void Raven::VulkanGPUQuery::EndGPUQuery ( Ref< RenderCommandBuffer > commandBuffer )

overridevirtual

Records an end timestamp, closing the innermost open scope.

Writes a VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT timestamp and pops the active query stack. Every BeginGPUQuery must have exactly one matching EndGPUQuery within the same frame.

Parameters

commandBuffer

The active command buffer to record into.

Implements Raven::GPUQuery.

GetTimeStampResults()

const std::vector< GPUTimeSpan > & Raven::VulkanGPUQuery::GetTimeStampResults ( ) const

nodiscardoverridevirtual

Returns the timing results from the most recently completed frame.

Results are populated during EndFrame and remain valid until the next EndFrame call. Only scopes with available timestamps are included.

Returns

Const reference to the list of completed GPU time spans.

Implements Raven::GPUQuery.

operator=() [1/2]

VulkanGPUQuery & Raven::VulkanGPUQuery::operator= ( const VulkanGPUQuery & )

delete

operator=() [2/2]

VulkanGPUQuery & Raven::VulkanGPUQuery::operator= ( VulkanGPUQuery && )

defaultnoexcept

---

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

• Illumine/src/Renderer/backend/Vulkan/VulkanGPUQuery.h
• Illumine/src/Renderer/backend/Vulkan/VulkanGPUQuery.cpp