ludus::graphics::renderer::StaticLightingBake¶

Class

CPU-only incremental static diffuse bake. Charts include all visible static area/environment direct diffuse and later indirect transport; analytic direct diffuse/specular stays raster. Set BakedLighting's AreTriangleChartsEnabled and HasStaticAreaDirect, and DirectLightId=0. Area specular is outside this profile. Per-triangle centroid irradiance is coarse spatial reconstruction; sample count controls transport variance. No Renderer, GPU, Qt or native ray-query state is touched. Zero-area triangles are skipped and reported through GetDiagnostics rather than failing the bake.

Two execution modes share the same transport and produce bit-identical charts:

Serial: Initialize, then Step until Ready, all on one thread.
Scheduled: Submit to a caller-owned foundation::threading::JobSystem, then Poll (nonblocking) or Finish (blocking) on the owner thread that serializes that system. Preparation and coarse triangle ranges run as jobs reading one immutable prepared scene; each range writes only its own triangles. After the JobSystem::Wait lifetime fence, the owner merges range results in stable range order and encodes the charts.

Source scene storage stays immutable and alive until destruction because retained CPU texture bytes are borrowed. Discard obsolete revision results before publication; transfer a completed bake to the composition owner.

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

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

class ludus::graphics::renderer::StaticLightingBake final

Methods¶

StaticLightingBake¶

LUDUS_INLINE ludus::graphics::renderer::StaticLightingBake::StaticLightingBake() noexcept=default

Construct an unbound job without allocation.

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

~StaticLightingBake¶

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

Release only CPU storage; must not race any other call. An in-flight scheduled bake is cancelled and drained through its JobSystem first; this blocks until running ranges reach their next sample boundary.

Warning

Destroying an in-flight bake from a job callback is a fatal contract violation.

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

StaticLightingBake¶

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

Worker job identity cannot be copied.

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

operator=¶

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

Worker job identity cannot be assigned.

Related types: StaticLightingBake

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

Initialize¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::Initialize(const resources::SceneDefinition &scene, const StaticLightingBakeDescription &description) noexcept

Build an owned world-space BVH and triangle chart accumulators on a worker.

Precondition

scene satisfies SceneDefinition::Decode bounds and stays immutable during the job. Legacy empty bake coordinates are accepted; its upload adapter must assign the shared triangle chart helper coordinates to deindexed mesh vertices. Returns Pending on accepted preparation; failure preserves an unbound job.

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

Step¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::Step(foundation::uint32 maxPathSamples) noexcept

Evaluate at most maxPathSamples complete cosine paths; positive count required. Pending keeps uncommitted charts private; Ready means all charts are encoded. Each path has bounded depth; initialization/final encoding belong on a worker. Invalid contributions permanently fail this candidate; never publish it.

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

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

GetChart¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::GetChart(foundation::usize objectIndex, StaticLightingChart &outChart) const noexcept

Borrow one placed object's completed linear chart; no allocation or GPU call. NotReady/invalid index preserves outChart. DirectLightId for uploaded BakedLighting must be zero: charts contain static area/environment direct diffuse plus indirect irradiance.

Related types: foundation::usize · rhi::RasterStatus · StaticLightingChart

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

Submit¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::Submit(foundation::threading::JobSystem &inoutSystem, const resources::SceneDefinition &scene, const StaticLightingBakeDescription &description, const StaticLightingScheduleDescription &schedule={}) noexcept

Submits preparation and range evaluation of an unbound bake to a JobSystem.

Copies the description, including every Surfaces override, before returning. Validation and preparation run in the first job, so their failures are reported by Poll or Finish. With zero workers the whole bake runs inside this call; Poll or Finish is still required to merge it. Step is unavailable for a scheduled bake.

Parameter	Description
`inoutSystem`	Initialized system with no graph in flight. It must outlive this bake; do not reinitialize it while this bake is in flight.
`scene`	Source scene; immutable and alive until this bake is destroyed.
`description`	Transport quality and provenance, validated as for Initialize.
`schedule`	Range decomposition.

Returns

Pending once submitted. InvalidState when already initialized or submitted, or when the system is uninitialized, busy, or called from a job callback; InvalidDescription for an invalid range count or Surfaces view; or OutOfMemory. Failure leaves the bake unbound.

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

Poll¶

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

Nonblocking completion check for a scheduled bake, on the owner thread.

Returns Pending while any job is unresolved. Once every job is resolved, it releases the graph through JobSystem::Wait without helping, merges range results in stable order and encodes all charts on the calling thread.

Returns

Pending; Ready when every chart is encoded; NotReady after cancellation; the first preparation or range failure in range order; or InvalidState for a bake that was not submitted, or a call from a job callback. Later calls return the same final status.

Related types: rhi::RasterStatus

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

Finish¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::Finish() noexcept

Blocking form of Poll: waits for the submitted graph, helping execute ready jobs.

Returns

As for Poll, never Pending.

Related types: rhi::RasterStatus

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

Cancel¶

void ludus::graphics::renderer::StaticLightingBake::Cancel() noexcept

Requests cooperative cancellation of a scheduled bake; no effect otherwise.

Ranges that have not started are skipped, and running ranges stop at their next sample boundary. Poll or Finish then returns NotReady, unless every job had already completed. Call on the owner thread while the system is initialized.

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

GetProgress¶

void ludus::graphics::renderer::StaticLightingBake::GetProgress(StaticLightingBakeProgress &outProgress) const noexcept

Reads evaluated and total path samples.

Scheduled progress is a relaxed sum of per-range counters advanced once per completed triangle, so it is monotonic but may lag the work in flight.

Parameter	Description
`outProgress`	Receives the counts; zero for an unbound bake.

Related types: StaticLightingBakeProgress

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

GetProfile¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::GetProfile(StaticLightingBakeProfile &outProfile) const noexcept

Reads phase durations of a scheduled bake once Poll or Finish has merged it.

Returns

Ready, including after cancellation or failure; Pending while in flight; or InvalidState for a bake that was not submitted. Pending and InvalidState preserve outProfile.

Related types: rhi::RasterStatus · StaticLightingBakeProfile

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

GetDiagnostics¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::GetDiagnostics(StaticLightingBakeDiagnostics &outDiagnostics) const noexcept

Reads the input problems preparation tolerated, such as skipped zero-area triangles.

Available as soon as preparation completes, while ranges are still running, so a caller can warn its user and offer Cancel before the bake finishes. Callable on the owner thread at any time; it never blocks or touches jobs.

Parameter	Description
`outDiagnostics`	Receives the counts on Ready; preserved otherwise.

Returns

Ready once preparation has succeeded; Pending while a scheduled preparation is unresolved; NotReady when preparation was cancelled or failed; InvalidState for an unbound bake.

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

GetSkippedTriangleCount¶

rhi::RasterStatus ludus::graphics::renderer::StaticLightingBake::GetSkippedTriangleCount(foundation::usize objectIndex, foundation::uint32 &outSkippedTriangleCount) const noexcept

Reads how many zero-area triangles of one placed object the bake skipped.

Available under the same conditions as GetDiagnostics, so a caller can name the affected objects while the bake runs. Callable on the owner thread; never blocks.

Parameter	Description
`objectIndex`	Index into SceneDefinition::Objects.
`outSkippedTriangleCount`	Receives the count on Ready; preserved otherwise.

Returns

As for GetDiagnostics, or InvalidDescription for an out-of-range index.

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

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