ludus::graphics::renderer::RenderGraphActivation¶

Class

Stage a complete graph + shader + plan generation and publish it atomically between frames. The active generation keeps rendering while a candidate prepares; a failed or rejected candidate never replaces it, so its last pixels and output revision remain. Activation happens only inside Poll, when the candidate's pipelines are Ready and it has prepared the latest accepted extraction. The replaced generation is Reset at that boundary: its GPU uses retire through RHI completion, independently of any game-module quiescence. Packages are owned here, so no plan retains pointers into caller memory. All calls use the RHI owner thread between frames, except the active graph's own Encode contract. The device and composite artifact storage outlive this object.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

#include <ludus/graphics/renderer/render_graph_activation.hpp>

class ludus::graphics::renderer::RenderGraphActivation final

Methods¶

RenderGraphActivation¶

ludus::graphics::renderer::RenderGraphActivation::RenderGraphActivation() noexcept

Construct without GPU work.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

~RenderGraphActivation¶

ludus::graphics::renderer::RenderGraphActivation::~RenderGraphActivation() noexcept

Reset every generation.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

RenderGraphActivation¶

ludus::graphics::renderer::RenderGraphActivation::RenderGraphActivation(const RenderGraphActivation &)=delete

Ownership is noncopyable.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

operator=¶

RenderGraphActivation & ludus::graphics::renderer::RenderGraphActivation::operator=(const RenderGraphActivation &)=delete

Ownership is nonassignable.

Related types: RenderGraphActivation

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

Initialize¶

rhi::RasterStatus ludus::graphics::renderer::RenderGraphActivation::Initialize(rhi::DeviceHandle device, foundation::BorrowedView< const foundation::uint8 > interfaceIdentity, const rhi::RasterShaderDescription &compositeVertex, const rhi::RasterShaderDescription &compositeFragment, RenderGraphAllocation allocation=RenderGraphAllocation::ExactPool) noexcept

Bind the device, the host's compiled CPU interface identity and composite recipes.

Parameter	Description
`device`	Owned device; must outlive this object and every staged generation.
`interfaceIdentity`	IDENTITY_BYTES digest from the host's generated header; copied.
`compositeVertex`	Installed renderer_composite vertex recipe; its artifact storage outlives this object.
`compositeFragment`	Installed renderer_composite fragment recipe; same lifetime as compositeVertex.
`allocation`	ExactPool (default) shares one attachment pool across generations; SerialControl is the non-pooled diagnostic control.

Returns

InvalidState when already initialized; InvalidDescription for a wrong identity width or an unknown allocation; the pool's device admission status when it cannot be bound.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

Stage¶

rhi::RasterStatus ludus::graphics::renderer::RenderGraphActivation::Stage(foundation::core::UniquePtr< RenderGraphPackage > package, const LightTransformerModelDescription *modelOrNull=nullptr) noexcept

Take ownership of a decoded package and begin preparing it as the candidate. Native shader/driver pipeline work is queued; owner-thread calls never wait for it. Queue admission/allocation may fail, preserving the active graph. An earlier unactivated candidate is discarded. A CPU interface mismatch returns Unsupported with RestartRequired; setup failure returns its status with Failed. Neither changes the active generation. Pending/Ready is accepted. A diagnostic ray path capture package (RenderGraphPackage::IsRayPathCapture) or a frame capture profile (RenderGraphPackage::IsCaptureProfile) returns InvalidDescription without staging: it never becomes a drawing generation.

Parameter	Description
`package`	Owned cooked candidate; ownership is consumed by this call, including on failure.
`modelOrNull`	Optional trained model setup, required by Light Transformer packages; assets are consumed/copied during this call, encoder artifact storage survives Poll.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

StageSelected¶

rhi::RasterStatus ludus::graphics::renderer::RenderGraphActivation::StageSelected(foundation::core::UniquePtr< RenderGraphPackage > rasterPackage, foundation::core::UniquePtr< RenderGraphPackage > rayPackageOrNull, RenderGraphPreference preference=RenderGraphPreference::Automatic) noexcept

Select and stage an authored renderer, taking ownership of both packages.

Parameter	Description
`rasterPackage`	Loaded raster-only graph; mandatory on every device.
`rayPackageOrNull`	Optional loaded graph containing software or native triangle ray passes.
`preference`	Automatic stages a software-only ray package through ordinary compute. Native packages require enabled native traversal and compute. ForceRaster always stages rasterPackage.

Returns

Stage's result for the selected package. Invalid packages/preferences or device query failures preserve both active and candidate generations. An unsupported ray API selects raster before preparing shaders or acceleration structures. Unselected packages are released. Shader, scene or allocation failures are reported through normal activation; they never change the authored traversal strategy. Re-stage fresh packages to change the preference.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

Resize¶

rhi::RasterStatus ludus::graphics::renderer::RenderGraphActivation::Resize(foundation::uint32 referenceWidth, foundation::uint32 referenceHeight) noexcept

Set this activation's drawable reference size, including before Stage. Relative packages require a positive reference before staging; fixed packages ignore it. For an active or staged graph, follows RenderGraph::Resize's consumer, Update and publication contract. A minimized (zero) request returns NotReady and preserves the prior reference/output. No shader artifacts or pipeline contexts are recreated. Independent activations keep independent references. Failure preserves the active drawable generation.

Related types: foundation::uint32 · rhi::RasterStatus

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

Poll¶

rhi::RasterStatus ludus::graphics::renderer::RenderGraphActivation::Poll() noexcept

Advance the active graph and the candidate; activate a complete candidate. Returns the active graph's Poll status, or the candidate's while no generation is active. Export consumers of the active generation must have completed before a Poll that may activate.

Related types: rhi::RasterStatus

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

Update¶

rhi::RasterStatus ludus::graphics::renderer::RenderGraphActivation::Update(foundation::BorrowedView< const RenderGraphMesh > meshes, foundation::BorrowedView< const RenderGraphItem > items, foundation::BorrowedView< const ViewDescription > cameras, foundation::uint64 sceneRevision, RenderGraphCoveragePolicy policy, RenderGraphReport &outReport, const SceneShaderInputs *sceneInputsOrNull=nullptr, foundation::uint64 contentRevision=0) noexcept

Forward one extraction to the active graph and to a candidate whose pipelines are Ready. outReport describes the active graph (or the candidate when none is active). A candidate that rejects an extraction the active generation accepts becomes Failed. Inputs need only survive the call.

Parameter	Description
`meshes`	Borrowed static geometry table, copied during a full extraction.
`items`	Borrowed instances, transforms, material bindings and per-draw values.
`cameras`	Complete generation-local camera table; consumed before return.
`sceneRevision`	Nonzero identity for the requested drawable scene/view publication.
`policy`	Whether unsupported coverage rejects or receives diagnostic color.
`outReport`	Latest candidate diagnostics, independent of the retained drawable output. Preflight rejection preserves it; coverage/preparation results replace it.
`sceneInputsOrNull`	Optional borrowed material/light/environment inputs for a full extraction.
`contentRevision`	Optional nonzero identity for all non-camera inputs. Reusing it promises unchanged geometry, transforms, materials, lights, uniforms and coverage policy; only cameras and sceneRevision may change. This reuses scene/acceleration buffers and resets camera history. Zero always prepares a complete extraction. Resize and new generations also prepare in full.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

GetActiveOrNull¶

RenderGraph * ludus::graphics::renderer::RenderGraphActivation::GetActiveOrNull() noexcept

Borrow the drawing generation's graph for Render/Encode/exports; null when none is active. The pointer changes when ActiveGeneration changes; never retain it across Poll.

Related types: RenderGraph

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

GetReport¶

RenderGraphActivationReport ludus::graphics::renderer::RenderGraphActivation::GetReport() const noexcept

Copy the activation status.

Related types: RenderGraphActivationReport

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

GetPoolReport¶

RenderGraphPoolReport ludus::graphics::renderer::RenderGraphActivation::GetPoolReport() const noexcept

Copy the owned pool's counters; SerialControl and an uninitialized activation report zeros.

Related types: RenderGraphPoolReport

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

TrimPool¶

void ludus::graphics::renderer::RenderGraphActivation::TrimPool() noexcept

Destroy idle pooled attachments between frames, for example under memory pressure. Attachments of the active and candidate generations are unaffected.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp

Reset¶

void ludus::graphics::renderer::RenderGraphActivation::Reset() noexcept

Release every generation; no open frame or outstanding export consumer is permitted.

Declared in modules/graphics/renderer/include/ludus/graphics/renderer/render_graph_activation.hpp