simvx.graphics.gpu.timestamp_pool

Vulkan timestamp query pool for per-pass GPU profiling.

A :class:TimestampPool wraps a single VkQueryPool of VK_QUERY_TYPE_TIMESTAMP and exposes a label-based API::

pool.reset(cmd)
pool.begin(cmd, "shadow")
# ... draw commands ...
pool.end(cmd, "shadow")
# submit, wait, then:
timings = pool.read_results()  # {"shadow": gpu_ms, ...}

The pool itself is purely additive — constructing one allocates a VkQueryPool and nothing else; no calls are issued unless the higher layer chooses to instrument a frame.

Module Contents

Classes

TimestampPool

Per-pass GPU timestamp pool.

Data

__all__
log

API

simvx.graphics.gpu.timestamp_pool.__all__

[‘TimestampPool’]

simvx.graphics.gpu.timestamp_pool.log

‘getLogger(…)’

class simvx.graphics.gpu.timestamp_pool.TimestampPool(device: Any, physical_device: Any, max_labels: int = 64)

Per-pass GPU timestamp pool.

Each label consumes two consecutive query slots (begin + end). Strict misuse — re-beginning a label, ending an unknown label, or exceeding max_labels distinct labels per frame — raises RuntimeError.

Initialization

__slots__

(‘device’, ‘physical_device’, ‘max_labels’, ‘ns_per_tick’, ‘pool’, ‘_labels’, ‘_next_index’)

reset(cmd: Any) → None

Reset the pool at the start of a frame.

Must be recorded into cmd before any begin/end calls. Clears the host-side label tracking so labels can be re-issued.

begin(cmd: Any, label: str) → None

Record a TOP_OF_PIPE timestamp for label.

end(cmd: Any, label: str) → None

Record a BOTTOM_OF_PIPE timestamp matching a prior begin(label).

read_results() → dict[str, float]

Read all begin/end pairs written this frame and return ms per label.

Uses VK_QUERY_RESULT_64_BIT | VK_QUERY_RESULT_WAIT_BIT so the call blocks until the GPU has written every queried slot. Labels that have a begin but no matching end are skipped.

destroy() → None

Destroy the underlying VkQueryPool.

__enter__() → simvx.graphics.gpu.timestamp_pool.TimestampPool

__exit__(exc_type: Any, exc: Any, tb: Any) → None