ludus::graphics::rhi¶

Namespace

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

Enumerations¶

ComputeCachePhase¶

enum class ComputeCachePhase : foundation::uint8

Explicit candidate state, separate from whether a previously published result exists.

Related types: foundation::uint8

Empty¶

Empty

No candidate; an active result may still exist.

Preparing¶

Preparing

Upload/shader/pipeline preparation is pending.

Prepared¶

Prepared

Candidate can build its one encoding graph.

AwaitingSubmission¶

AwaitingSubmission

Graph handed to caller; candidate cannot publish yet.

Executing¶

Executing

Accepted submission is not yet known complete.

Failed¶

Failed

Candidate failed; active result remains available.

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

DeviceStatus¶

enum class DeviceStatus : ludus::foundation::uint8

Result of an explicit device operation; each operation documents output preservation.

Related types: ludus::foundation::uint8

Ready¶

Ready

Operation accepted, or device ready for work.

Pending¶

Pending

Owned startup is in flight; poll GetDeviceInfo without blocking.

Skipped¶

Skipped

Zero-size target skipped acquisition and did not open a frame.

NotReady¶

NotReady

A frame operation was attempted before startup became ready.

InvalidHandle¶

InvalidHandle

A null, destroyed or foreign owner/target was supplied.

InvalidState¶

InvalidState

Busy session, occupied creation output or invalid frame ordering.

InvalidDescription¶

InvalidDescription

Malformed backend selection enum.

Unsupported¶

Unsupported

Unimplemented required workload or backend operation.

Failed¶

Failed

Backend startup/frame operation failed; inspect Startup in DeviceInfo.

DeviceLost¶

DeviceLost

Device loss stopped work; destroy and create a fresh session to recover.

IdentityExhausted¶

IdentityExhausted

Process device-owner identities exhausted; no backend request was launched.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GpuPassKind¶

enum class GpuPassKind : foundation::uint8

Measured native operation. Raster uses the backend's physical-pass stage interval; Compute uses its encoder/dispatch interval. Values are elapsed time, not shader busy time.

Related types: foundation::uint8

Raster¶

Raster

Vertex/fragment stage envelope on Metal, TOP/BOTTOM render-pass interval on Vulkan, or the interval between two bottom-of-pipe samples around a Direct3D 12 raster pass.

Compute¶

Compute

Physical compute operation, including GPU stalls.

RayTracing¶

RayTracing

Native ray-stage/function-table pipeline; Metal measures its compute encoder interval.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

RasterLoad¶

enum class RasterLoad : ludus::foundation::uint8

Full-attachment initialization at a raster pass boundary.

Related types: ludus::foundation::uint8

Clear¶

Clear

Initialize the complete attachment with the specified clear value.

Load¶

Load

Preserve defined contents; undefined contents are an error.

Discard¶

Discard

Previous contents are undefined; partial draws do not initialize the image.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

RasterStore¶

enum class RasterStore : ludus::foundation::uint8

Attachment validity after a raster pass.

Related types: ludus::foundation::uint8

Store¶

Store

Preserve initialized contents for later passes or executions.

Discard¶

Discard

Contents become undefined even when the pass cleared them.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

RasterTextureUse¶

enum class RasterTextureUse : ludus::foundation::uint8

Semantic whole-color-image use, translated privately to backend synchronization.

Related types: ludus::foundation::uint8

Undefined¶

Undefined

Newly allocated storage has no prior use or defined contents.

SampledVertex¶

SampledVertex

Read in the vertex shader.

SampledFragment¶

SampledFragment

Read in the fragment shader.

SampledBoth¶

SampledBoth

Read in either raster shader stage.

SampledCompute¶

SampledCompute

Unfiltered reads in a compute shader; ordered graphs track producer dependencies.

ColorAttachment¶

ColorAttachment

Read/write as a color attachment.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

GraphAccessMode¶

enum class GraphAccessMode : ludus::foundation::uint8

Actual use of a declared buffer range or complete color texture.

Related types: ludus::foundation::uint8

Vertex¶

Vertex

Vertex stream read; range must cover the packet's slice.

Index¶

Index

Index read; range must cover every indexed byte.

Uniform¶

Uniform

Reflected uniform range read.

Sampled¶

Sampled

Reflected texture binding read, including inactive extra bindings.

ColorWrite¶

ColorWrite

Attachment write to a new version; Clear or Discard.

ColorReadWrite¶

ColorReadWrite

Attachment Load of the preceding version and write of a new version.

StorageRead¶

StorageRead

Read-only compute storage range.

StorageReadWrite¶

StorageReadWrite

Read/write compute storage range, writing the next in-place version.

Indirect¶

Indirect

Indexed indirect argument range.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

GraphRoot¶

enum class GraphRoot : ludus::foundation::uint8

Resource roots observable after this execution.

Related types: ludus::foundation::uint8

Export¶

Export

An external consumer will use this version.

History¶

History

Future-frame history write, even if unused by this frame.

Readback¶

Readback

Readback consumer; scheduling/copy-out remains the R2 service's job.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

GraphHazard¶

enum class GraphHazard : ludus::foundation::uint8

Semantic dependency reason, independent of backend synchronization enums.

Related types: ludus::foundation::uint8

ReadAfterWrite¶

ReadAfterWrite

Earlier writer must make data visible to this reader.

WriteAfterRead¶

WriteAfterRead

Earlier reader must finish before this in-place overwrite.

WriteAfterWrite¶

WriteAfterWrite

Ordered in-place writes, even when contents are discarded.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

HostedConsumerRefusal¶

enum class HostedConsumerRefusal : foundation::uint8

Why a HostedSurfaceConsumer stopped showing the game's images.

Related types: foundation::uint8

None¶

None

Not refused.

AdapterMismatch¶

AdapterMismatch

Vulkan: the game renders on another adapter or driver (deviceUUID or driverUUID differ), so opaque memory handles cannot be imported.

UnsupportedHandle¶

UnsupportedHandle

The images use a handle kind this consumer's backend cannot import (for example Mach ports on Linux), or the consumer was started on another API.

ImportFailed¶

ImportFailed

An image could not be imported: the shared surface or memory does not match the announced extent and format, or the native import failed.

ProtocolViolation¶

ProtocolViolation

The game announced a frame of an image it did not share.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/hosted_surface.h

HostedConsumerStatus¶

enum class HostedConsumerStatus : foundation::uint8

Result of a HostedSurfaceConsumer operation.

Related types: foundation::uint8

Empty¶

Empty

No newer frame has arrived since the last AcquireFrame().

Refused¶

Refused

The consumer refused the game's images; GetRefusal() says why. Terminal for the session.

NotConnected¶

NotConnected

The endpoint has no connected window.

InvalidState¶

InvalidState

The call does not apply now: not started, already started, or a frame this consumer does not hold.

InvalidArgument¶

InvalidArgument

The device identity is incomplete or of an API this build has no hosted import for.

Unavailable¶

Unavailable

The target has no hosted surface (browser, Windows) or the consumer could not allocate its state.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/hosted_surface.h

GpuTimingState¶

enum class GpuTimingState : foundation::uint8

State of an optional GPU measurement; sampling never waits for the GPU.

Related types: foundation::uint8

Empty¶

Empty

No requested sample in this session.

Armed¶

Armed

Waiting for or recording the next acquired frame; skipped acquisition keeps it armed.

Pending¶

Pending

Submitted query/command buffer has not completed.

Available¶

Available

Duration is available, including a legitimate quantized zero.

Unavailable¶

Unavailable

Backend/device did not enable its optional timing facility.

Disjoint¶

Disjoint

Clock discontinuity or unrepresentable/invalid timestamps; duration is unavailable.

Failed¶

Failed

Query or command buffer failed; duration is unavailable.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/measurement.h

NativeCalibratedTimestamps¶

enum class NativeCalibratedTimestamps : ludus::foundation::uint8

Vulkan calibrated-timestamp device extension that a source enabled when it created its device.

Related types: ludus::foundation::uint8

None¶

None

Neither extension is enabled; per-pass GPU timings on the admitted device stay duration-only.

Khr¶

Khr

VK_KHR_calibrated_timestamps is enabled on the device.

Ext¶

Ext

VK_EXT_calibrated_timestamps is enabled on the device.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

TextureDimension¶

enum class TextureDimension : ludus::foundation::uint8

Allocation/sampled-view dimensionality; cube faces use +X,-X,+Y,-Y,+Z,-Z order.

Related types: ludus::foundation::uint8

D2Array¶

D2Array

Fixed array of two-dimensional images; layers do not shrink with mips.

Cube¶

Cube

Six square two-dimensional faces.

D3¶

D3

Volume; depth shrinks with each mip and cannot be selected as array layers.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RasterFormat¶

enum class RasterFormat : ludus::foundation::uint8

Original sampled color/data formats; dimensions and uses are independently negotiated.

Related types: ludus::foundation::uint8

Rgba8Unorm¶

Rgba8Unorm

Four unsigned normalized channels, interpreted as linear light.

Rgba8Srgb¶

Rgba8Srgb

Four unsigned normalized channels; RGB decodes sRGB during sampling, alpha remains linear.

R8Unorm¶

R8Unorm

Single unsigned normalized coverage/data channel; sampled only, never an attachment.

Rg8Unorm¶

Rg8Unorm

Two normalized linear data channels; sampled only, never an attachment.

Rgba16Float¶

Rgba16Float

Linear binary16 sampled RGBA; attachment/filter/blend support is capability-gated. Original binary16 upload bits are accepted without conversion; attachment use remains separately enabled.

Bc1RgbaUnorm¶

Bc1RgbaUnorm

BC1 RGBA normalized 4x4 blocks (8 bytes), sampled when enabled; no automatic compression.

Bc3RgbaUnorm¶

Bc3RgbaUnorm

BC3 RGBA normalized 4x4 blocks (16 bytes), sampled when enabled; no automatic compression.

Bc5RgUnorm¶

Bc5RgUnorm

BC5 RG unsigned normalized 4x4 blocks (16 bytes); sampling returns (R,G,0,1). Requires enabled compression support; no normal reconstruction, conversion or compression.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

ProfileRequirement¶

enum class ProfileRequirement : ludus::foundation::uint8

First unmet constraint, in raster-field order, compute-field order, then format array order.

Related types: ludus::foundation::uint8

None¶

None

Every requested constraint was met, or no diagnostic is available yet.

BufferSize¶

BufferSize

Buffer allocation size is insufficient.

TextureDimension¶

TextureDimension

General sampled texture dimension is insufficient.

UniformAlignment¶

UniformAlignment

Uniform offsets require a larger alignment than accepted.

UniformRange¶

UniformRange

Uniform binding range is insufficient.

ResourceCount¶

ResourceCount

Total resource records per kind are insufficient.

DrawCount¶

DrawCount

Draw capacity is insufficient.

BindingCount¶

BindingCount

Binding entry capacity is insufficient.

VertexBufferCount¶

VertexBufferCount

Vertex stream capacity is insufficient.

VertexAttributeCount¶

VertexAttributeCount

Vertex attribute capacity is insufficient.

VertexStride¶

VertexStride

Vertex stride bound is insufficient.

ColorAttachmentCount¶

ColorAttachmentCount

Color attachment capacity is insufficient.

TextureLayerCount¶

TextureLayerCount

Texture layer capacity is insufficient.

StorageRange¶

StorageRange

Storage binding range is insufficient or compute is unavailable.

StorageAlignment¶

StorageAlignment

Storage offsets require a larger alignment than accepted.

WorkgroupSize¶

WorkgroupSize

A local workgroup axis bound is insufficient.

WorkgroupInvocations¶

WorkgroupInvocations

Workgroup invocation capacity is insufficient.

DispatchCount¶

DispatchCount

A dispatch axis bound is insufficient.

Sampled¶

Sampled

Sampled use is unavailable.

PartialViews¶

PartialViews

Requested original-format sampled subrange views are disabled.

AttachmentViews¶

AttachmentViews

Writable mip/layer attachment views are unavailable.

DepthSampled¶

DepthSampled

Private depth sampling is unavailable.

StencilAttachment¶

StencilAttachment

Stencil allocation/testing is unavailable.

StencilSampled¶

StencilSampled

Private stencil sampling is unavailable.

Filterable¶

Filterable

Linear filtering is unavailable.

ColorAttachment¶

ColorAttachment

Color attachment use is unavailable.

Blendable¶

Blendable

Attachment blending is unavailable.

Storage¶

Storage

Storage texture use is unavailable.

CopySource¶

CopySource

General texture-copy source use is unavailable.

CopyDestination¶

CopyDestination

General texture-copy destination use is unavailable.

FormatDimension¶

FormatDimension

The format's requested dimensions exceed its selected-use bound.

MipCount¶

MipCount

The format's mip count is insufficient for the requested use.

SampleCount¶

SampleCount

The format's attachment sample count is unsupported.

UnalignedBlockExtents¶

UnalignedBlockExtents

Compressed base extents must be block-aligned on the enabled profile.

TextureUploadBytes¶

TextureUploadBytes

Complete texture creation-upload byte limit is insufficient.

UniformBindings¶

UniformBindings

Per-stage uniform descriptor limit is insufficient.

TextureBindings¶

TextureBindings

Per-stage sampled texture descriptor limit is insufficient.

SamplerBindings¶

SamplerBindings

Per-stage sampler descriptor limit is insufficient.

StorageBindings¶

StorageBindings

Compute storage descriptor limit is insufficient.

UniformBindingsPerSet¶

UniformBindingsPerSet

Set-wide uniform descriptor limit is insufficient.

SamplerBindingsPerSet¶

SamplerBindingsPerSet

Set-wide sampler descriptor limit is insufficient.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RasterStatus¶

enum class RasterStatus : ludus::foundation::uint8

Explicit portable-resource result. Only Ready/Pending publish ownership.

Related types: ludus::foundation::uint8

Ready¶

Ready

Operation completed, or an asynchronous resource is usable.

Pending¶

Pending

Output owns a resource awaiting backend validation; poll GetStatus.

NotReady¶

NotReady

Device startup or a dependency is pending; retry after it becomes ready.

Failed¶

Failed

Backend validation or creation failed; a published resource must be destroyed.

InvalidHandle¶

InvalidHandle

Null, stale, foreign-owner or wrong-incarnation handle.

InvalidState¶

InvalidState

Operation conflicts with an open frame or an already-owned output.

InvalidDescription¶

InvalidDescription

Malformed description, range, packing or layout mismatch.

Unsupported¶

Unsupported

Requested format or operation lies outside the enabled raster profile.

CapacityExceeded¶

CapacityExceeded

All bounded records are live or retained; no reservation was published.

IdentityExhausted¶

IdentityExhausted

An owner or slot generation cannot advance without wrapping.

OutOfMemory¶

OutOfMemory

Native allocation failed; no output ownership was published.

DeviceLost¶

DeviceLost

The device was lost; recreate resources in a new session.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

BufferRole¶

enum class BufferRole : ludus::foundation::uint8

Buffer creation role, fixed for its lifetime. Storage roles permit graph compute writes.

Related types: ludus::foundation::uint8

Vertex¶

Vertex

Per-vertex or per-instance attributes.

Index16¶

Index16

Mesh-local unsigned 16-bit indices.

Index32¶

Index32

Mesh-local unsigned 32-bit indices.

Uniform¶

Uniform

Uniform bytes with independently verified shader packing.

Storage¶

Storage

Mutable compute storage, initialized by complete creation bytes.

StorageVertex¶

StorageVertex

Mutable compute storage also consumed as vertex/instance records.

StorageIndirect¶

StorageIndirect

Mutable compute storage also consumed as one indexed indirect command.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

TextureAspect¶

enum class TextureAspect : ludus::foundation::uint8

Sampled color or private depth/stencil aspect; capability-gated independently.

Related types: ludus::foundation::uint8

Color¶

Color

Color/data channels, including normalized and compressed formats.

Depth¶

Depth

Private depth component; scalar float loads, without comparison/filtering.

Stencil¶

Stencil

Private stencil component; scalar unsigned integer loads when enabled.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterFilter¶

enum class RasterFilter : ludus::foundation::uint8

Portable within-level minification/magnification filter; mip interpolation is separate.

Related types: ludus::foundation::uint8

Nearest¶

Nearest

Select one texel.

Linear¶

Linear

Interpolate adjacent texels in linear light.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterAddress¶

enum class RasterAddress : ludus::foundation::uint8

Portable address mode applied independently along each sampled texture axis.

Related types: ludus::foundation::uint8

Clamp¶

Clamp

Clamp coordinates to edge texels.

Repeat¶

Repeat

Repeat the texture at integer coordinate boundaries.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterMipFilter¶

enum class RasterMipFilter : ludus::foundation::uint8

Independent minification selection across initialized mip levels.

Related types: ludus::foundation::uint8

None¶

None

Clamp to level zero; preserves the legacy sampling profile.

Nearest¶

Nearest

Select the nearest level.

Linear¶

Linear

Interpolate neighboring levels.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterBindingKind¶

enum class RasterBindingKind : ludus::foundation::uint8

Resource kind reflected at a binding in group/set zero.

Related types: ludus::foundation::uint8

UniformBuffer¶

UniformBuffer

Read-only uniform buffer range.

Texture2D¶

Texture2D

Non-multisampled, float-sampled two-dimensional texture.

Texture2DArray¶

Texture2DArray

Float-sampled fixed array of two-dimensional images.

TextureCube¶

TextureCube

Float-sampled six-face cubemap.

Texture3D¶

Texture3D

Float-sampled three-dimensional volume.

TextureDepth2D¶

TextureDepth2D

Scalar float, unfiltered loads from a D2 private depth aspect; no sampler binding.

TextureStencil2D¶

TextureStencil2D

Scalar unsigned integer loads from a D2 private stencil aspect; no sampler binding.

Sampler¶

Sampler

Non-comparison sampler.

StorageRead¶

StorageRead

Read-only storage buffer range, visible to compute or fragment shaders. Fragment storage requires the compute/storage capability profile; WebGL rejects it.

StorageReadWrite¶

StorageReadWrite

Read/write compute storage buffer range; shader write races remain kernel obligations.

RayScene¶

RayScene

Immutable, fully built native TLAS; compute-stage ray queries only.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterVisibility¶

enum class RasterVisibility : ludus::foundation::uint8

Shader stage visibility mask.

Related types: ludus::foundation::uint8

Vertex¶

Vertex = 1

Visible to the vertex stage only.

Fragment¶

Fragment = 2

Visible to the fragment stage only.

Both¶

Both = 3

Visible to both raster stages.

Compute¶

Compute = 4

Compute stage only; no raster/storage writes in this profile.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterBindingIndexing¶

enum class RasterBindingIndexing : ludus::foundation::uint8

Descriptor selection admitted by a reflected shader; array length alone grants no indexing mode.

Related types: ludus::foundation::uint8

Constant¶

Constant

Constant array indices only; does not require dynamic descriptor indexing.

Uniform¶

Uniform

A dynamically uniform index; native support is separately negotiated.

NonUniform¶

NonUniform

Per-invocation indices; requires explicitly requested optional bindless support.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterVertexFormat¶

enum class RasterVertexFormat : ludus::foundation::uint8

Portable float vertex attribute width.

Related types: ludus::foundation::uint8

Float2¶

Float2

Two IEEE binary32 components.

Float3¶

Float3

Three IEEE binary32 components.

Float4¶

Float4

Four IEEE binary32 components.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterUniformShape¶

enum class RasterUniformShape : ludus::foundation::uint8

Bounded authored uniform shapes, independently reflected for each target. Matrix order/array stride remain properties of the cooked target, not CPU math types.

Related types: ludus::foundation::uint8

Opaque¶

Opaque

Unclassified shape; legacy/other schemas cannot satisfy a typed material ABI.

Float32¶

Float32

One IEEE binary32 value.

Float2¶

Float2

Two IEEE binary32 components.

Float3¶

Float3

Three IEEE binary32 components.

Float4¶

Float4

Four IEEE binary32 components.

Float4x4¶

Float4x4

Four by four IEEE binary32 matrix.

Float4Array¶

Float4Array

Bounded fixed array of Float4 values.

Float4x4Array¶

Float4x4Array

Bounded fixed array of Float4x4 values.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterTarget¶

enum class RasterTarget : ludus::foundation::uint8

Color attachment compatibility baked into an immutable raster pipeline.

Related types: ludus::foundation::uint8

Surface¶

Surface

Acquired session target's negotiated format.

Rgba8Unorm¶

Rgba8Unorm

Linear RGBA8 offscreen color attachment.

Rgba8Srgb¶

Rgba8Srgb

sRGB RGBA8 offscreen color attachment.

Rgba16Float¶

Rgba16Float

Linear RGBA16F attachment; requires RasterCapabilities::HdrColor.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterDepthCompare¶

enum class RasterDepthCompare : ludus::foundation::uint8

Canonical [0,1] depth comparison; reversal is explicit rather than inferred from a matrix.

Related types: ludus::foundation::uint8

Less¶

Less

Pass when incoming depth is strictly smaller (conventional depth).

LessEqual¶

LessEqual

Pass on smaller or equal depth.

Greater¶

Greater

Pass when incoming depth is strictly larger (reverse-Z).

GreaterEqual¶

GreaterEqual

Pass on larger or equal depth.

Always¶

Always

Accept every depth value; DepthWrite still controls writes.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterFillMode¶

enum class RasterFillMode : ludus::foundation::uint8

How triangles are rasterized; indexed triangle lists remain the only primitive topology.

Related types: ludus::foundation::uint8

Solid¶

Solid

Cover every pixel inside each triangle.

Lines¶

Lines

Draw only each triangle's three edges as one-pixel lines, for wireframe diagnostics. Requires RasterCapabilities::HasLineFill; line width and anti-aliasing are not configurable.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterStencilCompare¶

enum class RasterStencilCompare : ludus::foundation::uint8

Portable stencil comparison against the masked reference and stored value.

Related types: ludus::foundation::uint8

Never¶

Never

Never pass.

Less¶

Less

Reference is smaller than the stored value.

Equal¶

Equal

Reference equals the stored value.

LessEqual¶

LessEqual

Reference is smaller than or equal to the stored value.

Greater¶

Greater

Reference is greater than the stored value.

NotEqual¶

NotEqual

Reference differs from the stored value.

GreaterEqual¶

GreaterEqual

Reference is greater than or equal to the stored value.

Always¶

Always

Always pass.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

RasterStencilOperation¶

enum class RasterStencilOperation : ludus::foundation::uint8

Operation on an eight-bit stencil value, after masking by WriteMask.

Related types: ludus::foundation::uint8

Keep¶

Keep

Preserve the stored value.

Zero¶

Zero

Write zero.

Replace¶

Replace

Write Reference.

IncrementClamp¶

IncrementClamp

Increment, saturating at 255.

DecrementClamp¶

DecrementClamp

Decrement, saturating at zero.

Invert¶

Invert

Invert all eight bits.

IncrementWrap¶

IncrementWrap

Increment modulo 256.

DecrementWrap¶

DecrementWrap

Decrement modulo 256.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

ResourceStatus¶

enum class ResourceStatus : ludus::foundation::uint8

Related types: ludus::foundation::uint8

Ready¶

Ready

Pending¶

Pending

Failed¶

Failed

NotReady¶

NotReady

InvalidHandle¶

InvalidHandle

InvalidState¶

InvalidState

InvalidDescription¶

InvalidDescription

CapacityExceeded¶

CapacityExceeded

InUse¶

InUse

DeviceLost¶

DeviceLost

An explicit device-owner operation was stopped by device loss; recreate the session.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

ShaderStage¶

enum class ShaderStage : ludus::foundation::uint8

Shader execution stage; Compute is accepted by the R4 reflected resource API.

Related types: ludus::foundation::uint8

Vertex¶

Vertex

Vertex input and transform stage.

Fragment¶

Fragment

Raster fragment stage.

Compute¶

Compute

Buffer compute stage, used only by the R4 reflected shader API.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

SurfaceEncoding¶

enum class SurfaceEncoding : ludus::foundation::uint8

Related types: ludus::foundation::uint8

Unorm¶

Unorm

Srgb¶

Srgb

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

Backend¶

enum class Backend : ludus::foundation::uint8

Renderer backend selected for a session; availability depends on target and startup.

Related types: ludus::foundation::uint8

Vulkan¶

Vulkan

WebGPU¶

WebGPU

WebGL2¶

WebGL2

Metal¶

Metal

Native macOS renderer using Metal for Cocoa and headless targets.

Direct3D12¶

Direct3D12

Native Windows renderer using Direct3D 12 for Win32 and headless targets.

The current bring-up starts a device, clears and presents frames; shader, draw, compute and resource operations report Unsupported or InvalidDescription. See docs/architecture/windows-direct3d12.md.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

BackendSelection¶

enum class BackendSelection : ludus::foundation::uint8

Browser backend policy. Native accepts only Auto, selecting Vulkan on Linux, Metal on macOS and Direct3D 12 on Windows. Auto attempts WebGPU (including its compatibility retry) and, only on a capability/startup failure, makes exactly one WebGL 2 attempt. A forced selection fails explicitly rather than silently switching backends.

Related types: ludus::foundation::uint8

Auto¶

Auto

WebGPU¶

WebGPU

WebGL2¶

WebGL2

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

StartupState¶

enum class StartupState : ludus::foundation::uint8

Related types: ludus::foundation::uint8

Idle¶

Idle

Pending¶

Pending

Ready¶

Ready

Failed¶

Failed

DeviceLost¶

DeviceLost

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

StartupError¶

enum class StartupError : ludus::foundation::uint8

Related types: ludus::foundation::uint8

None¶

None

InvalidWindow¶

InvalidWindow

InstanceUnavailable¶

InstanceUnavailable

AdapterUnavailable¶

AdapterUnavailable

DeviceUnavailable¶

DeviceUnavailable

SurfaceUnavailable¶

SurfaceUnavailable

RenderingUnavailable¶

RenderingUnavailable

Validation¶

Validation

DeviceLost¶

DeviceLost

GenerationExhausted¶

GenerationExhausted

BackendUnavailable¶

BackendUnavailable

RequirementsUnsatisfied¶

RequirementsUnsatisfied

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

StartStatus¶

enum class StartStatus : ludus::foundation::uint8

Related types: ludus::foundation::uint8

Pending¶

Pending

Ready¶

Ready

Failed¶

Failed

Busy¶

Busy

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

FrameStatus¶

enum class FrameStatus : ludus::foundation::uint8

Related types: ludus::foundation::uint8

Ready¶

Ready

NotReady¶

NotReady

InvalidState¶

InvalidState

Unsupported¶

Unsupported

Failed¶

Failed

Skipped¶

Skipped

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

RequirementFailure¶

enum class RequirementFailure : ludus::foundation::uint8

Related types: ludus::foundation::uint8

None¶

None

FrameDimension2D¶

FrameDimension2D

UniformBufferSize¶

UniformBufferSize

PortableRaster¶

PortableRaster

Required portable raster profile is unavailable on the negotiated device.

Compute¶

Compute

Required buffer compute/indirect profile is unavailable on this backend.

Profile¶

Profile

A required general raster/compute limit or format/use constraint was unmet.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

SpatialUpscaleColorProcessing¶

enum class SpatialUpscaleColorProcessing : foundation::uint8

Color interpretation supplied to the native spatial reconstruction algorithm. Neither mode performs application tone mapping or changes the texture format.

Related types: foundation::uint8

Linear¶

Linear

Input and output contain linear-light values in [0,1].

Perceptual¶

Perceptual

Input and output contain tone-mapped perceptual (sRGB) values in [0,1].

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/spatial_upscale.h

Aliases¶

WindowInfo¶

using ludus::graphics::rhi::WindowInfo = ludus::platform::NativeWindowInfo

Related types: ludus::platform::NativeWindowInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

Constants and variables¶

GPU_SCOPE_NAME_BYTES¶

constexpr foundation::usize ludus::graphics::rhi::GPU_SCOPE_NAME_BYTES = 128

Maximum UTF-8 scope storage, including its terminating zero. Longer names are rejected.

Related types: foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

MAX_GPU_TIMED_PASSES¶

constexpr foundation::usize ludus::graphics::rhi::MAX_GPU_TIMED_PASSES = 64

Maximum measured physical passes in one acquired frame. Surplus passes still render.

Related types: foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

GRAPH_EXTERNAL_INDEX¶

constexpr ludus::foundation::uint32 ludus::graphics::rhi::GRAPH_EXTERNAL_INDEX = ~ludus::foundation::uint32{0}

Sentinel for an external pass or an unavailable pass/resource index; never an authored index.

Related types: ludus::foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

HOSTED_VULKAN_SHADER_READ_LAYOUT¶

constexpr foundation::uint32 ludus::graphics::rhi::HOSTED_VULKAN_SHADER_READ_LAYOUT = 5

VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL: the layout of a Vulkan hosted image when presented.

Related types: foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/hosted_surface.h

MAX_NATIVE_COMPUTE_PASSES_PER_FRAME¶

constexpr foundation::usize ludus::graphics::rhi::MAX_NATIVE_COMPUTE_PASSES_PER_FRAME = 16

Native library dispatches per frame. Ordered graph execution rejects excess work before encoding, preserving the graph and completion output.

Related types: foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_compute.h

RASTER_FORMAT_COUNT¶

constexpr ludus::foundation::usize ludus::graphics::rhi::RASTER_FORMAT_COUNT =
static_cast<ludus::foundation::usize>(RasterFormat::Bc5RgUnorm) + 1

Number of known formats; profile tables are indexed by RasterFormat.

Related types: ludus::foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RASTER_BINDING_COUNT¶

constexpr ludus::foundation::usize ludus::graphics::rhi::RASTER_BINDING_COUNT = 16

Maximum group-zero binding numbers and copied shader/layout metadata entries. Enabled per-stage descriptor counts may be lower; query DeviceProfile before authoring layouts.

Related types: ludus::foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RUNTIME_BINDING_LENGTH_SLOT¶

constexpr ludus::foundation::uint32 ludus::graphics::rhi::RUNTIME_BINDING_LENGTH_SLOT = RASTER_BINDING_COUNT - 2

Reserved uniform binding for an RHI-owned immutable runtime table length. Runtime layouts reserve this slot; callers never supply or mutate its buffer.

Related types: ludus::foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RUNTIME_BINDING_ARRAY_SLOT¶

constexpr ludus::foundation::uint32 ludus::graphics::rhi::RUNTIME_BINDING_ARRAY_SLOT = RASTER_BINDING_COUNT - 1

Vulkan's variable-count sampled table occupies the highest group-zero binding.

Related types: ludus::foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RUNTIME_BINDING_LENGTH_WORDS¶

constexpr ludus::foundation::usize ludus::graphics::rhi::RUNTIME_BINDING_LENGTH_WORDS = 4

One uint4 constant-buffer record; its first word is the allocated table length.

Related types: ludus::foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

RUNTIME_BINDING_LENGTH_BYTES¶

constexpr ludus::foundation::usize ludus::graphics::rhi::RUNTIME_BINDING_LENGTH_BYTES =
sizeof(ludus::foundation::uint32) * RUNTIME_BINDING_LENGTH_WORDS

Native shader bytes of the immutable length record, excluding allocation padding.

Related types: ludus::foundation::usize

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

DEFAULT_GRAPH_RESOURCE_COUNT¶

constexpr foundation::uint32 ludus::graphics::rhi::DEFAULT_GRAPH_RESOURCE_COUNT = 64

Default logical resource ceiling for an ordered plan, including ordered ray invocations. This is an admission limit; graph metadata remains lazily allocated under HostBytes.

Related types: foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

DEFAULT_GRAPH_PASS_COUNT¶

constexpr foundation::uint32 ludus::graphics::rhi::DEFAULT_GRAPH_PASS_COUNT = 512

Default complete portable model dispatch schedule capacity; metadata is allocated lazily.

Related types: foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

DEFAULT_GRAPH_PACKET_COUNT¶

constexpr foundation::uint32 ludus::graphics::rhi::DEFAULT_GRAPH_PACKET_COUNT = 512

Default accepted packets in one plan, including a complete neural encoder.

Related types: foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

DEFAULT_BINDING_DESCRIPTOR_COUNT¶

constexpr foundation::uint32 ludus::graphics::rhi::DEFAULT_BINDING_DESCRIPTOR_COUNT = 4096

Default binding descriptors across overlapping scene/model generations.

Related types: foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

DEFAULT_GRAPH_DEPENDENCY_COUNT¶

constexpr foundation::uint32 ludus::graphics::rhi::DEFAULT_GRAPH_DEPENDENCY_COUNT = 2048

Default semantic dependency capacity, including read/write edges of every model dispatch.

Related types: foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

DEFAULT_RESOURCE_RECORD_COUNT¶

constexpr ludus::foundation::uint32 ludus::graphics::rhi::DEFAULT_RESOURCE_RECORD_COUNT = 1024

Default per-kind record admission for overlapping multi-pass resource generations.

Related types: ludus::foundation::uint32

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/profile.h

Functions¶

GetComputeCapabilities¶

RasterStatus ludus::graphics::rhi::GetComputeCapabilities(DeviceHandle, ComputeCapabilities &) noexcept

Query negotiated compute limits. Invalid owner preserves output; other failures zero it. WebGL2 returns Unsupported. No operation waits for the GPU.

Related types: RasterStatus · ComputeCapabilities · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute.h

CreateComputePipeline¶

RasterStatus ludus::graphics::rhi::CreateComputePipeline(DeviceHandle, const ComputePipelineDescription &, ComputePipelineHandle &) noexcept

Create a retained immutable compute pipeline between frames. Failure preserves null output; Pending publishes ownership requiring polling and destruction.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, ComputePipelineHandle) noexcept

Poll creation; invalid/stale/foreign identities return InvalidHandle.

Related types: RasterStatus · ComputePipelineHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, ComputePipelineHandle &) noexcept

Logically destroy between frames; graph and GPU leases delay physical release. Invalid handle preserves output. Success clears it.

Related types: RasterStatus · ComputePipelineHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/compute.h

ValidateDeviceDescription¶

DeviceStatus ludus::graphics::rhi::ValidateDeviceDescription(const DeviceDescription &description) noexcept

Reference admission validator shared by every backend; performs no allocation or GPU work.

Returns

Ready for implemented required workloads, Unsupported for missing workloads, InvalidDescription for malformed selection, format count/identity, duplicate format, sample count, zero/reserved storage counts or zero byte budgets. Actual limits and format uses are checked on each backend attempt before Ready; no feature or limit is inferred from a backend name.

Related types: DeviceStatus · DeviceDescription

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GetCompiledBackends¶

BackendAvailability ludus::graphics::rhi::GetCompiledBackends() noexcept

Query backend build availability without starting a device or requesting an adapter.

Related types: BackendAvailability

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

CreateDevice¶

DeviceStatus ludus::graphics::rhi::CreateDevice(const ApplicationInfo &application, const WindowInfo &window, const DeviceDescription &description, DeviceHandle &device, SurfaceHandle &surface, StartupInfo *failure=nullptr) noexcept

Start the single explicit device and its frame target on the main thread.

Precondition

Both outputs are null; the borrowed Platform window/canvas outlives DestroyDevice.

Returns

Ready/Pending publishes both handles and requires DestroyDevice, including subsequent failure/loss. Admission or synchronous startup failure preserves null outputs. Duplicate creation or an existing facade session returns InvalidState without changing it. Descriptions are copied; backend artifact inputs continue to use their existing contracts.

Parameter	Description
`application`	Startup application metadata, consumed during the call.
`window`	Borrowed Platform target; must outlive the owned device.
`description`	Copied backend/workload/limit admission request.
`device`	Null output receiving the single owned lifecycle record on Ready/Pending.
`surface`	Null output receiving the target borrowed from that owned session.
`failure`	Optional synchronous-startup diagnostic output, written only when startup fails; never retained. Other return paths preserve this output.

Related types: DeviceStatus · WindowInfo · ApplicationInfo · DeviceDescription · DeviceHandle · StartupInfo · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GetDeviceInfo¶

DeviceStatus ludus::graphics::rhi::GetDeviceInfo(DeviceHandle device, DeviceInfo &info) noexcept

Poll an owned startup/loss record without waiting. InvalidHandle preserves info. Ready/Pending/Failed/DeviceLost writes the snapshot; Failed/Lost still require destruction.

Related types: DeviceStatus · DeviceHandle · DeviceInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

DestroyDevice¶

DeviceStatus ludus::graphics::rhi::DestroyDevice(DeviceHandle &device) noexcept

Cancel pending startup or destroy a ready/failed/lost session; invalidates callback tokens before backend teardown. Clears device on success; borrowed surface copies become stale. InvalidHandle preserves device and cannot destroy another owner's session. Never waits for browser callbacks. Native interop leases defer physical teardown until foreign consumers complete; new device creation rejects InvalidState until all pins retire.

Related types: DeviceStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

SetFrameTarget¶

DeviceStatus ludus::graphics::rhi::SetFrameTarget(DeviceHandle device, SurfaceHandle surface, const FrameTarget &target) noexcept

Set a borrowed target between frames; dimensions are pixels and zero skips acquisition. Validates both owners before delegating to the facade's effective-limit checks.

Related types: DeviceStatus · DeviceHandle · FrameTarget · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

BeginFrame¶

DeviceStatus ludus::graphics::rhi::BeginFrame(DeviceHandle device, SurfaceHandle surface) noexcept

Acquire a frame for this owner/target. Skipped opens no frame; nested acquisition is invalid.

Related types: DeviceStatus · DeviceHandle · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

EndFrame¶

DeviceStatus ludus::graphics::rhi::EndFrame(DeviceHandle device) noexcept

Submit/end this owner's open frame once; fails explicitly after device loss.

Related types: DeviceStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GetFrameInfo¶

DeviceStatus ludus::graphics::rhi::GetFrameInfo(DeviceHandle device, SurfaceHandle surface, FrameInfo &info) noexcept

Query acquired dimensions/encoding; offscreen-only frames report their logical target extent. Invalid owner, pending startup or closed frame preserves info. This is not a presentation-completion query.

Related types: DeviceStatus · DeviceHandle · FrameInfo · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

CreateShader¶

ResourceStatus ludus::graphics::rhi::CreateShader(DeviceHandle device, const ShaderDescription &description, ShaderHandle &shader) noexcept

Create a facade shader after validating device ownership; output/async artifact contracts match CreateShader without a device parameter. Invalid owner returns InvalidHandle.

Related types: ResourceStatus · DeviceHandle · ShaderDescription · ShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

CreateUniform¶

ResourceStatus ludus::graphics::rhi::CreateUniform(DeviceHandle device, ludus::foundation::usize size, UniformHandle &uniform) noexcept

Create a facade uniform; size is bytes. Validates owner before applying existing admission rules.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

CreatePipeline¶

ResourceStatus ludus::graphics::rhi::CreatePipeline(DeviceHandle device, const PipelineDescription &description, PipelineHandle &pipeline) noexcept

Create a facade pipeline; all dependencies must resolve in this owner's shared registry.

Related types: ResourceStatus · DeviceHandle · PipelineDescription · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GetStatus¶

ResourceStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, ShaderHandle shader) noexcept

Poll a shader in this owner; stale/foreign resource identities return InvalidHandle.

Related types: ResourceStatus · DeviceHandle · ShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GetStatus¶

ResourceStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, UniformHandle uniform) noexcept

Poll a uniform in this owner; stale/foreign resource identities return InvalidHandle.

Related types: ResourceStatus · DeviceHandle · UniformHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

GetStatus¶

ResourceStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, PipelineHandle pipeline) noexcept

Poll a pipeline in this owner; stale/foreign resource identities return InvalidHandle.

Related types: ResourceStatus · DeviceHandle · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

UpdateUniform¶

ResourceStatus ludus::graphics::rhi::UpdateUniform(DeviceHandle device, UniformHandle uniform, std::span< const ludus::foundation::uint8 > bytes) noexcept

Replace uniform bytes under the existing frame/order/size rules; no ownership transfer.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

Destroy¶

ResourceStatus ludus::graphics::rhi::Destroy(DeviceHandle device, ShaderHandle shader) noexcept

Destroy a shader between frames. Existing pipeline dependencies still return InUse.

Related types: ResourceStatus · DeviceHandle · ShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

Destroy¶

ResourceStatus ludus::graphics::rhi::Destroy(DeviceHandle device, UniformHandle uniform) noexcept

Destroy a uniform between frames. Existing pipeline dependencies still return InUse.

Related types: ResourceStatus · DeviceHandle · UniformHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

Destroy¶

ResourceStatus ludus::graphics::rhi::Destroy(DeviceHandle device, PipelineHandle pipeline) noexcept

Destroy a pipeline between frames, using the shared facade registry and retirement behavior.

Related types: ResourceStatus · DeviceHandle · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

DrawFullscreen¶

ResourceStatus ludus::graphics::rhi::DrawFullscreen(DeviceHandle device, PipelineHandle pipeline) noexcept

Draw through the existing fullscreen path; validates the owner before issuing any work.

Related types: ResourceStatus · DeviceHandle · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/device.h

MakeGpuScope¶

bool ludus::graphics::rhi::MakeGpuScope(foundation::uint64 identity, foundation::BorrowedView< const char > name, GpuScopeDescription &outScope, foundation::uint32 logicalPassCount=1) noexcept

Construct an owned scope without allocation. Rejects zero identity, invalid/empty UTF-8, embedded zero, oversized names and zero logical count. Failure preserves outScope.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

ArmGpuPassTimings¶

RasterStatus ludus::graphics::rhi::ArmGpuPassTimings(DeviceHandle device) noexcept

Reserve/arm a native per-pass batch for the next acquired frame. Owner-thread only, between frames, with DeviceDescription::EnableGpuTiming enabled. No GPU waits. Ready replaces terminal data; InvalidState preserves armed/pending data. Unsupported leaves frame timing and rendering available. Allocation failure preserves terminal data.

Related types: RasterStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

GetGpuPassTimings¶

RasterStatus ludus::graphics::rhi::GetGpuPassTimings(DeviceHandle device, GpuPassTimings &outTimings) noexcept

Nonblocking owner-thread copy of the current batch. InvalidHandle preserves outTimings; unavailable device states clear it. Duration-only data has no CPU/GPU clock alignment.

Related types: RasterStatus · DeviceHandle · GpuPassTimings

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

BeginGpuScope¶

RasterStatus ludus::graphics::rhi::BeginGpuScope(DeviceHandle device, const GpuScopeDescription &scope) noexcept

Begin a named physical scope on the owner thread in an acquired frame, before encoding its operations. Names are copied for timing and native annotations. Nested scopes are rejected; a merged physical pass uses one scope with its logical member count. Timing need not be armed. InvalidState/Unsupported annotation results must not be treated as rendering failures.

Related types: RasterStatus · DeviceHandle · GpuScopeDescription

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

EndGpuScope¶

RasterStatus ludus::graphics::rhi::EndGpuScope(DeviceHandle device) noexcept

End the current owner-thread scope after its encoders/passes end. Rejects an unbalanced end.

Related types: RasterStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/gpu_scope.h

GetTextureState¶

RasterStatus ludus::graphics::rhi::GetTextureState(DeviceHandle, TextureHandle, RasterTextureState &) noexcept

Query an owned texture on the owner thread; failure preserves output.

Related types: RasterStatus · DeviceHandle · RasterTextureState · TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

BeginRasterPass¶

RasterStatus ludus::graphics::rhi::BeginRasterPass(DeviceHandle, const RasterPassDescription &) noexcept

Switch passes inside an open frame. Offscreen-only frames require owned texture attachments. Validates load/feedback/state before native calls; ends the previous pass and starts this one. Direct draws must match its attachment format. Rejected calls preserve the current pass.

Related types: RasterStatus · DeviceHandle · RasterPassDescription

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

GetGraphPassDiagnostic¶

RasterStatus ludus::graphics::rhi::GetGraphPassDiagnostic(DeviceHandle, OrderedGraph, ludus::foundation::uint32, GraphPassDiagnostic &) noexcept

Copy an authored pass diagnostic after a compile attempt; owner-thread only, no allocation. NotReady before a compile attempt; InvalidDescription for an out-of-range authored index. Admission failure and all rejected queries preserve output.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

GetGraphResourceDiagnostic¶

RasterStatus ludus::graphics::rhi::GetGraphResourceDiagnostic(DeviceHandle, OrderedGraph, ludus::foundation::uint32, GraphResourceDiagnostic &) noexcept

Copy a resource lifetime diagnostic after a compile attempt; failures preserve output. Resource indices refer to import order; owner-thread only, no allocation.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

GetGraphDependency¶

RasterStatus ludus::graphics::rhi::GetGraphDependency(DeviceHandle, OrderedGraph, ludus::foundation::uint32, GraphDependency &) noexcept

Copy one full-plan dependency after a compile attempt; failures preserve output. Index follows deterministic dependency order; owner-thread only, no allocation.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

CreateOrderedGraph¶

RasterStatus ludus::graphics::rhi::CreateOrderedGraph(DeviceHandle, OrderedGraph &) noexcept

Reserve a graph under StorageLimits::Graphs; null output required, failure preserves it.

Related types: RasterStatus · DeviceHandle · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

ImportGraphBuffer¶

RasterStatus ludus::graphics::rhi::ImportGraphBuffer(DeviceHandle, OrderedGraph, BufferHandle, GraphVersion &) noexcept

Import current buffer contents and freeze their accepted revision, retaining the physical record. Output version starts at zero. No duplicate physical imports; resource count is bounded by StorageLimits::ResourcesPerGraph. Compute writes invalidate earlier frozen plans.

Related types: RasterStatus · BufferHandle · DeviceHandle · GraphVersion · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

ImportGraphTexture¶

RasterStatus ludus::graphics::rhi::ImportGraphTexture(DeviceHandle, OrderedGraph, TextureHandle, const RasterTextureState &, RasterTextureUse finalUse, GraphVersion &) noexcept

Import a persistent texture using an exact registry snapshot. Stale snapshots reject; final use must be a sampled stage or ColorAttachment. Same-queue pending dependencies need no host wait. Pool textures cannot be imported by another graph.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

CreateGraphTexture¶

RasterStatus ludus::graphics::rhi::CreateGraphTexture(DeviceHandle, OrderedGraph, const TextureDescription &, GraphVersion &, TextureHandle &) noexcept

Acquire a matching complete attachment object under StorageLimits::TransientTextures. Reuse requires no other leases and actual GPU completion. Contents begin undefined. Returned texture is borrowed from the graph/pool: Destroy rejects it; create views and binding sets normally and destroy those owners to permit later pooling. A stale borrowed texture cannot be used once its graph is discarded/consumed. No heap aliasing. Allocation occurs during setup, before compilation or frame execution; Pending owns both outputs and can be polled using GetStatus on the texture before setup continues.

Related types: RasterStatus · DeviceHandle · GraphVersion · OrderedGraph · TextureDescription · TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

NextGraphVersion¶

RasterStatus ludus::graphics::rhi::NextGraphVersion(DeviceHandle, OrderedGraph, GraphVersion, GraphVersion &) noexcept

Reserve the next attachment or storage-buffer version without new physical storage. May reserve before its producer is added; compilation verifies authored ordering.

Related types: RasterStatus · DeviceHandle · GraphVersion · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

AddGraphPass¶

RasterStatus ludus::graphics::rhi::AddGraphPass(DeviceHandle, OrderedGraph, const GraphPassDescription &) noexcept

Copy one ordered pass and retain its validated packets. Failure changes no graph state. Uses/declarations are verified by CompileOrderedGraph before any GPU work.

Related types: RasterStatus · DeviceHandle · GraphPassDescription · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

AddGraphRoot¶

RasterStatus ludus::graphics::rhi::AddGraphRoot(DeviceHandle, OrderedGraph, GraphVersion, GraphRoot) noexcept

Mark a version as externally observable. Transient pool resources cannot escape; History/Export require persistent textures or buffers. Compilation rejects undefined roots.

Related types: RasterStatus · GraphRoot · DeviceHandle · GraphVersion · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

CompileOrderedGraph¶

RasterStatus ludus::graphics::rhi::CompileOrderedGraph(DeviceHandle, OrderedGraph, GraphReport &, bool reference=false) noexcept

Validate versions, actual packet uses, initialization, capacities and roots, then report dependencies/lifetimes. Reference mode keeps all otherwise legal passes. Failure preserves setup for repair/discard and writes its diagnostic report. Success freezes setup; no execution occurs. Whole resources remain physically distinct.

Related types: RasterStatus · DeviceHandle · GraphReport · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

CompileOrderedGraph¶

RasterStatus ludus::graphics::rhi::CompileOrderedGraph(DeviceHandle, OrderedGraph, GraphReport &, const GraphCompileOptions &) noexcept

Compile with explicit culling/merging controls, retaining the same validation, failure, freeze and ownership contract as the compatibility overload above. Reports logical passes/dependencies separately from planned raster groups.

Related types: RasterStatus · DeviceHandle · GraphCompileOptions · GraphReport · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

ExecuteOrderedGraph¶

RasterStatus ludus::graphics::rhi::ExecuteOrderedGraph(DeviceHandle, SurfaceHandle, OrderedGraph &, SubmissionToken &) noexcept

Preflight frozen imports/packets and backend pass objects, acquire a frame, encode authored live order and submit once. Preflight/target skip preserves graph/token for retry; once encoding begins graph is consumed even on failure. Partial backend work faults the session. Success publishes GPU completion and commits the existing ledger.

Related types: RasterStatus · DeviceHandle · OrderedGraph · SubmissionToken · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

EncodeOrderedGraph¶

RasterStatus ludus::graphics::rhi::EncodeOrderedGraph(DeviceHandle device, SurfaceHandle surface, OrderedGraph &inoutGraph) noexcept

Encode a compiled graph into the device's acquired frame without submitting it. The graph must have been built between frames; imports and packets are revalidated. Consumes the graph once encoding starts, retaining all GPU uses in the current frame ledger. The caller must EndFrame even after a partial failure and retain outputs through its actual submission completion. Owner thread only; no waiting.

Parameter	Description
`device`	Owned device with an acquired frame on surface.
`surface`	Surface of that frame.
`inoutGraph`	Compiled graph; cleared after accepted encoding, preserved on preflight rejection.

Related types: RasterStatus · DeviceHandle · OrderedGraph · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

DiscardOrderedGraph¶

RasterStatus ludus::graphics::rhi::DiscardOrderedGraph(DeviceHandle, OrderedGraph &) noexcept

Drop all graph packet/resource leases without GPU work; clears handle on success. Invalid handle or open frame preserves it. Pool reuse still waits for completion.

Related types: RasterStatus · DeviceHandle · OrderedGraph

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/graph.h

TryGetHostedConsumerAdapter¶

bool ludus::graphics::rhi::TryGetHostedConsumerAdapter(const NativeDeviceIdentity &device, platform::HostedAdapterIdentity &outAdapter) noexcept

Identify the adapter a HostedSurfaceConsumer started on device imports onto.

Pass the result as platform::HostedWindowEndpoint::StartInfo::ConsumerAdapterOrNull. The endpoint announces it in its Welcome, and a Vulkan game connected to the hosted window tries that adapter before any other, so a multi-GPU host renders where the editor can import. Without a matching adapter the game selects as usual and the consumer refuses its images with AdapterMismatch.

Parameter	Description
`device`	The consumer's device, as for HostedSurfaceConsumer::Start(). Vulkan needs `Instance` and `PhysicalDevice`; no other object is used.
`outAdapter`	Vulkan: the adapter's `deviceUUID` and `driverUUID`, queried through `Instance`. Unchanged unless true is returned.

Returns

true on Vulkan. false on Metal, where IOSurfaces work across GPUs and the game needs no adapter; for another API, an incomplete identity, a build without hosted import, or when vkGetPhysicalDeviceProperties2 cannot be loaded.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/hosted_surface.h

GetStorageUsage¶

RasterStatus ludus::graphics::rhi::GetStorageUsage(DeviceHandle, StorageUsage &) noexcept

Copy current accounting without waiting or allocating; owner-thread only. Invalid handles preserve output. Other unavailable states zero output and report their status.

Related types: RasterStatus · DeviceHandle · StorageUsage

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetTextureResidency¶

RasterStatus ludus::graphics::rhi::GetTextureResidency(DeviceHandle, TextureHandle, TextureResidency &) noexcept

Copy logical mip initialization without waiting; Pending writes do not publish new bits. Invalid handles preserve output. Owner-thread only; no sparse-memory or eviction promise.

Related types: RasterStatus · DeviceHandle · TextureHandle · TextureResidency

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestBufferUpdate¶

RasterStatus ludus::graphics::rhi::RequestBufferUpdate(DeviceHandle, BufferHandle, ludus::foundation::usize offset, const ludus::foundation::uint8 *bytes, ludus::foundation::usize size, TransferTicket &) noexcept

Submit a copied update to an existing buffer between frames. Offset/size are multiples of four, nonzero and within the allocation and TransferBytes. All buffer roles are legal. Pending publishes a null ticket; other results preserve it. Ready buffers with CPU leases (bindings, batches, graphs, ray inputs, transfers) or unfinished GPU uses reject InvalidState. Accepted writes make the destination Pending until actual completion; another request returns NotReady. Release the completed ticket before another mutation; cancellation cannot undo accepted writes.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestTextureUpdate¶

RasterStatus ludus::graphics::rhi::RequestTextureUpdate(DeviceHandle, TextureHandle, const TextureRegion &, const ludus::foundation::uint8 *bytes, ludus::foundation::usize byteCount, ludus::foundation::usize rowPitch, TransferTicket &) noexcept

Copy caller rows into owned staging and submit a bounded RGBA8Unorm mip rectangle update. Row pitch is a multiple of four, at least Width*4; byteCount must equal RowPitch*Height. Internal 256-byte row packing must also fit TransferBytes. CPU-retained textures reject Unsupported. Destination leases/in-flight uses reject InvalidState. An undefined mip requires its complete rectangle; success defines that mip after completion. Output publication/cancellation matches buffer updates.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestTextureCopy¶

RasterStatus ludus::graphics::rhi::RequestTextureCopy(DeviceHandle, TextureHandle source, const TextureRegion &sourceRegion, TextureHandle destination, const TextureRegion &destinationRegion, TransferTicket &) noexcept

Submit an exact-format RGBA8Unorm GPU copy between distinct textures/mips of equal rectangle size. Source mip must be initialized; source ownership is retained through completion. Destination mutation obeys RequestTextureUpdate's lease/initialization rules. Pending publishes a null ticket; rejection preserves it.

Related types: RasterStatus · DeviceHandle · TextureHandle · TextureRegion · TransferTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestTextureReadback¶

RasterStatus ludus::graphics::rhi::RequestTextureReadback(DeviceHandle, TextureHandle, const TextureRegion &, ludus::foundation::usize rowPitch, ReadbackTicket &) noexcept

Schedule RGBA8Unorm texel readback into owned staging; source mip must be initialized. Caller row pitch is four-byte aligned and at least Width*4; both caller and 256-byte staging rows must fit TransferBytes. CopyReadback returns RowPitch*Height top-oriented bytes with zero padding. Call on the ready device's owner thread between frames, with a null output ticket. Accepted submission returns Pending and publishes an owned ticket; poll GetStatus and release it once. Rejection preserves output. The source survives public destruction.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, TransferTicket) noexcept

Nonblocking mutation completion poll. Ready proves execution; failure remains explicit.

Related types: RasterStatus · DeviceHandle · TransferTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

Release¶

RasterStatus ludus::graphics::rhi::Release(DeviceHandle, TransferTicket &) noexcept

Drop notification ownership and clear the ticket. Leases/staging retire only after GPU completion. Invalid/stale handles preserve the ticket; cancellation does not roll back writes.

Related types: RasterStatus · DeviceHandle · TransferTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetLifetimeCapabilities¶

RasterStatus ludus::graphics::rhi::GetLifetimeCapabilities(DeviceHandle device, LifetimeCapabilities &output) noexcept

Query configured budgets; invalid owner preserves output, unavailable device writes zero budgets.

Related types: RasterStatus · DeviceHandle · LifetimeCapabilities

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

BeginCommands¶

RasterStatus ludus::graphics::rhi::BeginCommands(DeviceHandle device, CommandBatch &output) noexcept

Reserve a recording batch in a null output between frames. Ready publishes ownership. Admission failure preserves output; no caller storage is borrowed.

Related types: RasterStatus · CommandBatch · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RecordDraw¶

RasterStatus ludus::graphics::rhi::RecordDraw(DeviceHandle device, CommandBatch batch, const RasterDraw &draw) noexcept

Validate and copy one complete draw into a Recording batch before any native work. Retains pipeline, binding snapshot, geometry and their dependencies. Rejection preserves the batch. Destroying public resource handles after acceptance cannot invalidate this retained packet.

Related types: RasterStatus · CommandBatch · DeviceHandle · RasterDraw

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

FinishCommands¶

RasterStatus ludus::graphics::rhi::FinishCommands(DeviceHandle device, CommandBatch batch) noexcept

Change Recording to Finished once; later recording is InvalidState.

Related types: RasterStatus · CommandBatch · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

DiscardCommands¶

RasterStatus ludus::graphics::rhi::DiscardCommands(DeviceHandle device, CommandBatch &batch) noexcept

Discard Recording/Finished work and release CPU leases. Clears batch on success. No GPU work is issued. Invalid/stale owner preserves batch.

Related types: RasterStatus · CommandBatch · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

SubmitCommands¶

RasterStatus ludus::graphics::rhi::SubmitCommands(DeviceHandle device, SurfaceHandle surface, CommandBatch &batch, SubmissionToken &completion) noexcept

Acquire the current target, encode a Finished batch and submit it once.

Precondition

completion is null; no other frame is open. Main-thread use only. Ready transfers CPU leases to GPU retirement, clears batch, and publishes completion. A skipped target returns NotReady and preserves the finished batch for retry. Native failure after encoding begins can submit partial work: a non-null completion still identifies that accepted GPU work; inspect the returned failure independently. Preflight/admission failure preserves batch and completion. Sampled textures must have defined contents and a committed sampled use covering binding visibility.

Related types: RasterStatus · CommandBatch · DeviceHandle · SubmissionToken · SurfaceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

EndFrame¶

RasterStatus ludus::graphics::rhi::EndFrame(DeviceHandle device, SubmissionToken &completion) noexcept

End an open direct frame with completion tracking, including clear-only frames.

Precondition

completion is null. Ready publishes accepted ordered GPU work, never a displayed frame number. Admission/reservation failure preserves output and leaves the frame open for retry.

Related types: RasterStatus · DeviceHandle · SubmissionToken

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, SubmissionToken completion) noexcept

Nonblocking completion poll. Ready means Complete; Pending means accepted work is outstanding. Failed/DeviceLost preserve the failure rather than reporting completion. Foreign/zero ordinals and ordinals not published by this device return InvalidHandle. Tokens need no release.

Related types: RasterStatus · DeviceHandle · SubmissionToken

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestBufferUpload¶

RasterStatus ludus::graphics::rhi::RequestBufferUpload(DeviceHandle device, const BufferDescription &description, const ludus::foundation::uint8 *bytes, ludus::foundation::usize byteCount, UploadTicket &output) noexcept

Copy complete initial buffer bytes into an owned bounded upload-ring slice before return.

Parameter	Description
`device`	Ready owner with portable raster enabled.
`description`	Immutable buffer role and original size in bytes.
`bytes`	Borrowed byte pointer; non-null with byteCount == description.Size.
`byteCount`	Bytes copied, nonzero and at most TransferBytes; buffer-role alignment applies.
`output`	Null ticket receiving ownership on Pending; failures preserve it. The copy is submitted before return; PollLifetime/GetStatus polls without waiting. TakeUploadedBuffer transfers a Ready immutable result; Release cancels publication while retaining in-flight staging until completion.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestBufferReadback¶

RasterStatus ludus::graphics::rhi::RequestBufferReadback(DeviceHandle device, BufferHandle source, ludus::foundation::usize offset, ludus::foundation::usize size, ReadbackTicket &output) noexcept

Schedule a bounded byte-range copy from a ready buffer to an owned readback-ring slice. Offset and size are multiples of four, size is nonzero and at most TransferBytes. The source incarnation is retained even after its public handle is destroyed. Pending publishes output; rejection preserves it. Call between frames.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, UploadTicket ticket) noexcept

Poll upload validation and GPU completion without waiting; failure still requires Release.

Related types: RasterStatus · DeviceHandle · UploadTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, ReadbackTicket ticket) noexcept

Poll copy completion and mapping independently; Ready guarantees CopyReadback is legal.

Related types: RasterStatus · DeviceHandle · ReadbackTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

TakeUploadedBuffer¶

RasterStatus ludus::graphics::rhi::TakeUploadedBuffer(DeviceHandle device, UploadTicket &ticket, BufferHandle &output) noexcept

Transfer the Ready uploaded buffer into a null output and clear its ticket. Pending/failure preserves both outputs; source bytes are no longer borrowed.

Related types: RasterStatus · BufferHandle · DeviceHandle · UploadTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

CopyReadback¶

RasterStatus ludus::graphics::rhi::CopyReadback(DeviceHandle device, ReadbackTicket ticket, ludus::foundation::uint8 *output, ludus::foundation::usize capacity) noexcept

Copy all Ready readback bytes to caller storage; never exposes a native mapping.

Parameter	Description
`device`	Ready owner of the readback ticket.
`ticket`	Ready owned request; copying does not release it.
`output`	Non-null destination with capacity at least the requested size in bytes.
`capacity`	Destination capacity in bytes. Rejection/Pending preserves destination bytes. Success keeps the ticket until Release.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

Release¶

RasterStatus ludus::graphics::rhi::Release(DeviceHandle device, UploadTicket &ticket) noexcept

Cancel/drop an upload ticket and clear it. In-flight GPU staging remains retained until safe.

Related types: RasterStatus · DeviceHandle · UploadTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

Release¶

RasterStatus ludus::graphics::rhi::Release(DeviceHandle device, ReadbackTicket &ticket) noexcept

Drop a readback ticket and clear it. In-flight mapping/copy and source leases retire safely.

Related types: RasterStatus · DeviceHandle · ReadbackTicket

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

RequestPipeline¶

RasterStatus ludus::graphics::rhi::RequestPipeline(DeviceHandle device, const RasterPipelineDescription &description, PipelineRequest &output) noexcept

Copy a canonical field-wise pipeline description and retain dependencies before return. Repeated requests using identical immutable shader/layout incarnations and fixed state share one backend pipeline; keys compare every active field, never pointers, hashes or padding. Ready/Pending publishes one independent request. Null output required; failures preserve it. PollLifetime creates at most one pending pipeline per call on the device/context owner. WebGPU driver creation is asynchronous; native/WebGL driver creation may occupy that call.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, PipelineRequest request) noexcept

Poll a pipeline request; Pending/failure is explicit and never switches backend or creates a fallback.

Related types: RasterStatus · DeviceHandle · PipelineRequest

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

GetRequestedPipeline¶

RasterStatus ludus::graphics::rhi::GetRequestedPipeline(DeviceHandle device, PipelineRequest request, RasterPipelineHandle &output) noexcept

Obtain a borrowed Ready pipeline for recording/drawing while this request is owned. Null output required. Do not Destroy the borrowed pipeline (InvalidState); release its request. Accepted batches retain it beyond request release. Pending/failure preserves output.

Related types: RasterStatus · DeviceHandle · PipelineRequest · RasterPipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

Release¶

RasterStatus ludus::graphics::rhi::Release(DeviceHandle device, PipelineRequest &request) noexcept

Release one independent request and clear it; the last request detaches the cached pipeline. Pending native callbacks and accepted CPU/GPU work retain their own records until retirement.

Related types: RasterStatus · DeviceHandle · PipelineRequest

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

PollLifetime¶

RasterStatus ludus::graphics::rhi::PollLifetime(DeviceHandle device) noexcept

Drain transfer/creation completion and launch at most one queued pipeline without blocking on GPU work. Call between frames on the owner thread, including later browser event-loop turns. Admission failure is explicit. Does not pump a browser event loop or promise a driver time budget.

Related types: RasterStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/lifetime.h

ArmGpuTiming¶

RasterStatus ludus::graphics::rhi::ArmGpuTiming(DeviceHandle) noexcept

Optional frame sampling controls. One probe is retained per session, separate from resources. Enable through DeviceDescription::EnableGpuTiming before startup. Owner-thread only. Arm between frames; Ready replaces a terminal/empty sample, InvalidState preserves an armed/pending sample or rejects an open frame. Unsupported means timing was not enabled. Query allocation can return OutOfMemory/Failed; those and identity-capacity failures preserve the previous terminal sample while the device stays ready. Skipped frames keep it armed. No blocking or CPU-duration fallback. DestroyDevice cancels and releases its native storage.

Related types: RasterStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/measurement.h

GetGpuTiming¶

RasterStatus ludus::graphics::rhi::GetGpuTiming(DeviceHandle, GpuTiming &) noexcept

Nonblocking poll/copy. InvalidHandle preserves output; other unavailable device states zero it. Ready reports the copied lifecycle, including Pending, Unavailable, Disjoint or Failed. Polling a query does not claim presentation completion. Terminal results persist until re-armed.

Related types: RasterStatus · DeviceHandle · GpuTiming

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/measurement.h

GetMeasurementAdapter¶

RasterStatus ludus::graphics::rhi::GetMeasurementAdapter(DeviceHandle, MeasurementAdapter &) noexcept

Copy backend adapter identity, without allocation/wait; owner-thread only. InvalidHandle preserves output; unavailable device states zero it. Ready may still contain hidden identity fields; qualification must keep those observations open.

Related types: RasterStatus · DeviceHandle · MeasurementAdapter

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/measurement.h

GetAllocationTelemetry¶

RasterStatus ludus::graphics::rhi::GetAllocationTelemetry(DeviceHandle, AllocationTelemetry &) noexcept

Copy scoped allocation/retirement telemetry without waiting/allocating; owner-thread only. InvalidHandle preserves output; other unavailable device states zero it. ApiBytesAvailable is false when any allocation size is opaque; partial sums are not published as complete totals. CapacityExceeded zeros output when a complete byte count cannot be represented.

Related types: RasterStatus · AllocationTelemetry · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/measurement.h

CreateNativeComputePipeline¶

RasterStatus ludus::graphics::rhi::CreateNativeComputePipeline(DeviceHandle device, const NativeComputePipelineDescription &description, ComputePipelineHandle &outPipeline) noexcept

Create a native adapter in the ordinary compute registry; no shader compilation. Dispatch must use the exact supplied snapshot, unit group counts and no dynamic offsets. Ready/Pending publishes ownership; Pending requires polling and destruction. Failure preserves output and does not retain ContextOrNull. Call between frames. Metal only; unsupported backends return Unsupported before calling Prepare.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_compute.h

CreateNativeDevice¶

DeviceStatus ludus::graphics::rhi::CreateNativeDevice(const ApplicationInfo &application, const NativeDeviceDescription &native, const DeviceDescription &description, ludus::foundation::uint32 width, ludus::foundation::uint32 height, DeviceHandle &device, SurfaceHandle &surface) noexcept

Admit a retained foreign device for headless RHI rendering, without creating or destroying that source's instance/device/queue. Width/height are initial pixels.

Precondition

Native objects and queue provenance are valid; all calls/submissions use the owner thread.

Returns

Ready on success; Unsupported for unsupported backend/profile, or an explicit admission failure. Device/surface outputs are preserved on rejection. Vulkan ray queries and BC formats are not enabled by foreign-device admission.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

GetNativeInteropCapabilities¶

RasterStatus ludus::graphics::rhi::GetNativeInteropCapabilities(DeviceHandle device, NativeInteropCapabilities &output) noexcept

Query enabled native sharing; outputs are preserved unless Ready is returned.

Related types: RasterStatus · DeviceHandle · NativeInteropCapabilities

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

AcquireNativeDevice¶

RasterStatus ludus::graphics::rhi::AcquireNativeDevice(DeviceHandle device, NativeDeviceLease &output) noexcept

Pin the exact native context of a Ready RHI device. An occupied output rejects. Shutdown defers native cleanup while native device/image leases remain live.

Related types: RasterStatus · DeviceHandle · NativeDeviceLease

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

GetNativeDeviceInfo¶

RasterStatus ludus::graphics::rhi::GetNativeDeviceInfo(NativeDeviceLease handle, NativeDeviceInfo &output) noexcept

Get the pinned context, including after ordinary device shutdown; preserve output on failure.

Related types: RasterStatus · NativeDeviceInfo · NativeDeviceLease

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

ReleaseNativeDevice¶

RasterStatus ludus::graphics::rhi::ReleaseNativeDevice(NativeDeviceLease &handle) noexcept

Release a device pin after every associated texture read and foreign native borrower has been retired. InvalidState preserves the lease when texture reads still refer to it.

Related types: RasterStatus · NativeDeviceLease

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

AcquireNativeTextureRead¶

RasterStatus ludus::graphics::rhi::AcquireNativeTextureRead(NativeDeviceLease device, const NativeDeviceIdentity &consumer, TextureHandle handle, SubmissionToken producer, NativeTextureRead &output, NativeTextureInfo &info) noexcept

Publish an initialized attachment for same-context sampled reads. Producer must be the exact last accepted RHI submission using this texture. A native queue barrier orders producer writes before consumer reads; no CPU pixel transfer or completion wait.

Parameter	Description
`device`	Open context lease for the Ready RHI session, on its owner thread.
`consumer`	Exact actual consumer context; physical adapter agreement alone is insufficient.
`handle`	Initialized single-sample RGBA8 attachment incarnation to retain.
`producer`	Its most recent accepted RHI submission; GPU completion need not have occurred.
`output`	Null read lease; receives ownership only on Ready.
`info`	Borrowed native descriptor; preserved unless Ready is returned.

Returns

Ready publishes both outputs; all failures preserve both. Writes, including graph attachments and mutable transfers, reject until the read is fully released.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

GetNativeTextureInfo¶

RasterStatus ludus::graphics::rhi::GetNativeTextureInfo(NativeTextureRead handle, NativeTextureInfo &output) noexcept

Query the borrowed descriptor only while its read is open; preserve output on failure.

Related types: RasterStatus · NativeTextureInfo · NativeTextureRead

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

ReleaseNativeTextureRead¶

RasterStatus ludus::graphics::rhi::ReleaseNativeTextureRead(NativeTextureRead &read) noexcept

Stop new foreign reads and enqueue a completion marker after all already-submitted foreign work on the shared queue. Invoke after actual queue submission, not recording. Pending preserves the handle and backing; poll/repeat until Ready clears the handle. Rejection preserves the handle; terminal loss permits safe retirement. Owner thread only.

Related types: RasterStatus · NativeTextureRead

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

DrainNativeTextureRead¶

RasterStatus ludus::graphics::rhi::DrainNativeTextureRead(NativeTextureRead &read) noexcept

Explicit maintenance/teardown variant of ReleaseNativeTextureRead. May block until previously submitted shared-queue GPU work finishes; never call in presentation. Clears the handle on Ready and preserves it on nonterminal failures.

Related types: RasterStatus · NativeTextureRead

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(NativeTextureRead handle) noexcept

Ready means an open queue-ordered read, or a completed release marker; Pending means foreign release is still in flight. DeviceLost is terminal. No CPU pixel readback occurs.

Related types: RasterStatus · NativeTextureRead

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/native_interop.h

GetTextureCpuContent¶

RasterStatus ludus::graphics::rhi::GetTextureCpuContent(DeviceHandle, TextureHandle, ludus::foundation::uint32 mip, TextureCpuContent &) noexcept

Query an explicitly retained CPU shadow. No allocation/wait; failure preserves output. Missing shadow returns Unsupported, pending upload NotReady, bad mip InvalidDescription. Owner-thread only. The texture must remain retained.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetTextureCpuContent¶

RasterStatus ludus::graphics::rhi::GetTextureCpuContent(DeviceHandle, TextureViewHandle, ludus::foundation::uint32 mip, TextureCpuContent &) noexcept

Query through a retained sampled view, including after its source texture owner was destroyed. mip is relative to the view (zero selects BaseMip), and must be less than its MipCount. Same readiness/failure rules; keep the view retained.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetRasterCapabilities¶

RasterStatus ludus::graphics::rhi::GetRasterCapabilities(DeviceHandle, RasterCapabilities &) noexcept

Query the enabled raster profile. Invalid owner preserves output; non-ready devices return their state and zero the capability value. A resource-only backend can expose nonzero allocation limits with zero DrawsPerFrame while PortableRaster remains disabled. Resource creation is available; pipelines/draws may return Unsupported. All operations are owner-thread only.

Related types: RasterStatus · DeviceHandle · RasterCapabilities

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetFormatCapabilities¶

RasterStatus ludus::graphics::rhi::GetFormatCapabilities(DeviceHandle, RasterFormat, FormatCapabilities &) noexcept

Query one known format's enabled uses and limits on the owner thread, including open frames. Invalid owner or malformed format preserves output. Non-ready devices zero it; valid but unavailable formats return Unsupported with zero output. No allocation or GPU wait.

Related types: RasterStatus · RasterFormat · DeviceHandle · FormatCapabilities

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateBuffer¶

RasterStatus ludus::graphics::rhi::CreateBuffer(DeviceHandle, const BufferDescription &, std::span< const ludus::foundation::uint8 >, BufferHandle &) noexcept

Create a buffer from exactly Size initial bytes; creation is forbidden in an open frame. Failure preserves a null output. Index content is copied into bounded engine storage for draw-range checks; vertex/uniform input is consumed by the backend before return.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateTexture¶

RasterStatus ludus::graphics::rhi::CreateTexture(DeviceHandle, const TextureDescription &, const TextureUpload &, TextureHandle &) noexcept

Create a sampled allocation from a complete original-format mip/slice chain, including enabled HDR/BC. The borrowed blob must not exceed RasterCapabilities::MaxBufferSize; all logical backing consumes StorageLimits::ResourceBytes. Empty upload/zero pitch selects an attachment or deferred RGBA8 D2 allocation. Owner-thread only, between frames. Ready/Pending publishes ownership and consumes caller bytes/metadata before return; other results preserve output. Poll Pending with GetStatus.

Related types: RasterStatus · DeviceHandle · TextureDescription · TextureHandle · TextureUpload

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

IsNull¶

bool ludus::graphics::rhi::IsNull(TextureHandle) noexcept

Return whether the texture identity is the null surface selector; no ownership/state query.

Related types: TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetTextureDescription¶

RasterStatus ludus::graphics::rhi::GetTextureDescription(DeviceHandle, TextureHandle, TextureDescription &) noexcept

Copy the immutable description of an owned texture; owner-thread only, including open frames. Invalid/unready handles preserve output; does not expose native objects or extend ownership.

Related types: RasterStatus · DeviceHandle · TextureDescription · TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateTextureView¶

RasterStatus ludus::graphics::rhi::CreateTextureView(DeviceHandle, TextureHandle, TextureViewHandle &) noexcept

Create a complete initialized-mip view in the allocation dimension and format, retaining its texture. Use the description overload to select sampled subranges. Deferred sampled allocations reject InvalidState until every mip is initialized. Failures preserve a null output; owner-thread only.

Related types: RasterStatus · DeviceHandle · TextureHandle · TextureViewHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateTextureView¶

RasterStatus ludus::graphics::rhi::CreateTextureView(DeviceHandle, TextureHandle, const TextureViewDescription &, TextureViewHandle &) noexcept

Create a bounded sampled aspect or writable attachment view on the owner thread between frames. Only selected mips must be initialized (attachments retain existing clear/store rules). Ready/Pending publishes ownership and retains the allocation; other results preserve output. Unsupported denotes a disabled dimension/partial-view capability. GDI hazards and mutation exclusion remain conservative for the whole allocation, including disjoint views.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateSampler¶

RasterStatus ludus::graphics::rhi::CreateSampler(DeviceHandle, const SamplerDescription &, SamplerHandle &) noexcept

Create immutable filter/address state; no engine allocations on a warmed resource path.

Related types: RasterStatus · DeviceHandle · SamplerDescription · SamplerHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateRasterShader¶

RasterStatus ludus::graphics::rhi::CreateRasterShader(DeviceHandle, const RasterShaderDescription &, RasterShaderHandle &) noexcept

Create a reflected stage. Pending owns its output; copied metadata survives caller storage.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateBindingLayout¶

RasterStatus ludus::graphics::rhi::CreateBindingLayout(DeviceHandle, std::span< const RasterBinding >, BindingLayoutHandle &) noexcept

Create an immutable group-zero layout from at most Interface.MaxBindings unique entries; per-stage counts are checked independently. A runtime entry reserves the length slot and adds its uniform entry when absent; conflicting consumer bindings reject.

Related types: RasterStatus · BindingLayoutHandle · DeviceHandle · RasterBinding

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateBindingSet¶

RasterStatus ludus::graphics::rhi::CreateBindingSet(DeviceHandle, BindingLayoutHandle, std::span< const RasterBindingResource >, BindingSetHandle &) noexcept

Create an immutable snapshot of the layout's full descriptor capacity. Every element is required unless its binding enables HasPartialBinding; omitted elements then use a required element-zero fallback. Duplicates always reject. Runtime length metadata is supplied by RHI; consumer entries at its reserved binding reject. Each runtime snapshot also owns one budgeted uniform buffer. Creation consumes StorageLimits::BindingDescriptors until physical retirement. It retains its layout and all resources even after public destruction.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateRuntimeBindingSet¶

RasterStatus ludus::graphics::rhi::CreateRuntimeBindingSet(DeviceHandle, BindingLayoutHandle, ludus::foundation::BorrowedView< const RasterBindingResource >, ludus::foundation::uint32 runtimeCount, BindingSetHandle &) noexcept

Allocate an explicitly sized snapshot of a runtime layout between frames.

Parameter Description

runtimeCount

Positive runtime array length, no greater than layout Count. The borrowed entries are consumed before return. The RHI-owned length buffer matches runtimeCount; verified runtime shaders clamp through runtime_bindings.slang. Missing elements require HasPartialBinding and populated element zero; otherwise every element is required. Failure preserves output; Pending owns output and requires normal status polling. Layouts without exactly one runtime binding reject. Owner-thread only.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

PublishBindingSetUpdate¶

RasterStatus ludus::graphics::rhi::PublishBindingSetUpdate(DeviceHandle, BindingSetHandle &inoutCurrent, BindingSetHandle &inoutReplacement) noexcept

Publish a prepared replacement after previous work has bound the old snapshot. Both handles must be owned, distinct, Ready and share the exact layout. Owner-thread only, including during an open frame; prepare replacements before the frame. Publication never allocates, collects or mutates native descriptors. Ready consumes inoutReplacement, updates inoutCurrent and logically destroys its old identity. Retained graphs/batches/submissions keep the previous backing until completion. NotReady or other failure preserves both handles and bindings. This snapshot operation does not enable Vulkan UPDATE_AFTER_BIND semantics.

Related types: RasterStatus · BindingSetHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetBindingIndex¶

RasterStatus ludus::graphics::rhi::GetBindingIndex(DeviceHandle, BindingSetHandle, ludus::foundation::uint32 binding, ludus::foundation::uint32 element, RasterBindingIndex &) noexcept

Obtain a borrowed index into a populated element of an owned, ready descriptor array between or during frames. Logical holes and out-of-allocation indices reject. Invalid/stale set returns InvalidHandle; bad binding/element InvalidDescription. Failure preserves output. Does not retain resources or allocate. Owner-thread only.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetBindingArrayElement¶

RasterStatus ludus::graphics::rhi::GetBindingArrayElement(DeviceHandle, BindingSetHandle, const RasterBindingIndex &, ludus::foundation::uint32 &) noexcept

Resolve an index against the exact owned snapshot, preserving output on failure. Stale/foreign/replaced indices return InvalidHandle. Ready writes the bounded shader array element. Shaders must remain inside the allocated extent; logical holes access the retained fallback. Replacing a snapshot invalidates its host tokens.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

CreateRasterPipeline¶

RasterStatus ludus::graphics::rhi::CreateRasterPipeline(DeviceHandle, const RasterPipelineDescription &, RasterPipelineHandle &) noexcept

Create an immutable triangle pipeline; dependencies must be ready. Binding contents are supplied independently at draw time. Failure leaves null output and rolls back reservation.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

DrawIndexed¶

RasterStatus ludus::graphics::rhi::DrawIndexed(DeviceHandle, const RasterDraw &) noexcept

Encode an indexed/instanced packet into the explicit device's open frame. Retain all referenced records until backend completion; drawing cannot mix with DrawFullscreen in the same frame. Rejected packets issue no native draw. Sampled textures must have defined contents and a committed/draft sampled use covering the binding visibility; otherwise InvalidDescription/InvalidState.

Related types: RasterStatus · DeviceHandle · RasterDraw

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, BufferHandle) noexcept

Query asynchronous validation for an owned Buffer record; stale/foreign handles are rejected.

Related types: RasterStatus · BufferHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, BufferHandle &) noexcept

Logically destroy an owned Buffer outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · BufferHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, TextureHandle) noexcept

Query asynchronous validation for an owned Texture record; stale/foreign handles are rejected.

Related types: RasterStatus · DeviceHandle · TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, TextureHandle &) noexcept

Logically destroy an owned Texture outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · DeviceHandle · TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, TextureViewHandle) noexcept

Query asynchronous validation for an owned TextureView record; stale/foreign handles are rejected.

Related types: RasterStatus · DeviceHandle · TextureViewHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, TextureViewHandle &) noexcept

Logically destroy an owned TextureView outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · DeviceHandle · TextureViewHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, SamplerHandle) noexcept

Query asynchronous validation for an owned Sampler record; stale/foreign handles are rejected.

Related types: RasterStatus · DeviceHandle · SamplerHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, SamplerHandle &) noexcept

Logically destroy an owned Sampler outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · DeviceHandle · SamplerHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, RasterShaderHandle) noexcept

Query asynchronous validation for an owned RasterShader record; stale/foreign handles are rejected.

Related types: RasterStatus · DeviceHandle · RasterShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, RasterShaderHandle &) noexcept

Logically destroy an owned RasterShader outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · DeviceHandle · RasterShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, BindingLayoutHandle) noexcept

Query asynchronous validation for an owned BindingLayout record; stale/foreign handles are rejected.

Related types: RasterStatus · BindingLayoutHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, BindingLayoutHandle &) noexcept

Logically destroy an owned BindingLayout outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · BindingLayoutHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, BindingSetHandle) noexcept

Query asynchronous validation for an owned BindingSet record; stale/foreign handles are rejected.

Related types: RasterStatus · BindingSetHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, BindingSetHandle &) noexcept

Logically destroy an owned BindingSet outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · BindingSetHandle · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, RasterPipelineHandle) noexcept

Query asynchronous validation for an owned RasterPipeline record; stale/foreign handles are rejected.

Related types: RasterStatus · DeviceHandle · RasterPipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, RasterPipelineHandle &) noexcept

Logically destroy an owned RasterPipeline outside frames, zeroing the supplied handle. Retained dependencies/GPU uses delay physical release. Invalid handles preserve output.

Related types: RasterStatus · DeviceHandle · RasterPipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/raster.h

GetRayResourceStats¶

RasterStatus ludus::graphics::rhi::GetRayResourceStats(DeviceHandle, RayResourceStats &) noexcept

Nonblocking collection followed by a device-wide known resource snapshot. Failure preserves output; Unsupported means no negotiated native ray profile.

Related types: RasterStatus · DeviceHandle · RayResourceStats

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetRayCapabilities¶

RasterStatus ludus::graphics::rhi::GetRayCapabilities(DeviceHandle, RayCapabilities &) noexcept

Query negotiated native ray operations without allocating or launching work. Invalid owner preserves output; unavailable backend zeros it and returns Unsupported.

Related types: RasterStatus · DeviceHandle · RayCapabilities

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

CreateRayQueryProgram¶

RasterStatus ludus::graphics::rhi::CreateRayQueryProgram(DeviceHandle, const ShaderDescription &, RayQueryProgram &) noexcept

Create the fixed query program from the installed RT0 kernel artifact. Stage must be Compute. Vulkan uses SPIR-V RayQueryKHR; Metal uses its cooked MSL 2.4 variant. Owner-thread/between-frames only. Failure preserves null output.

Related types: RasterStatus · DeviceHandle · RayQueryProgram · ShaderDescription

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

CreateRayGeometry¶

RasterStatus ludus::graphics::rhi::CreateRayGeometry(DeviceHandle, const RayGeometryDescription &, RayGeometryHandle &) noexcept

Asynchronously build a copied immutable BLAS. Ready/Pending publishes ownership; failure preserves null output. Owner-thread/between-frames only.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

CreateRayScene¶

RasterStatus ludus::graphics::rhi::CreateRayScene(DeviceHandle, const RaySceneDescription &, RaySceneHandle &) noexcept

Asynchronously build a TLAS/opacity table. Pending BLAS returns NotReady without publishing output. Ready/Pending retains every exact input version. Between frames.

Related types: RasterStatus · DeviceHandle · RaySceneDescription · RaySceneHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

SubmitRayQueries¶

RasterStatus ludus::graphics::rhi::SubmitRayQueries(DeviceHandle, RayQueryProgram, RaySceneHandle, const RayInput *rays, ludus::foundation::usize count, RayQueryBatch &) noexcept

Submit a bounded immutable ray batch between frames. Copies every ray; retains program/scene until completion. Count must be positive and within negotiated limits. Pending dependencies return NotReady; other failures preserve null output.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, RayGeometryHandle) noexcept

Nonblocking poll of a BLAS build; stale/foreign identity returns InvalidHandle.

Related types: RasterStatus · DeviceHandle · RayGeometryHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, RaySceneHandle) noexcept

Nonblocking poll of a TLAS build; stale/foreign identity returns InvalidHandle.

Related types: RasterStatus · DeviceHandle · RaySceneHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, RayQueryProgram) noexcept

Query program readiness; stale/foreign identity returns InvalidHandle.

Related types: RasterStatus · DeviceHandle · RayQueryProgram

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle, RayQueryBatch) noexcept

Nonblocking poll of an accepted query batch; failure still requires Destroy.

Related types: RasterStatus · DeviceHandle · RayQueryBatch

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

ReadRayResults¶

RasterStatus ludus::graphics::rhi::ReadRayResults(DeviceHandle, RayQueryBatch, RayResult *, ludus::foundation::usize count) noexcept

Copy completed query results into exactly Count records. NotReady/failure preserves output; no mapping/wait occurs until the native completion is ready.

Related types: ludus::foundation::usize · RasterStatus · DeviceHandle · RayQueryBatch · RayResult

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetRayAllocation¶

RasterStatus ludus::graphics::rhi::GetRayAllocation(DeviceHandle, RayGeometryHandle, RayAllocation &) noexcept

Query native geometry byte categories; invalid identity preserves output.

Related types: RasterStatus · DeviceHandle · RayAllocation · RayGeometryHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetRayAllocation¶

RasterStatus ludus::graphics::rhi::GetRayAllocation(DeviceHandle, RaySceneHandle, RayAllocation &) noexcept

Query native scene byte categories; invalid identity preserves output.

Related types: RasterStatus · DeviceHandle · RayAllocation · RaySceneHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

GetRayAllocation¶

RasterStatus ludus::graphics::rhi::GetRayAllocation(DeviceHandle, RayQueryBatch, RayAllocation &) noexcept

Query native batch byte categories; invalid identity preserves output.

Related types: RasterStatus · DeviceHandle · RayAllocation · RayQueryBatch

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, RayGeometryHandle &) noexcept

Detach geometry ownership between frames. Scenes/builds retain accepted uses. Invalid identity preserves handle; success clears it.

Related types: RasterStatus · DeviceHandle · RayGeometryHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, RaySceneHandle &) noexcept

Detach scene ownership between frames; pending batches keep the scene alive. Invalid identity preserves handle; success clears it.

Related types: RasterStatus · DeviceHandle · RaySceneHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, RayQueryProgram &) noexcept

Detach program ownership between frames; pending batches retain its pipeline. Invalid identity preserves handle; success clears it.

Related types: RasterStatus · DeviceHandle · RayQueryProgram

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle, RayQueryBatch &) noexcept

Detach batch ownership between frames; pending GPU work retires on completion. Invalid identity preserves handle; success clears it. Does not cancel submitted rays.

Related types: RasterStatus · DeviceHandle · RayQueryBatch

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/ray.h

CreateShader¶

ResourceStatus ludus::graphics::rhi::CreateShader(const ShaderDescription &, ShaderHandle &) noexcept

Bounded slice: eight resources of each kind; uniform size 16..16384, multiple of 16, further bounded by StartupInfo.Capabilities.MaxUniformBufferSize.

Upload bytes follow the application's independently verified layouts.

Related types: ResourceStatus · ShaderDescription · ShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

CreateUniform¶

ResourceStatus ludus::graphics::rhi::CreateUniform(ludus::foundation::usize size, UniformHandle &) noexcept

Related types: ludus::foundation::usize · ResourceStatus · UniformHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

CreatePipeline¶

ResourceStatus ludus::graphics::rhi::CreatePipeline(const PipelineDescription &, PipelineHandle &) noexcept

Pending means the output owns a resource.

Pending dependencies instead return NotReady without creating a pipeline; poll those dependencies before retrying.

Related types: ResourceStatus · PipelineDescription · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

GetStatus¶

ResourceStatus ludus::graphics::rhi::GetStatus(ShaderHandle) noexcept

Related types: ResourceStatus · ShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

GetStatus¶

ResourceStatus ludus::graphics::rhi::GetStatus(UniformHandle) noexcept

Related types: ResourceStatus · UniformHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

GetStatus¶

ResourceStatus ludus::graphics::rhi::GetStatus(PipelineHandle) noexcept

Related types: ResourceStatus · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

GetFrameInfo¶

FrameInfo ludus::graphics::rhi::GetFrameInfo() noexcept

Acquired extent/attachment conversion, valid only in an open frame. Offscreen-only frames report their logical target extent; encoding remains the surface format.

Related types: FrameInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

UpdateUniform¶

ResourceStatus ludus::graphics::rhi::UpdateUniform(UniformHandle, std::span< const ludus::foundation::uint8 >) noexcept

Full replacement between frames or before the open frame's first draw.

No allocation; latest bytes are snapshotted into the next acquired frame. A uniform must be updated before its first draw.

Related types: ludus::foundation::uint8 · ResourceStatus · UniformHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

Destroy¶

ResourceStatus ludus::graphics::rhi::Destroy(ShaderHandle) noexcept

Related types: ResourceStatus · ShaderHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

Destroy¶

ResourceStatus ludus::graphics::rhi::Destroy(UniformHandle) noexcept

Related types: ResourceStatus · UniformHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

Destroy¶

ResourceStatus ludus::graphics::rhi::Destroy(PipelineHandle) noexcept

Related types: ResourceStatus · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

DrawFullscreen¶

ResourceStatus ludus::graphics::rhi::DrawFullscreen(PipelineHandle) noexcept

Exactly one non-indexed triangle in an open frame, current full surface extent.

Pending/failed/stale resources and a second draw are rejected.

Related types: ResourceStatus · PipelineHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/render.h

Start¶

StartStatus ludus::graphics::rhi::Start(const ApplicationInfo &appInfo, const WindowInfo &windowInfo) noexcept

Start the main-thread session using Auto backend selection.

Native Auto selects Vulkan on Linux, Metal on macOS and Direct3D 12 on Windows. Duplicate calls are Busy until Shutdown, including failed/lost sessions. The window/canvas must outlive the session. Browser startup is asynchronous; poll GetStartup.

Related types: StartStatus · WindowInfo · ApplicationInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

Start¶

StartStatus ludus::graphics::rhi::Start(const ApplicationInfo &appInfo, const WindowInfo &windowInfo, BackendSelection selection) noexcept

Explicit browser backend selection. Native rejects forced browser backends.

Related types: StartStatus · BackendSelection · WindowInfo · ApplicationInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

Start¶

StartStatus ludus::graphics::rhi::Start(const ApplicationInfo &appInfo, const WindowInfo &windowInfo, BackendSelection selection, const DeviceRequirements &requirements) noexcept

Related types: StartStatus · BackendSelection · WindowInfo · ApplicationInfo · DeviceRequirements

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

GetStartup¶

StartupInfo ludus::graphics::rhi::GetStartup() noexcept

Related types: StartupInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

SetFrameTarget¶

FrameStatus ludus::graphics::rhi::SetFrameTarget(const FrameTarget &target) noexcept

Related types: FrameStatus · FrameTarget

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

BeginFrameStatus¶

FrameStatus ludus::graphics::rhi::BeginFrameStatus() noexcept

Related types: FrameStatus

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

EndFrameStatus¶

FrameStatus ludus::graphics::rhi::EndFrameStatus() noexcept

Related types: FrameStatus

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

Initialize¶

bool ludus::graphics::rhi::Initialize(const ApplicationInfo &appInfo) noexcept

Native synchronous compatibility startup; browser returns false. Use Start/GetStartup there.

Precondition

Do not mix the synchronous and asynchronous lifecycle entry points.

Related types: ApplicationInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

ConnectWindow¶

bool ludus::graphics::rhi::ConnectWindow(const WindowInfo &windowInfo) noexcept

Related types: WindowInfo

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

InitializeRendering¶

bool ludus::graphics::rhi::InitializeRendering() noexcept

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

ShutdownRendering¶

void ludus::graphics::rhi::ShutdownRendering() noexcept

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

Shutdown¶

void ludus::graphics::rhi::Shutdown() noexcept

Idempotent; invalidates callbacks and ordinary RHI handles before native cleanup. Native interop device/read leases defer physical cleanup until consumer GPU completion and final lease release. Startup remains Busy while that retirement is pending.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

BeginFrame¶

bool ludus::graphics::rhi::BeginFrame() noexcept

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

EndFrame¶

bool ludus::graphics::rhi::EndFrame() noexcept

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/rhi.h

GetSpatialUpscaleCapabilities¶

RasterStatus ludus::graphics::rhi::GetSpatialUpscaleCapabilities(DeviceHandle device, SpatialUpscaleCapabilities &outCapabilities) noexcept

Query support without allocating an effect. Ready with a false capability is a valid unsupported backend/device. Invalid or non-ready devices preserve output.

Related types: RasterStatus · DeviceHandle · SpatialUpscaleCapabilities

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/spatial_upscale.h

CreateSpatialUpscaler¶

RasterStatus ludus::graphics::rhi::CreateSpatialUpscaler(DeviceHandle device, const SpatialUpscalerDescription &description, SpatialUpscalerHandle &outUpscaler) noexcept

Prepare an immutable effect outside frames. Only Ready/Pending publish the previously empty output; failures preserve it. Unsupported is explicit on non-Metal backends and Metal devices without MetalFX Spatial. No fallback.

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/spatial_upscale.h

GetStatus¶

RasterStatus ludus::graphics::rhi::GetStatus(DeviceHandle device, SpatialUpscalerHandle upscaler) noexcept

Query readiness of a live effect identity; stale or foreign owners return InvalidHandle.

Related types: SpatialUpscalerHandle · RasterStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/spatial_upscale.h

Destroy¶

RasterStatus ludus::graphics::rhi::Destroy(DeviceHandle device, SpatialUpscalerHandle &inoutUpscaler) noexcept

Release ownership between frames, preserving the handle on failure. Submitted uses delay physical retirement; Ready clears the handle. No GPU wait occurs.

Related types: SpatialUpscalerHandle · RasterStatus · DeviceHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/spatial_upscale.h

EncodeSpatialUpscale¶

RasterStatus ludus::graphics::rhi::EncodeSpatialUpscale(DeviceHandle device, SpatialUpscalerHandle upscaler, TextureHandle source, TextureHandle destination) noexcept

Encode native reconstruction in the acquired RHI frame, following preceding producers on the same queue. Both textures must be distinct RGBA8 D2 images, one mip/layer/sample, with the exact configured dimensions. Source color must be initialized; destination must be a private offscreen attachment with no external readers. Ready fully defines color and invalidates private depth/stencil. Validation failures preserve the current pass. An accepted call ends it; subsequent raster draws require BeginRasterPass. The frame retains effect and textures through submission completion. No pipeline creation or CPU copies.

Related types: SpatialUpscalerHandle · RasterStatus · DeviceHandle · TextureHandle

Declared in modules/graphics/rhi/include/ludus/graphics/rhi/spatial_upscale.h

ludus::graphics::rhi¶

Related declarations¶

Enumerations¶

ComputeCachePhase¶

Empty¶

Preparing¶

Prepared¶

AwaitingSubmission¶

Executing¶

Failed¶

DeviceStatus¶

Ready¶

Pending¶

Skipped¶

NotReady¶

InvalidHandle¶

InvalidState¶

InvalidDescription¶

Unsupported¶

Failed¶

DeviceLost¶

IdentityExhausted¶

GpuPassKind¶

Raster¶

Compute¶

RayTracing¶

RasterLoad¶

Clear¶

Load¶

Discard¶

RasterStore¶

Store¶

Discard¶

RasterTextureUse¶

Undefined¶

SampledVertex¶

SampledFragment¶

SampledBoth¶

SampledCompute¶

ColorAttachment¶

GraphAccessMode¶

Vertex¶

Index¶

Uniform¶

Sampled¶

ColorWrite¶

ColorReadWrite¶

StorageRead¶

StorageReadWrite¶

Indirect¶

GraphRoot¶

Export¶

History¶

Readback¶

GraphHazard¶

ReadAfterWrite¶

WriteAfterRead¶

WriteAfterWrite¶

HostedConsumerRefusal¶

None¶

AdapterMismatch¶

UnsupportedHandle¶

ImportFailed¶

ProtocolViolation¶

HostedConsumerStatus¶

Ok¶

Empty¶

Refused¶

NotConnected¶

InvalidState¶

InvalidArgument¶

Unavailable¶

GpuTimingState¶

Empty¶

Armed¶

Pending¶

Available¶

Unavailable¶

Disjoint¶

Failed¶