ludus::graphics::rhi::ComputeCache¶

Class

Owner-thread, two-generation cache for view-independent GPU preprocessing. Stage/encode/submit/Poll leaves the active buffers intact until a replacement submission completes. No hidden execution, GPU wait, CPU readback or fallback. Mutable workload output must not be modified after publication while consumers use it. Call between frames and destroy before the device; normal RHI leases retire old uses.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

#include <ludus/graphics/rhi/compute_cache.hpp>

class ludus::graphics::rhi::ComputeCache final

Methods¶

ComputeCache¶

ludus::graphics::rhi::ComputeCache::ComputeCache() noexcept=default

Construct an empty cache with no device or resource ownership.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

ComputeCache¶

ludus::graphics::rhi::ComputeCache::ComputeCache(const ComputeCache &)=delete

Candidate tickets require a stable cache address; copying is forbidden.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

operator=¶

ComputeCache & ludus::graphics::rhi::ComputeCache::operator=(const ComputeCache &)=delete

Candidate tickets require a stable cache address; copy assignment is forbidden.

Related types: ComputeCache

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

ComputeCache¶

ludus::graphics::rhi::ComputeCache::ComputeCache(ComputeCache &&)=delete

Candidate tickets require a stable cache address; moving is forbidden.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

operator=¶

ComputeCache & ludus::graphics::rhi::ComputeCache::operator=(ComputeCache &&)=delete

Candidate tickets require a stable cache address; move assignment is forbidden.

Related types: ComputeCache

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

Stage¶

RasterStatus ludus::graphics::rhi::ComputeCache::Stage(DeviceHandle device, ComputeCacheKey key, const ComputeWorkloadDescription &description) noexcept

Prepare a new candidate, preserving active and previous candidate on admission failure. Equal active/candidate keys reuse their result/state without uploading. Different accepted keys supersede pending work; caller must discard any unsubmitted graph of the superseded candidate. Input lifetimes follow ComputeWorkload::Initialize. Device must match every existing active/candidate generation until Reset. Candidate writable buffers must be newly owned: writable External buffers reject. Read-only External inputs must have owners outside this cache that outlive both generations; borrowing this cache's active owned buffers is invalid.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

Poll¶

RasterStatus ludus::graphics::rhi::ComputeCache::Poll() noexcept

Advance preparation or check submission completion and atomically publish a completed candidate. Ready means no pending candidate; it never means that unsubmitted GPU work has completed. Host drives PollLifetime as usual. A failed candidate remains inspectable and does not release active buffers.

Related types: RasterStatus

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

BuildCandidateGraph¶

RasterStatus ludus::graphics::rhi::ComputeCache::BuildCandidateGraph(OrderedGraph &outGraph) noexcept

Build the prepared candidate's graph, then enter AwaitingSubmission. Caller compiles/executes it using normal RHI APIs. Failure preserves phase and output.

Related types: RasterStatus · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

GetCandidateTicket¶

ComputeCacheTicket ludus::graphics::rhi::ComputeCache::GetCandidateTicket() const noexcept

Capture the current candidate attempt, or an invalid ticket when empty. A new accepted Stage uses a new attempt even when a cancelled key is reused.

Related types: ComputeCacheTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

SetCandidateCompletion¶

RasterStatus ludus::graphics::rhi::ComputeCache::SetCandidateCompletion(ComputeCacheTicket ticket, SubmissionToken completion) noexcept

Associate the exact attempt and submission that executed the candidate graph. Reject foreign/stale attempt callbacks, invalid tokens and calls outside AwaitingSubmission.

Precondition

completion actually covers all candidate kernels on this device.

Related types: RasterStatus · ComputeCacheTicket · SubmissionToken

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

CancelCandidate¶

void ludus::graphics::rhi::ComputeCache::CancelCandidate() noexcept

Drop candidate owners/state; submitted/retained graph work retires normally. Caller discards any unsubmitted candidate graph. Preserves the active result.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

HasActive¶

bool ludus::graphics::rhi::ComputeCache::HasActive() const noexcept

Whether a completed GPU result is published.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

GetActiveKey¶

ComputeCacheKey ludus::graphics::rhi::ComputeCache::GetActiveKey() const noexcept

Active semantic revisions, or zero revisions when HasActive is false.

Related types: ComputeCacheKey

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

GetPhase¶

ComputeCachePhase ludus::graphics::rhi::ComputeCache::GetPhase() const noexcept

Candidate state, independent of active readiness.

Related types: ComputeCachePhase

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

GetActiveBuffer¶

RasterStatus ludus::graphics::rhi::ComputeCache::GetActiveBuffer(foundation::usize index, BufferHandle &outBuffer) const noexcept

Borrow an active result allocation; same lifetime contract as GetBuffer. NotReady before first publication. Failures preserve outBuffer.

Related types: foundation::usize · RasterStatus · BufferHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp

Reset¶

void ludus::graphics::rhi::ComputeCache::Reset() noexcept

Release both generations and device association without waiting. Between frames.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute_cache.hpp