Engine

Wraps the Vulkan context and the compute graph, compiles graphs, manages the camera uniform buffer and drives the frame-submit loop.

class KlartraumEngine

Frame updates

setFrameUpdate() installs an application callback that receives the acquired render path’s index after its previous GPU use completes and before graph submission. Pass nullptr to disable the callback.

If the callback throws, the engine completes the acquired frame without running its graphs and rethrows the original exception. The frame fence is signaled and its acquisition semaphore is consumed, so the application can catch the exception and render another frame or shut down. A cancelled window frame discards its contents and returns the image in presentation layout. Cancellation waits for device completion before releasing its temporary submission resources.

Windows and render targets

A window composites viewports into its swapchain image; offscreen targets are the render targets of viewports and of rendering without a window.

class Window

Composites viewports into the swapchain image of the window.

makeViewport() hands out offscreen render targets for sub-regions of the window. One composite per swapchain image, recorded once, blits every viewport into its rectangle and transitions the swapchain image for presentation. The engine submits the composite once per frame after the viewport scenes have rendered.

class OffscreenTarget : public klartraum::ImageViewSrc

An ImageViewSrc that owns its images instead of wrapping the swapchain’s.

Used as a render target for viewports and for rendering without a window: a scene renders into it at its full extent exactly as it would into the swapchain, and the Window composite can blit it into a sub-region of the swapchain image.

It allocates numImages images (one per swapchain image or compute-graph path) in the swapchain format, with usage STORAGE | COLOR_ATTACHMENT | TRANSFER_SRC, so both the compute and the raster backend can write them and the composite can blit from them. getFinalLayoutOverride() reports TRANSFER_SRC_OPTIMAL, so the backends leave the images ready for that blit (PRESENT_SRC would not be valid).

Overlays

class FrameOverlay

Per-frame work drawn on top of the finished swapchain image, e.g. an immediate-mode GUI.

Unlike the compute graphs, whose command buffers are recorded once and resubmitted unchanged, an overlay records its commands anew every frame, so its content may change freely.

KlartraumEngine::step() submits the overlay after all graphs (or after the viewport composite) and before presenting. At that point the swapchain image is in PRESENT_SRC_KHR (GENERAL when headless) and must be left in the same layout. This requires at least one graph (or the viewport composite) to have rendered the image.