simvx.graphics.gpu.pipeline_cache

Persistent VkPipelineCache: warm vkCreate*Pipelines across runs.

A pipeline cache never changes rendering output; it only lets the driver reuse previously-compiled pipeline binaries instead of recompiling SPIR-V to GPU ISA on every launch. On the render-modernization examples the first-frame stall is almost entirely that recompilation (measured ~0.4 s recurring per run plus ~1.2 s of first-run pipeline construction); seeding the driver from a saved cache removes the recurring cost and warms the first run.

One cache per logical device, seeded from and flushed to a per-GPU file under the user cache dir ($XDG_CACHE_HOME/simvx/pipeline_cache or ~/.cache/...). The file is keyed + header-validated by pipelineCacheUUID + vendor/device id, so a foreign-GPU or driver-mismatched file is discarded rather than fed to the driver. Every failure path degrades to no-cache (NULL): a missing, corrupt, unreadable, or unwritable file is never fatal, and the render result is identical either way.

The :class:~simvx.graphics.engine.Engine owns the lifecycle: it calls

func:

init_pipeline_cache right after the device is created (before any pipeline is built) and :func:destroy_pipeline_cache (which flushes to disk) at teardown. Every vkCreate*Pipelines call site passes :func:pipeline_cache_for as its pipelineCache argument; when no cache is registered for that device (e.g. an isolated pass test with no Engine) it returns NULL and behaviour is unchanged.

Module Contents

Functions

init_pipeline_cache	Create the device’s pipeline cache, seeded from disk when a valid file exists.
pipeline_cache_for	The device’s VkPipelineCache handle, or NULL when none is registered.
save_pipeline_cache	Flush the (grown) pipeline cache to its per-GPU file. Never fatal.
destroy_pipeline_cache	Flush the cache to disk and destroy the handle. Idempotent, never fatal.

Data

log

API

simvx.graphics.gpu.pipeline_cache.log

‘getLogger(…)’

simvx.graphics.gpu.pipeline_cache.init_pipeline_cache(device: Any, physical_device: Any) → None

Create the device’s pipeline cache, seeded from disk when a valid file exists.

Idempotent and never fatal: any failure leaves no cache registered, so

Func:

pipeline_cache_for returns NULL and pipeline creation is unchanged.

simvx.graphics.gpu.pipeline_cache.pipeline_cache_for(device: Any) → Any

The device’s VkPipelineCache handle, or NULL when none is registered.

simvx.graphics.gpu.pipeline_cache.save_pipeline_cache(device: Any) → None

Flush the (grown) pipeline cache to its per-GPU file. Never fatal.

simvx.graphics.gpu.pipeline_cache.destroy_pipeline_cache(device: Any) → None

Flush the cache to disk and destroy the handle. Idempotent, never fatal.