ludus::graphics::renderer::Renderer¶

Class

Portable flat/unlit/lit renderer, one owner thread per device. Setup copies data and may allocate/create GPU resources. Repeated Submit creates no renderer resources or heap allocations; RHI retains accepted work through completion. Setup/release and destruction require a closed RHI frame; DrawView/DrawPresentation require an acquired open frame. Reset before destroying the device. See the portable scene submission section in docs/architecture/renderer-systems.md for the canonical guide.

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

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

class ludus::graphics::renderer::Renderer final

Members¶

internal::RenderGraphDeferredPass¶

friend class internal::RenderGraphDeferredPass

Grants the renderer-owned deferred resolve access to immutable view/material bindings.

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

internal::RenderGraphRayPass¶

friend class internal::RenderGraphRayPass

Grants graph camera transactions access to staged GPU preview parameters.

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

Methods¶

Renderer¶

ludus::graphics::renderer::Renderer::Renderer() noexcept

Construct an uninitialized renderer; no allocation or global registration.

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

~Renderer¶

ludus::graphics::renderer::Renderer::~Renderer()

Release renderer ownership; submitted GPU uses retain their own RHI leases.

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

Renderer¶

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

Renderer identity and owner thread cannot be copied.

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

operator=¶

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

Renderer identity and owner thread cannot be assigned.

Related types: Renderer

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

Initialize¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Initialize(rhi::DeviceHandle device, const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment, const Limits &limits={}) noexcept

Initialize on a ready portable-raster device using the shipped renderer_flat.slang program or an authored program with the same six-location interface. Ready/Pending publishes renderer ownership; failures leave it uninitialized. Shader inputs must match six shipped locations. Bindings, when present, must be constant scalar read-only uniform buffers (a bound flat program): one layout merges both stages, a binding number shared by both stages needs an equal MinSize, and every flat pipeline uses it. Items then select a UniformSet or zero-filled defaults.

Parameter	Description
`device`	Borrowed ready device, which must outlive this renderer.
`vertex`	Cooked vertex description from the installed shader helper.
`fragment`	Cooked fragment description from the same flat program.
`limits`	Copied capacities and host budget; invalid/overflowing requests preserve uninitialized state.

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

Poll¶

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

Advance asynchronous shader/layout/pipeline setup without blocking. Ready permits scene setup. Pending/failure retains ownership until Reset; no automatic backend switch.

Related types: rhi::RasterStatus

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

InitializeGrid¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::InitializeGrid(const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment) noexcept

Opt in to the analytic world grid after Initialize is Ready, using the shipped renderer_grid.slang stages. A visible ViewDescription::WorldGrid then draws one world-space plane whose fragment stage computes antialiased lines, plus one ribbon for the axis off the plane, instead of 165 ribbons. Views prepared before this call keep their ribbons. Pending shaders make PrepareView return Pending for grid views; failed shaders fall back to ribbons. Unsupported with uniform-bound or visibility flat programs. Between frames, owner thread.

Parameter	Description
`vertex`	Cooked renderer_grid vertex stage: twelve locations, no bindings.
`fragment`	Cooked renderer_grid fragment stage: no inputs or bindings.

Returns

Ready, Pending while the shaders are created, or the failure; the ribbon grid is unaffected.

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

EnableReferenceRendering¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::EnableReferenceRendering(const rhi::ShaderDescription &, const ReferenceRenderingOptions &) noexcept

Opt in to retained CPU geometry and the selected RT0/RT1 traversal before any meshes or material versions are live. Native mode requires ready optional RHI ray support and the installed fixed query shader; CpuOracle ignores the shader explicitly. Failure preserves disabled state. Owner-thread/between-frames only.

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

EnableReferenceRendering¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::EnableReferenceRendering(const rhi::RasterShaderDescription &trace, const rhi::RasterShaderDescription &reduce, const ReferenceRenderingOptions &options) noexcept

Opt in to the GPU-compute RT1 reference before any meshes or material versions are live. Retains the same CPU geometry/material inputs as CpuOracle; captures then traverse the median BVH and integrate transport on the device, without native rays.

Parameter	Description
`trace`	Cooked `renderer_reference` compute kernel from the installed helper.
`reduce`	Cooked `renderer_reference_reduce` kernel from the same source.
`options`	Traversal must be GpuCompute with positive CPU and GPU byte budgets.

Returns

Ready once shaders are accepted (pipelines finish while captures set up); Unsupported without negotiated compute; InvalidDescription for another traversal or reflected bindings that differ from the frozen kernel ABI. Failure preserves disabled state. Owner-thread/between-frames only.

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

DisableReferenceRendering¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::DisableReferenceRendering() noexcept

Cancel reference jobs, detach their accepted native work and drop retained CPU mesh/material copies. Raster versions remain usable. Re-enabling requires reauthoring meshes/materials after all existing incarnations are released. Owner-thread/between-frames only; no GPU wait or device capability switch. InvalidState while GPU preview owns retained input setup; Reset releases both services. Never disables preview input retention implicitly.

Related types: rhi::RasterStatus

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

BeginReferenceCapture¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::BeginReferenceCapture(Snapshot, const ReferenceCaptureDescription &, ReferenceCapture &) noexcept

Freeze all opaque/masked snapshot objects and exact surface/texture versions, including offscreen objects and full-detail geometry. Overlays are excluded. Unlit/error surfaces or missing CPU texture shadows return Unsupported; uninitialized mips return InvalidDescription, pending uploads NotReady. Missing geometry, capacity and allocation failures preserve null output. Ready/Pending publishes one of at most four renderer-owned capture jobs. Native build readiness and progressive samples advance explicitly afterward.

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

AdvanceReferenceCapture¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::AdvanceReferenceCapture(ReferenceCapture) noexcept

Advance at most one tile stage without blocking. Pending means native work or further stages/samples remain; Ready means the requested target is complete. Failed contributions leave that tile's old sums/counts intact and identify the offending pixel/depth. Owner-thread/between-frames only; no raster frame submission, denoising, silent fallback or synchronous GPU readback occurs.

Related types: rhi::RasterStatus · ReferenceCapture

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

AdvanceReferenceCapture¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::AdvanceReferenceCapture(ReferenceCapture handle, rhi::SurfaceHandle surface) noexcept

Advance one GPU-compute stage without blocking: poll setup, submit one sample for every pixel as compute work in a frame of surface, or poll its status/pixel readback. CpuOracle/NativeQueries captures ignore surface and behave as the overload above.

Parameter	Description
`handle`	Live capture of this renderer.
`surface`	Device surface whose frame carries dispatches; a null surface returns InvalidDescription when a GpuCompute dispatch is due, without failing it.

Returns

Pending while setup, dispatches or readbacks remain; Ready at the target once its committed sums are read back. A pixel with an invalid contribution keeps its committed sums; the capture then fails after reading back every pixel.

Related types: rhi::RasterStatus · ReferenceCapture · rhi::SurfaceHandle

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

UpdateReferenceCapture¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::UpdateReferenceCapture(ReferenceCapture, Snapshot, const ReferenceCaptureDescription &) noexcept

Update the frozen integral transactionally. Snapshot, camera, image extent, lights, mip, seed or integrator changes reset accumulation; a TargetSamples change alone continues it. Failure preserves the previous image/job. The identical request retries a failed uncommitted tile with the same addresses. Ready/Pending publishes copied input; caller arrays need not remain alive.

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(ReferenceCapture) const noexcept

Query progressive completion without advancing CPU path stages or polling native setup/work (AdvanceReferenceCapture performs that bounded polling). Pending/Failed remain owned; Update can retry a failed tile or Release cancels it. Invalid identity returns InvalidHandle. Owner-thread only.

Related types: rhi::RasterStatus · ReferenceCapture

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

GetReferenceCaptureInfo¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetReferenceCaptureInfo(ReferenceCapture, ReferenceCaptureInfo &) const noexcept

Copy bounded progress and profile evidence. Failure preserves output; valid failed captures still report their diagnostic counters. Owner-thread only.

Related types: rhi::RasterStatus · ReferenceCapture · ReferenceCaptureInfo

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

EnableGpuPreview¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::EnableGpuPreview(const rhi::RasterShaderDescription &compute, const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment, const GpuPreviewOptions &) noexcept

Enable GPU preview before creating meshes/materials, with a Ready renderer and negotiated Compute/StorageVertex. Select the installed native-query or explicit software-triangle preview recipe; a RayScene shader binding additionally requires enabled native rays. Unsupported devices reject without selecting another traversal recipe or CPU rendering fallback. Uses the compute artifact's reflected positive X/Y workgroup dimensions; Z must be 1. Zero dimensions reject with InvalidDescription; device workgroup/dispatch limits reject with Unsupported. Image extents need not divide evenly into groups. Copies options; positive budgets and finite exposure are required. Owner-thread, between frames. Failure preserves the previous disabled state. Pending owns setup and requires PollGpuPreview; Reset releases it. Optional options.StorageBuffers extend the compute ABI in user slots 6/7; descriptors are copied. Every job owns independent zero-initialized storage, retained across dispatches and retired on job release. Stride/access must match the supplied shader; checked byte counts obey CPU/GPU/device budgets. CPU input retention must be disabled before enable; it is enabled internally without CPU tracing.

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

EnableTriangleRayPipeline¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::EnableTriangleRayPipeline(const rhi::RasterShaderDescription &compute, const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment, const GpuPreviewOptions &options) noexcept

Enable the graph triangle kernel with flat opaque snapshots, without lit-material programs. Same GPU setup, budgets and lifetime as EnableGpuPreview; the compute stage must implement the authored triangle-ray ABI. BeginGpuPreview then copies flat tint/geometry only, with no lighting or CPU tracing. Ready/Pending owns setup; failure preserves the disabled state.

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

PollGpuPreview¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PollGpuPreview() noexcept

Poll asynchronous GPU preview setup and retire cancelled completed jobs on the owner thread between frames. No waiting; failure remains observable until Reset.

Related types: rhi::RasterStatus

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

BeginGpuPreview¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::BeginGpuPreview(Snapshot, const ReferenceCaptureDescription &, GpuPreview &, const RenderGraphSceneDescription *graphSceneOrNull=nullptr, const GpuPreviewGraphInvocation *invocationOrNull=nullptr) noexcept

Copy an admitted static snapshot/camera/material integral into owned GPU buffers. Four live jobs; old/new GPU bytes share the enable-time budget. RT1 supported RGB reflection/opacity/emission only, fixed retained mip; overlay items are excluded. No baked/atlas lighting, transmission or deformation. Target <=4096, depth <=8, pixel count <=2^24; negotiated storage limits can be tighter. RGB emissive triangles, up to 128 analytic lights and constant/HDR environment. Ready/Pending publish ownership into a null output; rejection preserves it. All caller owners may detach after success. Changing camera/content/exposure creates a new job and restarts accumulation. Setup can allocate/upload; never shades.

Parameter	Description
`graphSceneOrNull`	Optional graph scene, consumed synchronously instead of Snapshot. Requires EnableTriangleRayPipeline. Material defaults/errors follow its declared policy.
`invocationOrNull`	Optional graph-only sample limit, callback and borrowed buffers. Requires EnableTriangleRayPipeline; null retains the capture description's sample limit. A nonzero Program or nonempty Buffers requires the persistent ABI.

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

AdvanceGpuPreview¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::AdvanceGpuPreview(GpuPreview, rhi::SurfaceHandle, rhi::SubmissionToken &) noexcept

Dispatch one full-image GPU sample, shade/accumulate/tone-map on GPU, and rasterize GPU-produced colors into an available output texture. Ordered GDI dependencies include compute-to-fragment storage reads and output export. Never reads rays, radiance or pixels to host. Owner-thread, closed frame; completion starts null. NotReady means an earlier producer is pending or both output images are leased. Success publishes producing completion; acquired images are never overwritten.

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

PrepareGpuPreviewGraph¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrepareGpuPreviewGraph(GpuPreview job, rhi::TextureHandle target, rhi::OrderedGraph &outGraph, const VisibilityRasterPass *visibilityOrNull=nullptr) noexcept

Prepare a one-sample GPU job's compute and image commands for an external graph-owned target. Owner thread, between frames. The target must be a ready offscreen RGBA8 attachment with the job's exact extent. Copies/retains resource uses in a new compiled OrderedGraph; never shades. The caller encodes it into a frame, tracks the actual EndFrame completion, and rebuilds it only after that producer finishes. The GPU job/target outlive graph encoding; RHI retains submitted resources through completion. Job progress/preview frame leases are unaffected.

Parameter	Description
`job`	Ready GPU job; do not also AdvanceGpuPreview this job.
`target`	Borrowed attachment, cleared/stored in color; private depth is discarded.
`visibilityOrNull`	Optional visibility producer, appended before the ray dispatch; source differs from target.
`outGraph`	Null graph receives the commands. Failure preserves it and releases temporary leases.

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

AppendVisibilityView¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::AppendVisibilityView(PreparedView handle, rhi::OrderedGraph &inoutGraph, const rhi::RasterPassDescription &attachment, rhi::GraphVersion previous, rhi::GraphVersion &outWritten) noexcept

Append one visibility-ABI view to an uncompiled graph between frames. No allocation survives outside the graph; partial failure leaves the caller responsible for discarding the graph.

Parameter	Description
`handle`	Ready opaque visibility view; no authored uniforms, materials or world grid.
`inoutGraph`	Caller-owned uncompiled ordered graph on this renderer's device.
`attachment`	RGBA8/private-depth attachment, Clear/Store in both aspects.
`previous`	Imported version of attachment.Color.
`outWritten`	Receives the next written version on success; preserved on failure.

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

PrepareGpuPreviewGraphSequence¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrepareGpuPreviewGraphSequence(foundation::BorrowedView< const GpuPreview > jobs, foundation::BorrowedView< const rhi::TextureHandle > targets, rhi::OrderedGraph &outGraph, const VisibilityRasterPass *visibilityOrNull=nullptr) noexcept

Compile a consecutive sequence of ready graph ray jobs into one ordered graph. Owner thread, between frames. Jobs and targets have equal nonzero lengths (at most four). Shared buffers and targets import once and advance explicit versions, preserving cross-pass RAW/WAR/WAW dependencies. Storage history is retained across executions; no CPU readback. Caller keeps jobs/targets alive through encoding and tracks actual frame completion before rebuilding. The null output is unchanged on rejection; temporary graph leases are released.

Parameter	Description
`visibilityOrNull`	Optional opaque visibility producer, appended once before the first ray dispatch. Every job then samples that same written color/depth image, so the source must not be any job's target.
`jobs`	Ready jobs from this Renderer; never also AdvanceGpuPreview them.
`targets`	Borrowed ready RGBA8 attachments with each job's exact extent.
`outGraph`	Receives compiled commands on Ready; caller discards or encodes once.

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

GetGpuPreviewInfo¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetGpuPreviewInfo(GpuPreview, GpuPreviewInfo &) noexcept

Poll GPU completion and copy progress; no waiting or GPU-buffer readback. Ready/Pending copy progress; rejection preserves output. Owner-thread, between frames. Pending means creation or producer work is outstanding.

Related types: rhi::RasterStatus · GpuPreview · GpuPreviewInfo

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

AcquireGpuPreviewFrame¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::AcquireGpuPreviewFrame(GpuPreview, GpuPreviewFrame &, GpuPreviewImage &) noexcept

Acquire latest GPU-complete output. Ready fills a null frame lease and copied image; Pending/NotReady/rejection preserves both outputs. The same output cannot be acquired twice. Retain through external sampling completion.

Related types: rhi::RasterStatus · GpuPreview · GpuPreviewFrame · GpuPreviewImage

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(GpuPreviewFrame &) noexcept

Return an acquired output lease and clear identity.

Precondition

Every external GPU use completed and its RHI interoperability lease was released. Never releases on behalf of Qt; stale/foreign frames preserve input. Owner-thread, between frames.

Related types: rhi::RasterStatus · GpuPreviewFrame

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(GpuPreview &) noexcept

Cancel future preview work and clear owner. Acquired frames keep GPU scene storage alive until returned. Pending producers keep their GPU budget until PollGpuPreview or the next Begin retires them after completion. Stale/foreign jobs preserve input. Owner-thread, between frames.

Related types: rhi::RasterStatus · GpuPreview

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

CopyReferencePixels¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::CopyReferencePixels(ReferenceCapture, ReferencePixel *output, ludus::foundation::usize count) const noexcept

Copy exactly Width*Height raw unexposed means/AOVs and committed counts. Incomplete images expose zero/unequal counts; native pending work never enters the copied data. Failure preserves output. No allocation or GPU wait. GpuCompute copies its latest read-back sums, which may trail Info.MinimumSamples between periodic readbacks; a Ready capture's pixels are fully read back.

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

EncodeReferenceHdr¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::EncodeReferenceHdr(ReferenceCapture, ludus::foundation::uint8 *output, ludus::foundation::usize capacity, ludus::foundation::usize &written) const noexcept

Encode the versioned LUHDR01 little-endian FP32 RGB/count capture and frozen profile metadata into caller storage. Required bytes and PFM conversion are documented in the renderer guide. Capacity/other failure preserves output and written; partial images retain exact per-pixel counts. No file I/O/wait.

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(ReferenceCapture &) noexcept

Cancel future samples and detach capture ownership. Accepted native batches retire through completion; invalid identity preserves handle, success clears it. Snapshot/material/mesh references release exactly once. Between frames.

Related types: rhi::RasterStatus · ReferenceCapture

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

InitializeViews¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::InitializeViews(const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment) noexcept

Enable L1 surface/offscreen reverse-Z and target composition after Initialize is Ready. Uses the shipped renderer_composite.slang stages; Ready/Pending publishes setup ownership. Failure preserves the usable L0 profile; failed published setup requires Reset.

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

PollViews¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PollViews() noexcept

Advance L1 resource/pipeline creation on later owner turns; no GPU wait or backend switch.

Related types: rhi::RasterStatus

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

PrewarmMaterialProgram¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrewarmMaterialProgram(const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment, MaterialProgram &output) noexcept

Validate the installed unlit material ABI and prewarm every legal surface/offscreen conventional/reverse-Z/painter pipeline through R2's bounded cache, between frames. Two logical program versions; all six pipelines must be Ready before material creation. Null output required; Ready/Pending grants ownership. Failures preserve output. No driver pipeline work occurs in DrawView/Submit; no persistent native cache is implied.

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(MaterialProgram handle) noexcept

Advance candidate prewarming between frames; Ready is immutable and allocation-free.

Related types: rhi::RasterStatus · MaterialProgram

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(MaterialProgram &handle) noexcept

Detach program ownership; earlier material/snapshot/GPU uses retain its resources.

Related types: rhi::RasterStatus · MaterialProgram

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

CreateMaterial¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::CreateMaterial(MaterialProgram program, const MaterialDescription &description, MaterialVersion &output) noexcept

Copy parameters, sampler and exact sampled view; eight logical material versions. Requires a Ready owned program and Ready RGBA8 texture (or null white fallback). Ready/Pending grants ownership; invalid input/capacity preserves null output.

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(MaterialVersion handle) noexcept

Complete candidate binding creation between frames, without blocking.

Related types: rhi::RasterStatus · MaterialVersion

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

PublishMaterial¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PublishMaterial(MaterialVersion &candidate, MaterialVersion &current) noexcept

Atomically publish a Ready candidate and detach current (which may be null). Both are owned by this renderer and must be different. Failure preserves both; earlier snapshots/views retain current's old contents. Invalid reload never swaps.

Related types: rhi::RasterStatus · MaterialVersion

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(MaterialVersion &handle) noexcept

Detach material ownership; earlier snapshot/view/GPU uses retain the exact version.

Related types: rhi::RasterStatus · MaterialVersion

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

InitializeLighting¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::InitializeLighting(const rhi::RasterShaderDescription &outputVertex, const rhi::RasterShaderDescription &outputFragment, const rhi::RasterShaderDescription &shadowFragment) noexcept

Enable linear lighting output and opaque shadow rendering after InitializeViews is Ready. Uses renderer_output.slang and renderer_shadow.slang; Ready/Pending owns setup resources. HdrColor enables prewarmed RGBA16F flat pipelines; RGBA8 remains the authored fallback. Failures preserve earlier profiles; a failed published setup requires Reset.

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

PollLighting¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PollLighting() noexcept

Advance lighting setup without blocking, between frames.

Related types: rhi::RasterStatus

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

PrewarmLitProgram¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrewarmLitProgram(const rhi::RasterShaderDescription &vertex, const rhi::RasterShaderDescription &fragment, const rhi::RasterShaderDescription &shadowFragment, MaterialProgram &outProgram, const rhi::RasterShaderDescription *depthOrNull=nullptr, rhi::RasterFillMode fillMode=rhi::RasterFillMode::Solid) noexcept

Validate renderer_lit.slang or renderer_clustered.slang and prewarm linear RGBA8/RGBA16F plus masked shadows. Clustered programs require their reflected binding/uniform range; pass LitMaterialDescription::Clusters when creating their materials. Unsupported capabilities reject. Shadow fragment uses the same typed uniform schema and a subset of the lit bindings. Sixteen vertex locations required; HDR variants are omitted when HdrColor is false. Ready/Pending grants program ownership; failure preserves null output.

Parameter	Description
`vertex`	Cooked geometry stage shared by color and optional depth pipelines.
`fragment`	Cooked material-shading stage with the selected lit ABI.
`shadowFragment`	Coverage stage with the matching material uniform schema.
`outProgram`	Receives an owned program on Ready/Pending; preserved on failure.
`depthOrNull`	Optional void depth fragment using the same retained vertex stage and binding layout. It is prewarmed for conventional-depth RGBA8 DrawDepthView calls.
`fillMode`	Rasterization of the colour and depth pipelines; shadow pipelines always fill. Lines draws triangle edges for MaterialDebugView::Wireframe and returns Unsupported unless rhi::RasterCapabilities::HasLineFill.

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

CreateLitMaterial¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::CreateLitMaterial(MaterialProgram program, const LitMaterialDescription &description, MaterialVersion &output, LightSelection &report) noexcept

Copy an immutable lit material and normalized bounded light list, between frames. Report and null output are preserved on failure. Shadows must be rendered and Ready; bake/shadow views are retained even after their owners are released.

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

PrepareShadowAtlas¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrepareShadowAtlas(Snapshot handle, const ShadowAtlasDescription &description, ShadowAtlas &output) noexcept

Copy light regions and prepare retained conventional-depth caster views/atlas, between frames. Invalid gutters/overlap, unsupported masked-unlit casters or incomplete/noncanonical cube maps preserve null output. Ready/Pending grants ownership; drawing is required before material sampling is admitted.

Related types: rhi::RasterStatus · ShadowAtlas · ShadowAtlasDescription · Snapshot

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(ShadowAtlas handle) const noexcept

Poll retained atlas/instance setup. Ready does not mean it has been rendered yet.

Related types: rhi::RasterStatus · ShadowAtlas

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

DrawShadowAtlas¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::DrawShadowAtlas(ShadowAtlas handle, ludus::foundation::uint32 reservedDraws=0) noexcept

Render all prepared regions in an acquired frame; no allocation or shader creation.

Precondition

Call before indexed draws in this frame; reservedDraws budgets the subsequent scene/composition draws. Aggregate packet overflow preserves the unrendered candidate before GPU work; other GPU failures may be partial. Configure enough Views for every region and retained prior incarnation. Only one accepted draw per immutable atlas. A partial failure permanently rejects reuse; recreate a candidate. Caller must end/submit the frame before material creation.

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

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(ShadowAtlas &handle) noexcept

Detach atlas ownership; materials retain the exact rendered texture and caster version.

Related types: rhi::RasterStatus · ShadowAtlas

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

PrepareLightingPresentation¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrepareLightingPresentation(rhi::TextureHandle source, const ViewMapping &mapping, const LightingOutput &lighting, Presentation &output) noexcept

Prepare retained linear scene/display source and immutable exposure/output parameters. Accepts RGBA8 or supported RGBA16F attachments. Encode=false selects a linear display target for UI blending; Encode=true permits a final sRGB-encoded RGBA8Unorm texture for external presentation. Consumers must not encode that again.

Related types: rhi::RasterStatus · LightingOutput · Presentation · ViewMapping · rhi::TextureHandle

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

DrawLightingPresentation¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::DrawLightingPresentation(Presentation handle, const rhi::RasterPassDescription &description={ .ColorLoad=rhi::RasterLoad::Load, }) noexcept

Compose a Ready lighting presentation in an acquired frame; select surface or linear RGBA8. Actual surface encoding selects shader or hardware conversion, exactly once. No blending. Use Encode=false for a linear UI intermediate. Encode=true encodes once for RGBA8Unorm offscreen output, or selects shader/hardware surface encoding.

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

Reset¶

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

Release all public identities/resources; accepted CPU/GPU uses retire through RHI.

Precondition

Owner thread, no open frame; invalidates every previously issued logical handle.

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

GetConfiguredLimits¶

Limits ludus::graphics::renderer::Renderer::GetConfiguredLimits() const noexcept

Copied configured capacities, or defaults while uninitialized. Owner-thread only.

Related types: Limits

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

GetHostBytes¶

ludus::foundation::usize ludus::graphics::renderer::Renderer::GetHostBytes() const noexcept

Reserved renderer metadata/workspace bytes, zero while uninitialized. Exclusions match Limits::HostBytes; this is requested storage, not physical memory usage.

Related types: ludus::foundation::usize

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

GetUniformBytes¶

ludus::foundation::usize ludus::graphics::renderer::Renderer::GetUniformBytes() const noexcept

Bytes a bound flat program's uniform set copies: each binding's declared stage MinSize, concatenated in ascending binding order. Zero for an unbound program or before Initialize.

Related types: ludus::foundation::usize

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

CreateUniformSet¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::CreateUniformSet(ludus::foundation::BorrowedView< const ludus::foundation::uint8 > bytes, UniformSet &output) noexcept

Copy per-draw uniform blocks into an immutable buffer and binding snapshot, between frames.

Parameter	Description
`bytes`	Exactly GetUniformBytes() target-packed bytes; need only survive the call.
`output`	Null set receiving ownership on Ready/Pending.

Returns

NotReady before setup is Ready, InvalidDescription for an unbound program or a wrong size, CapacityExceeded when Limits::UniformSets are live; failures preserve output.

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(UniformSet handle) noexcept

Advance uniform buffer/binding creation without blocking; stale or foreign sets reject.

Related types: rhi::RasterStatus · UniformSet

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(UniformSet &handle) noexcept

Detach set ownership and clear handle; existing snapshots/views retain the exact version.

Related types: rhi::RasterStatus · UniformSet

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

CreateMesh¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::CreateMesh(const MeshDescription &description, Mesh &output) noexcept

Copy geometry and derive exact mesh-local bounds. Null output required. Ready/Pending publishes mesh ownership; rejected input preserves output.

Related types: rhi::RasterStatus · Mesh · MeshDescription

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(Mesh handle) const noexcept

Poll owned mesh creation; stale/foreign or detached public identities reject.

Related types: rhi::RasterStatus · Mesh

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(Mesh &handle) noexcept

Detach mesh ownership and clear handle. Existing snapshots/views retain the old geometry.

Related types: rhi::RasterStatus · Mesh

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

CreateSnapshot¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::CreateSnapshot(const SceneItem *items, ludus::foundation::usize count, Snapshot &output) noexcept

Copy all items and retain mesh incarnations; accepts zero count with null items. Invalid IDs, duplicate source IDs, nonfinite transforms/colors, capacity or unready meshes reject atomically, preserving output and all existing scenes. Null output required.

Related types: ludus::foundation::usize · rhi::RasterStatus · SceneItem · Snapshot

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

ReplaceSnapshot¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::ReplaceSnapshot(const SceneItem *items, ludus::foundation::usize count, Snapshot &current) noexcept

Atomically replace an owned snapshot with a complete copied dynamic scene. Earlier views retain exact snapshot/mesh versions. Admission failure preserves current; requires one free snapshot slot, between frames.

Related types: ludus::foundation::usize · rhi::RasterStatus · SceneItem · Snapshot

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(Snapshot &handle) noexcept

Detach snapshot ownership and clear handle; existing prepared views remain valid.

Related types: rhi::RasterStatus · Snapshot

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

PrepareView¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PrepareView(Snapshot handle, const ViewDescription &description, PreparedView &output, ViewReport &report) noexcept

Cull, safely order and instance a copied view during setup, retaining the snapshot. Opaque mesh sorting is confined to mutually disjoint projected-bound runs; overlapping objects and overlays preserve source order. Reference disables sorting/culling/instancing. Ready/Pending publishes view ownership and report; failures preserve both outputs.

Parameter	Description
`handle`	Owned snapshot incarnation.
`description`	Copied view transform and reference policy.
`output`	Null prepared view receiving ownership; Pending requires GetStatus before Submit.
`report`	Copied visibility/draw/source diagnostics, unchanged on rejection.

Related types: rhi::RasterStatus · PreparedView · Snapshot · ViewDescription · ViewReport

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(PreparedView handle) const noexcept

Poll the prepared immutable instance buffer without blocking.

Related types: rhi::RasterStatus · PreparedView

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

Submit¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Submit(PreparedView handle, rhi::SurfaceHandle surface, rhi::SubmissionToken &completion) noexcept

Record/submit conventional-depth packets with R1 clear/depth behavior. Reverse-Z views return InvalidDescription; use DrawView in an acquired shared frame.

Parameter	Description
`handle`	Ready view. It remains reusable after successful submission.
`surface`	Borrowed surface owned by the initialized device.
`completion`	Null completion receiving accepted GPU work; may be published on partial failure. NotReady preserves a finished batch for retry. Other preflight failures drop that batch. Returned failure is independent of a possible non-null completion (R2 partial-work contract).

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

DrawView¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::DrawView(PreparedView handle, const rhi::RasterPassDescription &description) noexcept

Draw a ready view in an acquired frame using explicit attachment/load/store/rectangles. L1 must be Ready. Null pass.Color selects the acquired surface; offscreen targets must be linear RGBA8 attachments. View depth chooses Less/Greater and the matching clear. Clear is whole-attachment regardless of viewport/scissor; use offscreen composition for independently cleared neighboring views. Accepted packets retain resources until the caller ends the frame with R2 EndFrame. Later rejection does not undo earlier work.

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

DrawDepthView¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::DrawDepthView(PreparedView handle, const rhi::RasterPassDescription &description) noexcept

Draw opaque depth using each material's prewarmed void fragment and the exact retained geometry stage of the color pass. Skips overlays/grid; no material evaluation or color output. Requires an offscreen RGBA8 attachment, conventional depth and depth-enabled lit programs.

Precondition

Owner thread inside an acquired frame; view and attachment must be Ready.

Returns

Unsupported before recording when a packet lacks a prewarmed depth program.

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

PreparePresentation¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::PreparePresentation(rhi::TextureHandle source, const ViewMapping &mapping, Presentation &output) noexcept

Copy presentation geometry/mapping and retain the sampled linear RGBA8 attachment. Four presentation slots, one vertex buffer and binding snapshot each; shared RHI budgets may exhaust earlier. Ready/Pending publishes output; failure preserves it. Source must already be Ready, but may have undefined contents until a later draw. Its pixel aspect must equal the mapping's logical aspect; render resolution may differ.

Parameter	Description
`source`	Owned RHI attachment; may be destroyed after accepted preparation.
`mapping`	Resolved output mapping; recreated explicitly after drawable resize.
`output`	Null presentation receiving ownership.

Related types: rhi::RasterStatus · Presentation · ViewMapping · rhi::TextureHandle

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

GetStatus¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::GetStatus(Presentation handle) noexcept

Advance asynchronous presentation geometry/view/binding creation between frames; may create its binding snapshot once dependencies become Ready. Failure still requires Release.

Related types: rhi::RasterStatus · Presentation

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

DrawPresentation¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::DrawPresentation(Presentation handle) noexcept

Composite into the acquired surface, preserving its defined color outside the mapped viewport/scissor. Undefined sampled color rejects; resize mismatch returns NotReady before changing the current pass. Mapping uses the actual acquired extent. Caller ends the shared frame with R2 EndFrame; no renderer allocations during drawing.

Related types: rhi::RasterStatus · Presentation

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(Presentation &handle) noexcept

Detach presentation CPU ownership; sampled texture/geometry retire after accepted GPU uses.

Related types: rhi::RasterStatus · Presentation

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

Release¶

rhi::RasterStatus ludus::graphics::renderer::Renderer::Release(PreparedView &handle) noexcept

Drop a prepared view and any retry batch; clear handle. GPU retirement remains in RHI.

Related types: rhi::RasterStatus · PreparedView

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

Static methods¶

GetLimits¶

static Limits ludus::graphics::renderer::Renderer::GetLimits() noexcept

Return compatibility defaults; use GetConfiguredLimits for an initialized renderer.

Related types: Limits

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