Centralized timeline semaphore management for the rendering pipeline. More...

#include <TimelineSynchronizer.h>

Collaboration diagram for EngineCore::TimelineSynchronizer:

Public Member Functions
	TimelineSynchronizer (ApplicationContext *context, uint32_t framesInFlight)
	Constructs a timeline synchronizer.
	~TimelineSynchronizer ()
	TimelineSynchronizer (const TimelineSynchronizer &)=delete
TimelineSynchronizer &	operator= (const TimelineSynchronizer &)=delete
	TimelineSynchronizer (TimelineSynchronizer &&other) noexcept
TimelineSynchronizer &	operator= (TimelineSynchronizer &&other) noexcept
uint64_t	getStageValue (uint64_t frameNumber, PipelineStage stage) const
	Gets the timeline value for a specific stage at a specific frame.
std::optional< uint64_t >	getWaitValue (uint64_t currentFrame, PipelineStage waitForStage, uint32_t framesBack=1) const
	Gets the value to wait for from a previous frame's stage.
std::optional< uint64_t >	getResourceReuseWaitValue (uint64_t currentFrame, PipelineStage waitForStage) const
	Gets the wait value for resource reuse (frames-in-flight synchronization)
uint64_t	getCurrentValue () const
	Gets the current GPU timeline semaphore value.
void	waitForValue (uint64_t value, uint64_t timeout=UINT64_MAX) const
	CPU-side wait for a specific timeline value.
void	waitForStage (uint64_t frameNumber, PipelineStage stage, uint64_t timeout=UINT64_MAX) const
	CPU-side wait for a specific stage to complete.
void	signalValue (uint64_t value) const
	CPU-side signal of the timeline semaphore.
VkSemaphore	getSemaphore () const
	Gets the underlying Vulkan timeline semaphore.
uint32_t	getFramesInFlight () const
	Gets the number of frames in flight.

Private Attributes
ApplicationContext *	context_ = nullptr
VkSemaphore	timelineSemaphore_ = VK_NULL_HANDLE
uint32_t	framesInFlight_ = 0

Detailed Description

Centralized timeline semaphore management for the rendering pipeline.

Manages a single timeline semaphore used for synchronizing all pipeline stages. Timeline values are computed using the formula: timelineValue = frameNumber * PIPELINE_STAGE_COUNT + stageIndex

This provides:

Monotonically increasing values (required by timeline semaphores)
Predictable values for any stage at any frame
Easy extension with new pipeline stages

Date: 2026-01-14

Author: Konstantin Passig

Definition at line 28 of file TimelineSynchronizer.h.

Constructor & Destructor Documentation

◆ TimelineSynchronizer() [1/3]

EngineCore::TimelineSynchronizer::TimelineSynchronizer	(	ApplicationContext *	context,
		uint32_t	framesInFlight )

explicit

Constructs a timeline synchronizer.

Parameters

context	The application context for Vulkan device access
framesInFlight	Number of frames that can be processed concurrently

Definition at line 10 of file TimelineSynchronizer.cpp.

References context_, framesInFlight_, and timelineSemaphore_.

Referenced by operator=(), operator=(), TimelineSynchronizer(), and TimelineSynchronizer().

Here is the caller graph for this function:

◆ ~TimelineSynchronizer()

EngineCore::TimelineSynchronizer::~TimelineSynchronizer ( )

Definition at line 39 of file TimelineSynchronizer.cpp.

References context_, and timelineSemaphore_.

◆ TimelineSynchronizer() [2/3]

EngineCore::TimelineSynchronizer::TimelineSynchronizer ( const TimelineSynchronizer & )

delete

References TimelineSynchronizer().

Here is the call graph for this function:

◆ TimelineSynchronizer() [3/3]

EngineCore::TimelineSynchronizer::TimelineSynchronizer ( TimelineSynchronizer && other )

noexcept

Definition at line 48 of file TimelineSynchronizer.cpp.

References context_, framesInFlight_, timelineSemaphore_, and TimelineSynchronizer().

Here is the call graph for this function:

Member Function Documentation

◆ getCurrentValue()

uint64_t EngineCore::TimelineSynchronizer::getCurrentValue ( ) const

nodiscard

Gets the current GPU timeline semaphore value.

Returns: The current counter value of the timeline semaphore

Definition at line 81 of file TimelineSynchronizer.cpp.

References context_, and timelineSemaphore_.

◆ getFramesInFlight()

uint32_t EngineCore::TimelineSynchronizer::getFramesInFlight ( ) const

inlinenodiscard

Gets the number of frames in flight.

Returns: The frames in flight count

Definition at line 152 of file TimelineSynchronizer.h.

References framesInFlight_.

◆ getResourceReuseWaitValue()

std::optional< uint64_t > EngineCore::TimelineSynchronizer::getResourceReuseWaitValue	(	uint64_t	currentFrame,
		PipelineStage	waitForStage ) const

inlinenodiscard

Gets the wait value for resource reuse (frames-in-flight synchronization)

Waits for the frame that last used this resource slot. Use this when waiting to reuse per-frame resources like command buffers or staging buffers.

Parameters

currentFrame	The current frame number
waitForStage	The stage to wait for

Returns: The wait value, or nullopt if no wait is needed

Definition at line 93 of file TimelineSynchronizer.h.

References framesInFlight_, getStageValue(), and waitForStage().

Here is the call graph for this function:

◆ getSemaphore()

VkSemaphore EngineCore::TimelineSynchronizer::getSemaphore ( ) const

inlinenodiscard

Gets the underlying Vulkan timeline semaphore.

Returns: The VkSemaphore handle

Definition at line 146 of file TimelineSynchronizer.h.

References timelineSemaphore_.

◆ getStageValue()

uint64_t EngineCore::TimelineSynchronizer::getStageValue	(	uint64_t	frameNumber,
		PipelineStage	stage ) const

inlinenodiscard

Gets the timeline value for a specific stage at a specific frame.

Parameters

frameNumber	The absolute frame number
stage	The pipeline stage

Returns: The timeline semaphore value

Definition at line 56 of file TimelineSynchronizer.h.

References EngineCore::PIPELINE_STAGE_COUNT.

Referenced by getResourceReuseWaitValue(), getWaitValue(), and waitForStage().

Here is the caller graph for this function:

◆ getWaitValue()

std::optional< uint64_t > EngineCore::TimelineSynchronizer::getWaitValue	(	uint64_t	currentFrame,
		PipelineStage	waitForStage,
		uint32_t	framesBack = 1 ) const

inlinenodiscard

Gets the value to wait for from a previous frame's stage.

Parameters

currentFrame	The current frame number
waitForStage	The stage to wait for
framesBack	How many frames back to wait (default: 1)

Returns: The wait value, or nullopt if no wait is needed (first frames)

Definition at line 71 of file TimelineSynchronizer.h.

References getStageValue(), and waitForStage().

Here is the call graph for this function:

◆ operator=() [1/2]

TimelineSynchronizer & EngineCore::TimelineSynchronizer::operator= ( const TimelineSynchronizer & )

delete

References TimelineSynchronizer().

Here is the call graph for this function:

◆ operator=() [2/2]

TimelineSynchronizer & EngineCore::TimelineSynchronizer::operator= ( TimelineSynchronizer && other )

noexcept

Definition at line 58 of file TimelineSynchronizer.cpp.

References context_, framesInFlight_, timelineSemaphore_, and TimelineSynchronizer().

Here is the call graph for this function:

◆ signalValue()

void EngineCore::TimelineSynchronizer::signalValue ( uint64_t value ) const

CPU-side signal of the timeline semaphore.

Use this during shutdown to unblock GPU work that is waiting on timeline semaphore values that will never be signaled by subsequent GPU submissions.

Parameters

value The value to signal (must be greater than current value)

Definition at line 106 of file TimelineSynchronizer.cpp.

References context_, and timelineSemaphore_.

◆ waitForStage()

void EngineCore::TimelineSynchronizer::waitForStage	(	uint64_t	frameNumber,
		PipelineStage	stage,
		uint64_t	timeout = UINT64_MAX ) const

inline

CPU-side wait for a specific stage to complete.

Parameters

frameNumber	The frame number
stage	The pipeline stage
timeout	Maximum wait time in nanoseconds (default: infinite)

Definition at line 125 of file TimelineSynchronizer.h.

References getStageValue(), and waitForValue().

Referenced by getResourceReuseWaitValue(), and getWaitValue().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ waitForValue()

void EngineCore::TimelineSynchronizer::waitForValue	(	uint64_t	value,
		uint64_t	timeout = UINT64_MAX ) const

CPU-side wait for a specific timeline value.

Parameters

value	The value to wait for
timeout	Maximum wait time in nanoseconds (default: infinite)

Definition at line 88 of file TimelineSynchronizer.cpp.

References context_, and timelineSemaphore_.

Referenced by waitForStage().

Here is the caller graph for this function:

Member Data Documentation

◆ context_

ApplicationContext* EngineCore::TimelineSynchronizer::context_ = nullptr

private

Definition at line 155 of file TimelineSynchronizer.h.

Referenced by getCurrentValue(), operator=(), signalValue(), TimelineSynchronizer(), TimelineSynchronizer(), waitForValue(), and ~TimelineSynchronizer().

◆ framesInFlight_

uint32_t EngineCore::TimelineSynchronizer::framesInFlight_ = 0

private

Definition at line 157 of file TimelineSynchronizer.h.

Referenced by getFramesInFlight(), getResourceReuseWaitValue(), operator=(), TimelineSynchronizer(), and TimelineSynchronizer().

◆ timelineSemaphore_

VkSemaphore EngineCore::TimelineSynchronizer::timelineSemaphore_ = VK_NULL_HANDLE

private

Definition at line 156 of file TimelineSynchronizer.h.

Referenced by getCurrentValue(), getSemaphore(), operator=(), signalValue(), TimelineSynchronizer(), TimelineSynchronizer(), waitForValue(), and ~TimelineSynchronizer().

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

/home/magerbeton/Documents/gl3-vulkan/Engine/include/Engine/Renderer/TimelineSynchronizer.h
/home/magerbeton/Documents/gl3-vulkan/Engine/src/Engine/Renderer/TimelineSynchronizer.cpp

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TimelineSynchronizer() [1/3]

◆ ~TimelineSynchronizer()

◆ TimelineSynchronizer() [2/3]

◆ TimelineSynchronizer() [3/3]

Member Function Documentation

◆ getCurrentValue()

◆ getFramesInFlight()

◆ getResourceReuseWaitValue()

◆ getSemaphore()

◆ getStageValue()

◆ getWaitValue()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ signalValue()

◆ waitForStage()

◆ waitForValue()

Member Data Documentation

◆ context_

◆ framesInFlight_

◆ timelineSemaphore_