Skip to content

ludus::foundation::geometry

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/convex_polygon.hpp

Enumerations

FrameSeedPolicy

enum class FrameSeedPolicy : uint8
What TryBuildFrames does when the seed direction is nearly parallel to the starting tangent.

Related types: uint8

RejectDegenerateSeed

RejectDegenerateSeed
Fail with DegenerateFrame.

UseFallbackAxis

UseFallbackAxis
Project FramePreparation::FallbackAxis instead and record that choice in the run.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

FrameSingularityPolicy

enum class FrameSingularityPolicy : uint8
What TryBuildFrames does where the tangent is undefined: zero speed, cusps and reversals inside a span.

Related types: uint8

Reject

Reject
Fail with DegenerateFrame and report the offending parameter range.

SplitRuns

SplitRuns
End the current frame run before the singular range and seed a new run after it.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

FrameCornerPolicy

enum class FrameCornerPolicy : uint8
What TryBuildFrames does at a joint that is not G1 under the path's ContinuityAngle.

Related types: uint8

Reject

Reject
Fail with DegenerateFrame.

RotateMinimally

RotateMinimally
Rotate about the incoming x outgoing tangent axis; an (almost) exact reversal fails.

SplitRuns

SplitRuns
End the run at the joint and seed a new run on the outgoing span.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

ClosedFramePolicy

enum class ClosedFramePolicy : uint8
Residual-twist policy of a closed path, part of the frame cache key.

Related types: uint8

DistributeTwist

DistributeTwist
Add a compensating roll proportional to estimated arc distance so the seam is periodic.

PreserveHolonomy

PreserveHolonomy
Keep the transported frames; the seam frame differs by ResidualTwist.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

SpanKind

enum class SpanKind : uint8
Polynomial kind of one span.

Related types: uint8

Line

Line
Linear segment from Control[0] to Control[3]; Control[1] and Control[2] are ignored on input.

Cubic

Cubic
Cubic Bezier span with four controls.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

GeometryStatus

enum class GeometryStatus : uint8
Result of a Geometry preparation, sampling or query operation (ADR 0024).
Enumerator names are frozen; numeric values and multi-failure precedence are not an ABI or file format, so serialized diagnostics store GetStatusName(). Every failing operation leaves its outputs unchanged. A geometric miss is Success with a classification in the result record.

Related types: uint8

Success

Success
Outputs are written and meaningful.

NonFiniteInput

NonFiniteInput
A NaN or infinity where a finite value is required.

InvalidArgument

InvalidArgument
Malformed request or profile: negative tolerance, unknown policy, Wrap on an open path.

InvalidDomain

InvalidDomain
Outside the domain under Reject; nonincreasing keys; coincident consecutive waypoints.

InvalidTopology

InvalidTopology
Unsupported or inconsistent adjacency, edge or corner records, such as disconnected spans.

MissingCache

MissingCache
The snapshot lacks the cache the request needs; sampling never builds it.

StaleRevision

StaleRevision
A cursor, view or cache revision does not match its snapshot.

Degenerate

Degenerate
A requested direction or normal is undefined there; position may still be valid.

DegenerateFrame

DegenerateFrame
A framed profile cannot define a transported frame run under its policy.

IllConditioned

IllConditioned
Below a named conditioning threshold.

OutOfRange

OutOfRange
Finite inputs whose result cannot be represented.

UnsupportedRepresentation

UnsupportedRepresentation
Valid source geometry this version cannot represent.

UnsupportedPrecision

UnsupportedPrecision
Tolerance below the arithmetic floor, or a strict profile lacks a certificate.

BudgetExceeded

BudgetExceeded
A work, depth, iteration or output budget was exhausted.

CapacityExceeded

CapacityExceeded
A caller-owned output range is too small; detected before writing.

OutOfMemory

OutOfMemory
A fallible allocation failed.

Cancelled

Cancelled
The caller cancelled preparation.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

GuaranteeClass

enum class GuaranteeClass : uint8
How a reported bound or value is guaranteed (ADR 0024).

Related types: uint8

Exact

Exact
Bitwise defined: stored endpoints, decisions on stored values, exact identities.

Rounded

Rounded
One float64 computation narrowed to float32; no error bound is promised.

Certified

Certified
Enclosure from reviewed outward-rounded arithmetic.

Estimated

Estimated
Heuristic, padded or sampled bound, reported with its class.

Approximate

Approximate
Separately named mode that returns its candidate and achieved residual.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

PrecisionProfile

enum class PrecisionProfile : uint8
Which bounds a preparation accepts.

Related types: uint8

Strict

Strict
Only Exact or Certified bounds; otherwise UnsupportedPrecision and no output change.

Visual

Visual
Estimated bounds are accepted and reported with their class.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

DomainKind

enum class DomainKind : uint8
Kind of domain a value or diagnostic range is expressed in.

Related types: uint8

SegmentParameter

SegmentParameter
Span index and local u in [0,1].

SurfaceParameter

SurfaceParameter
Patch index and local (u, v) in [0,1]^2.

PathDistance

PathDistance
Prefix arc length in declared asset units.

TrackTime

TrackTime
Seconds from the track's local epoch.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

SpanSide

enum class SpanSide : uint8
Which span an exact interior key or span boundary selects.

Related types: uint8

Outgoing

Outgoing
The span that starts there, at u = 0 (the default).

Incoming

Incoming
The previous span at u = 1; at the first endpoint both sides select the first span.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

BoundaryPolicy

enum class BoundaryPolicy : uint8
Behavior outside the closed domain [start, end] of duration D; inside it every policy is identical.

Related types: uint8

Reject

Reject
InvalidDomain; outputs unchanged.

Clamp

Clamp
Nearest endpoint; derivatives are the one-sided ones from inside the domain.

Hold

Hold
Tracks only: nearest endpoint value with zero derivatives.

Loop

Loop
Tracks only: start + mod(x - start, D), in [start, end).

PingPong

PingPong
Tracks only: reflect with period 2D; the reflected half negates the first derivative.

Wrap

Wrap
Closed paths only: Loop over distance; an open path rejects it as InvalidArgument.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

PatchSide

enum class PatchSide : uint8
One boundary side of a patch, named by its fixed parameter.
Each side has an along-edge parameter s in [0,1]: v for U0 and U1, u for V0 and V1. Its control curve in increasing s is Control[0][k] (U0), Control[3][k] (U1), Control[k][0] (V0) or Control[k][3] (V1).

Related types: uint8

U0

U0
u = 0; runs along v.

U1

U1
u = 1; runs along v.

V0

V0
v = 0; runs along u.

V1

V1
v = 1; runs along u.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

PatchCorner

enum class PatchCorner : uint8
One corner of a patch, named by its (u, v) parameters.

Related types: uint8

U0V0

U0V0
(0, 0): Control[0][0].

U1V0

U1V0
(1, 0): Control[3][0].

U0V1

U0V1
(0, 1): Control[0][3].

U1V1

U1V1
(1, 1): Control[3][3].

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

SweepSection

enum class SweepSection : uint8
Cross-section swept along the path.

Related types: uint8

Ribbon

Ribbon
Flat strip along the frame binormal, Scale wide; faces the frame normal; no caps.

Tube

Tube
Closed circle of radius Scale approximated by a regular polygon with a duplicated UV seam column.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/sweep.hpp

SweepCaps

enum class SweepCaps : uint8
Ends of an open tube.

Related types: uint8

None

None
Leave the ends open.

Flat

Flat
Close each end with a flat fan; cap vertices copy ring positions with their own normals and UVs.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/sweep.hpp

SweepWinding

enum class SweepWinding : uint8
Front-face winding of emitted triangles, seen from the side their normals point to.

Related types: uint8

CounterClockwise

CounterClockwise
Counter-clockwise front faces.

Clockwise

Clockwise
Clockwise front faces.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/sweep.hpp

SurfaceDegeneracyPolicy

enum class SurfaceDegeneracyPolicy : uint8
How mesh preparation treats singular normals and collapsed triangles.

Related types: uint8

Reject

Reject
Fail with Degenerate or IllConditioned and keep the previous mesh.

Report

Report
Emit a zero normal with its status, keep collapsed triangles, and count both in the report.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/tessellation.hpp

SurfaceSampleKind

enum class SurfaceSampleKind : uint8
Topological owner of one emitted position.

Related types: uint8

Corner

Corner
A corner record; the position is its stored control (Exact).

Edge

Edge
An interior sample of an edge, evaluated once on the canonical curve.

Interior

Interior
An interior sample of one patch.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/tessellation.hpp

TrackInterpolation

enum class TrackInterpolation : uint8
Interpolation of the span that starts at a key.

Related types: uint8

Step

Step
Left key's value on [t0, t1), right key's value at t1; zero derivative.

Linear

Linear
Linear between the two key values.

Hermite

Hermite
Cubic from the left key's OutSlope to the right key's InSlope, per second.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/track.hpp

Constants and variables

MAX_CONVEX_POLYGON_VERTICES

constexpr usize ludus::foundation::geometry::MAX_CONVEX_POLYGON_VERTICES = math::MAX_PROJECTED_POLYGON_INPUT_VERTICES
Largest polygon in a partition; owned by projected solid angle sampling (paper supplement A.1).

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/convex_polygon.hpp

SPAN_CONTROL_COUNT

constexpr usize ludus::foundation::geometry::SPAN_CONTROL_COUNT = 4
Controls stored for every span; a line uses Control[0] and Control[3].

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

MAX_POINT_NEIGHBORS

constexpr usize ludus::foundation::geometry::MAX_POINT_NEIGHBORS = LUDUS_MAX_POINT_NEIGHBORS
Maximum neighbors returned by the bounded CPU/GPU point-search interface.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/point_search.hpp

POINT_SEARCH_STACK_SIZE

constexpr usize ludus::foundation::geometry::POINT_SEARCH_STACK_SIZE = LUDUS_POINT_SEARCH_STACK_SIZE
Maximum balanced tree traversal depth, sufficient for every uint32 node count.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/point_search.hpp

ABSENT_POINT_NODE

constexpr uint32 ludus::foundation::geometry::ABSENT_POINT_NODE = LUDUS_ABSENT_POINT_NODE
Sentinel for a missing child; never a valid node index.

Related types: uint32

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/point_search.hpp

MAX_POINT_SEARCH_COORDINATE

constexpr float32 ludus::foundation::geometry::MAX_POINT_SEARCH_COORDINATE = LUDUS_MAX_POINT_SEARCH_COORDINATE
Coordinate magnitude bound in world units, keeping float32 squared distances finite.

Related types: float32

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/point_search.hpp

PATCH_CONTROL_ORDER

constexpr usize ludus::foundation::geometry::PATCH_CONTROL_ORDER = 4
Controls along each direction of a bicubic patch and along each boundary curve.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

PATCH_SIDE_COUNT

constexpr usize ludus::foundation::geometry::PATCH_SIDE_COUNT = 4
Boundary sides of one patch.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

PATCH_CORNER_COUNT

constexpr usize ludus::foundation::geometry::PATCH_CORNER_COUNT = 4
Corners of one patch.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

MAX_EDGE_INCIDENCES

constexpr usize ludus::foundation::geometry::MAX_EDGE_INCIDENCES = 2
Largest number of patch sides incident to one edge (V1 manifold rule).

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

EDGE_CORNER_COUNT

constexpr usize ludus::foundation::geometry::EDGE_CORNER_COUNT = 2
Corner records at the start and end of one edge.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

MAX_SURFACE_MESH_LEVEL

constexpr usize ludus::foundation::geometry::MAX_SURFACE_MESH_LEVEL = 16
Largest dyadic level per patch direction a mesh profile may request (2^16 cells per direction).

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/tessellation.hpp

SURFACE_MESH_TRIANGLE_INDEX_COUNT

constexpr usize ludus::foundation::geometry::SURFACE_MESH_TRIANGLE_INDEX_COUNT = 3
Indices per emitted triangle.

Related types: usize

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/tessellation.hpp

Functions

TryPartitionConvexPolygons

GeometryStatus ludus::foundation::geometry::TryPartitionConvexPolygons(BorrowedView< const math::Vector3 > positionsMesh, BorrowedView< const uint32 > indices, ConvexPolygonPartition &outPartition) noexcept
Partition a triangle mesh into convex planar polygons for polygonal light sampling.
Triangles that share an edge (equal endpoint positions, opposite directions) merge when the result is coplanar, convex, simple and has at most MAX_CONVEX_POLYGON_VERTICES vertices after collinear vertices are removed. Merging along a chain of shared edges removes the chain's interior vertices, so a fan around a center vertex becomes one polygon when it fits. Every nondegenerate triangle ends in exactly one polygon; a lone triangle is a polygon of three vertices. Tolerances are relative to the polygon's extent and the float32 coordinate magnitude. The result is deterministic for a given input.
ParameterDescription
positionsMesh
Finite vertex positions in one Cartesian space; borrowed for this call.
indices
Triangle list; each index must name a position.
outPartition
Written only on success.

Returns

Success; InvalidArgument for invalid views or an index count that is not a multiple of three; InvalidTopology for an index outside positionsMesh; NonFiniteInput for a nonfinite referenced position; OutOfMemory when scratch or output storage cannot be allocated. outPartition is unchanged on failure.

Related types: BorrowedView · uint32 · GeometryStatus · ConvexPolygonPartition · math::Vector3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/convex_polygon.hpp

TryBuildDistanceMap

GeometryStatus ludus::foundation::geometry::TryBuildDistanceMap(const PathView &path, const DistancePreparation &preparation, PreparedDistanceMap &outMap, GeometryDiagnostic *outDiagnosticOrNull)
Build a distance map whose whole-path gap is at most path.Tolerance.DistanceError.
Refinement splits the leaf with the largest gap at its parameter midpoint; ties go to the earlier span and parameter, so the result is deterministic. The gap is rechecked with outward accumulation before success.
ParameterDescription
path
Borrowed prepared path; its Revision is recorded in the map.
preparation
Precision profile and work limits.
outMap
Replaced by the new map only on Success.
outDiagnosticOrNull
Optional; on BudgetExceeded it receives the achieved Certified gap.

Returns

Success; InvalidArgument for an empty path or zero limits; BudgetExceeded when a leaf, depth, subdivision or byte limit stops refinement; UnsupportedPrecision when every leaf is exact but outward accumulation still exceeds the gap; OutOfRange; OutOfMemory. outMap is replaced only on Success.

Related types: PreparedDistanceMap · GeometryStatus · DistancePreparation · GeometryDiagnostic · PathView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/distance.hpp

TryBoundDistance

GeometryStatus ludus::foundation::geometry::TryBoundDistance(const PathView &path, const DistanceMapView &map, SegmentParameter parameter, DistanceBound &outBound) noexcept
Enclose the arc length from the path start to parameter, including all preceding uncertainty.

Returns

MissingCache for an empty map; StaleRevision when the map does not belong to path; InvalidDomain or NonFiniteInput for a bad parameter; OutOfRange. outBound is unchanged on failure.

Related types: GeometryStatus · DistanceBound · DistanceMapView · PathView · SegmentParameter

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/distance.hpp

TryResolveDistance

GeometryStatus ludus::foundation::geometry::TryResolveDistance(const PathView &path, const DistanceMapView &map, const DistanceQuery &query, DistanceResolution &outResolution) noexcept
Find the earliest parameter whose prefix length matches a distance, with a residual bound.
The leaf is proposed by monotone lookup over prefix estimates, and the parameter by bisection on partial-span estimates. Acceptance uses the Certified residual bound, which must not exceed the map's DistanceError. Zero-length runs resolve to their earliest parameter; the path end resolves to the last span at u = 1. Near zero speed the parameter is ill-conditioned even though the residual is bounded; request a tangent to detect that.

Returns

MissingCache; StaleRevision; NonFiniteInput; InvalidDomain outside [0, TotalEstimate] under Reject; InvalidArgument for Hold, Loop, PingPong, an unknown policy or side, or Wrap on an open path; BudgetExceeded when MaxIterations ends before the residual fits; OutOfRange. outResolution is unchanged on failure.

Related types: GeometryStatus · DistanceMapView · DistanceQuery · DistanceResolution · PathView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/distance.hpp

TryBuildFrames

GeometryStatus ludus::foundation::geometry::TryBuildFrames(const PathView &path, const DistanceMapView &map, const FramePreparation &preparation, PreparedFrames &outFrames, GeometryDiagnostic *outDiagnosticOrNull)
Bake rotation-minimizing frames for a prepared path.
Each span is stepped over dyadic intervals. An interval is regular when an outward-rounded box of its derivative stays farther than MinimumSpeed from zero (a Certified decision). A regular interval is accepted when one double-reflection step and two half steps differ by at most path.Tolerance.TangentAngleError x width / span count; otherwise it is halved. Intervals that cannot be shown regular at the depth limit are singular and follow SingularityPolicy; intervals whose derivative box lies inside the MinimumSpeed ball are skipped whole. The first run starts from SeedUp projected perpendicular to the first tangent, or from FallbackAxis. Non-G1 joints follow CornerPolicy. A closed path needs a G1 closing joint and a single run for DistributeTwist, which adds -ResidualTwist + 2 pi WindingTurns of roll in proportion to estimated distance.
ParameterDescription
path
Borrowed prepared path.
map
Distance map of the same path revision; provides sample distances and the twist distribution.
preparation
Seed, policies and limits.
outFrames
Replaced by the new cache only on Success.
outDiagnosticOrNull
Optional; receives the failure, its span and parameter range.

Returns

Success; InvalidArgument for an empty path or a malformed preparation; NonFiniteInput; MissingCache or StaleRevision for the distance map; UnsupportedPrecision for a Strict profile; DegenerateFrame when a policy rejects a seed, singularity, corner or closed seam; BudgetExceeded when a sample, depth, test or byte limit stops baking; OutOfRange; OutOfMemory. outFrames is replaced only on Success.

Related types: PreparedFrames · GeometryStatus · DistanceMapView · FramePreparation · GeometryDiagnostic · PathView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

TryEvaluateFrame

GeometryStatus ludus::foundation::geometry::TryEvaluateFrame(const PathView &path, const FramesView &frames, SegmentParameter parameter, float64 rollRadians, TransportedFrame &outFrame) noexcept
Evaluate a transported frame with an authored roll about the tangent.
The result depends only on the path, the frames and the request, never on earlier queries. It transports the preceding baked sample of the same span and run to the analytic tangent with one double-reflection step, then rotates by the interpolated twist compensation plus rollRadians (right-handed about Tangent). An exact sample parameter returns that sample.
ParameterDescription
path
Borrowed path the frames were built from.
frames
Borrowed frame cache.
parameter
Span index and u in [0,1]; u = 1 selects the incoming side of a joint.
rollRadians
Finite authored roll.
outFrame
Written only on Success.

Returns

MissingCache for empty frames; StaleRevision for frames of another revision; NonFiniteInput; InvalidDomain for a bad parameter; Degenerate where no run covers the parameter, such as at a cusp or zero-speed endpoint; OutOfRange. outFrame is unchanged on failure.

Related types: float64 · GeometryStatus · FramesView · PathView · SegmentParameter · TransportedFrame

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

TryPreparePath

GeometryStatus ludus::foundation::geometry::TryPreparePath(const PathSource &source, const PathPreparation &preparation, PreparedPath &outPath, GeometryDiagnostic *outDiagnosticOrNull)
Validate a source path and build a new prepared owner.
Checks: a valid tolerance profile; at least one span within Limits.MaxSpans; finite controls, origin and positive domain widths; a known span kind; consecutive spans (and the closing joint of a closed path) whose stored endpoints are within ContinuityPosition; the float32 position floor of the narrowed controls and their narrowing error against the effective position error; and the prepared byte size against Limits.MaxPreparedBytes.
ParameterDescription
source
Source spans and origin, borrowed for the call only.
preparation
Tolerance profile and limits; the profile is copied into the path.
outPath
Replaced by the new owner only on Success.
outDiagnosticOrNull
Optional; receives the first failure's details.

Returns

Success; NonFiniteInput; InvalidArgument; InvalidTopology for a gap; UnsupportedPrecision when the effective position error is below the floor or narrowing error; OutOfRange when a relative control exceeds float32; BudgetExceeded; OutOfMemory. outPath is replaced only on Success.

Related types: PreparedPath · GeometryStatus · GeometryDiagnostic · PathPreparation · PathSource

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

TryEvaluatePath

GeometryStatus ludus::foundation::geometry::TryEvaluatePath(const PathView &path, SegmentParameter parameter, math::Vector3 &outPosition) noexcept
Evaluate a chunk-relative position at a segment parameter (Rounded; endpoints Exact).

Returns

InvalidDomain for an empty view, a span index out of range or U outside [0,1]; NonFiniteInput for a nonfinite U; OutOfRange. outPosition is unchanged on failure.

Related types: GeometryStatus · PathView · SegmentParameter · math::Vector3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

TryEvaluatePath

GeometryStatus ludus::foundation::geometry::TryEvaluatePath(const PathView &path, SegmentParameter parameter, math::CubicSample3 &outSample) noexcept
Evaluate position and first/second derivatives per normalized u, with the position overload's contract.

Related types: GeometryStatus · PathView · SegmentParameter · math::CubicSample3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

TryEvaluatePathTangent

GeometryStatus ludus::foundation::geometry::TryEvaluatePathTangent(const PathView &path, SegmentParameter parameter, float64 minimumSpeed, math::Vector3 &outTangent) noexcept
Unit tangent dP/du / |dP/du| at a segment parameter (Rounded).
ParameterDescription
path
Borrowed prepared path.
parameter
Span index and u in [0,1].
outTangent
Unit direction written only on Success.
minimumSpeed
Asset units per unit u; finite and >= 0. The direction is undefined at or below it.

Returns

Degenerate when |dP/du| <= minimumSpeed (for example at a cusp or a zero-speed endpoint), plus the TryEvaluatePath statuses and InvalidArgument for a negative minimumSpeed. outTangent is unchanged on failure.

Related types: float64 · GeometryStatus · PathView · SegmentParameter · math::Vector3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

TryGetSpanControlBounds

GeometryStatus ludus::foundation::geometry::TryGetSpanControlBounds(const PathView &path, usize spanIndex, math::Aabb3 &outBounds) noexcept
Axis-aligned box of a span's stored controls, which encloses the exact span (Exact).

Returns

InvalidDomain for an out-of-range span index; outBounds is unchanged on failure.

Related types: usize · GeometryStatus · PathView · math::Aabb3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

TryConvertHermite

GeometryStatus ludus::foundation::geometry::TryConvertHermite(BorrowedView< const HermiteWaypoint > waypoints, bool isClosed, BorrowedView< PathSpanSource > outSpans, usize &outSpanCount) noexcept
Convert Hermite waypoints to cubic spans: B1 = P0 + h*T0/3 and B2 = P1 - h*T1/3.
An open path of n waypoints yields n - 1 spans; a closed path yields n spans, the last returning to the first waypoint. The last waypoint's OutgoingWidth is used only when closed. Spans carry their width as DomainWidth and their starting waypoint index as SourceElement. Arithmetic is float64 (Rounded).
ParameterDescription
waypoints
Source waypoints, borrowed for the call only.
isClosed
Whether the last waypoint connects back to the first.
outSpans
Caller-owned range; capacity is checked before anything is written.
outSpanCount
Number of spans written, set only on Success.

Returns

InvalidArgument for fewer than 2 waypoints (3 when closed) or a nonpositive width; NonFiniteInput; OutOfRange for an overflowing control; CapacityExceeded. Outputs are unchanged on failure.

Related types: BorrowedView · usize · GeometryStatus · HermiteWaypoint · PathSpanSource

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

TryConvertCentripetalCatmullRom

GeometryStatus ludus::foundation::geometry::TryConvertCentripetalCatmullRom(BorrowedView< const math::Vector3d > waypoints, bool isClosed, float64 coincidenceDistance, BorrowedView< PathSpanSource > outSpans, usize &outSpanCount) noexcept
Convert waypoints to cubic spans with centripetal Catmull-Rom (knot step sqrt of chord length).
Interior tangents use the nonuniform Barry-Goldman formula; an open path's endpoints use the one-sided chord tangent. A closed path wraps neighbors and must not store its first waypoint again at the end. Spans carry their knot width as DomainWidth and their starting waypoint index as SourceElement. Arithmetic is float64 (Rounded).
ParameterDescription
waypoints
Source waypoints in asset units, borrowed for the call only.
isClosed
Whether the path wraps from the last waypoint to the first.
outSpans
Caller-owned range; capacity is checked before anything is written.
outSpanCount
Number of spans written, set only on Success.
coincidenceDistance
Asset units; finite and > 0. Consecutive waypoints (including the closing pair) at or below this distance are rejected.

Returns

InvalidArgument for fewer than 2 waypoints (3 when closed) or a bad coincidence distance; InvalidDomain for coincident consecutive waypoints; NonFiniteInput; OutOfRange; CapacityExceeded. Outputs are unchanged on failure.

Related types: BorrowedView · float64 · usize · GeometryStatus · PathSpanSource · math::Vector3d

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/path.hpp

ComputeProjectionScratchCapacity

GeometryStatus ludus::foundation::geometry::ComputeProjectionScratchCapacity(const PathView &path, usize maxIterations, usize &outCapacity) noexcept
Scratch entries a query needs: span count + 1 + maxIterations (each split adds at most one).

Returns

Success, or OutOfRange when the sum overflows. outCapacity is unchanged on failure.

Related types: usize · GeometryStatus · PathView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/query.hpp

TryProjectPoint

GeometryStatus ludus::foundation::geometry::TryProjectPoint(const PathView &path, const ProjectionQuery &query, ProjectionScratch &inoutScratch, ProjectionResult &outResult) noexcept
Strict closest-point projection with a Certified global distance gap.
Every span starts as one interval whose control-hull box bounds its distance from below; span starts and the terminal endpoint are candidates. Each iteration splits the interval with the smallest lower bound (ties: earlier span, then smaller parameter) at its midpoint, evaluates the midpoint as a candidate and discards intervals whose lower bound exceeds the best candidate. The search stops when the best candidate's distance minus the smallest live lower bound is at most half of path.Tolerance.ProjectionGap; the other half is the tie margin below. All bounds use outward-rounded enclosures, so the gap is Certified.
Ties: every point whose distance is within ProjectionGap of the global lower bound is acceptable. Once the search stops, the earliest live interval whose lower bound allows a point within half the gap is split until it contains an acceptable candidate or its bound rules it out. Every global minimizer lies in such an interval, and the margin makes this search terminate. The result is the earliest acceptable candidate by span then parameter, so symmetric minima resolve to the earlier minimum and an endpoint within the gap wins over later interiors. This tie search shares MaxIterations; intervals are kept while their lower bound is within ProjectionGap of the best candidate.
ParameterDescription
path
Borrowed prepared path.
query
Point and iteration limit.
inoutScratch
Reserved storage of at least ComputeProjectionScratchCapacity entries; contents are scratch.
outResult
Written only on Success, with Guarantee Certified and IsGapMet true.

Returns

Success; InvalidArgument for an empty path; NonFiniteInput; CapacityExceeded when the scratch is too small (checked before searching); BudgetExceeded when MaxIterations ends before the gap is met or the tie is resolved; UnsupportedPrecision when an interval reaches float64 parameter resolution with the gap still open; OutOfRange. outResult is unchanged on failure.

Related types: ProjectionScratch · GeometryStatus · PathView · ProjectionQuery · ProjectionResult

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/query.hpp

ProjectPointApproximate

GeometryStatus ludus::foundation::geometry::ProjectPointApproximate(const PathView &path, const ProjectionQuery &query, ProjectionScratch &inoutScratch, ProjectionResult &outResult) noexcept
Approximate projection: TryProjectPoint's search that returns its candidate when work runs out.
When the gap is not met, the result is the earliest candidate with the smallest distance found, IsGapMet is false and Gap reports the remaining outward-rounded gap. Guarantee is always Approximate, which never satisfies a strict profile.

Returns

TryProjectPoint's input and capacity statuses, OutOfRange, or Success; work exhaustion is Success. outResult is unchanged on failure.

Related types: ProjectionScratch · GeometryStatus · PathView · ProjectionQuery · ProjectionResult

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/query.hpp

IsSuccess

constexpr bool ludus::foundation::geometry::IsSuccess(GeometryStatus status) noexcept
Whether status is GeometryStatus::Success.

Related types: GeometryStatus

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

GetStatusName

const char * ludus::foundation::geometry::GetStatusName(GeometryStatus status) noexcept
Frozen enumerator name for serialized diagnostics, or "Unknown" for an out-of-range value.

Returns

A static, null-terminated string; never null.

Related types: GeometryStatus

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

GetGuaranteeClassName

const char * ludus::foundation::geometry::GetGuaranteeClassName(GuaranteeClass guarantee) noexcept
Frozen enumerator name of a guarantee class, or "Unknown" for an out-of-range value.

Related types: GuaranteeClass

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

IsStrictGuarantee

constexpr bool ludus::foundation::geometry::IsStrictGuarantee(GuaranteeClass guarantee) noexcept
Whether a strict preparation profile accepts a bound of this class (Exact or Certified only).

Related types: GuaranteeClass

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

TryValidateToleranceProfile

GeometryStatus ludus::foundation::geometry::TryValidateToleranceProfile(const ToleranceProfile &profile) noexcept
Check every ToleranceProfile field against its ADR 0024 range.
The position floor depends on the prepared controls and is checked by the preparation that knows them, not here.

Returns

Success, NonFiniteInput for a NaN or infinite field, or InvalidArgument for a finite out-of-range field.

Related types: GeometryStatus · ToleranceProfile

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

ComputePositionFloor

float64 ludus::foundation::geometry::ComputePositionFloor(float64 maxAbsComponent) noexcept
Float32 position floor 2 * ulp32(E) for chunk-relative controls of largest absolute component E.
ulp32(E) = 2^(floor(log2 E) - 23) for E in the float32 normal range. Below it the floor is two subnormal units (2^-148); E = 0 also returns that value. The floor is an Exact policy value, not a promise that a computation achieves it.

Precondition

E is finite and nonnegative.

Related types: float64

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

TryPrepareSurface

GeometryStatus ludus::foundation::geometry::TryPrepareSurface(const SurfaceSource &source, const SurfacePreparation &preparation, PreparedSurface &outSurface, GeometryDiagnostic *outDiagnosticOrNull)
Validate a source surface and build a new prepared owner with its topology.
Checks: a valid tolerance profile; at least one patch within Limits.MaxPatches; unique patch IDs; finite controls, origin and asset scale; the float32 position floor of the narrowed controls and their narrowing error against the effective position error; adjacency records that name existing patches and known sides, use each patch side at most once, never join a side to itself, and whose narrowed control curves are equal after the declared orientation mapping; and the prepared byte size against Limits.MaxPreparedBytes.
ParameterDescription
source
Source patches, adjacency and origin, borrowed for the call only.
preparation
Tolerance profile and limits; the profile is copied into the surface.
outSurface
Replaced by the new owner only on Success.
outDiagnosticOrNull
Optional; receives the first failure's details. SourceElement is the patch index, or the adjacency index for "Adjacency" properties.

Returns

Success; NonFiniteInput; InvalidArgument for an unknown side, a bad asset scale or no patches; InvalidTopology for a duplicate patch ID, an out-of-range patch index, a side joined to itself, a third incidence (nonmanifold) or mismatched curves (including partial joins); UnsupportedPrecision; OutOfRange when a relative control exceeds float32; BudgetExceeded; OutOfMemory. outSurface is replaced only on Success.

Related types: PreparedSurface · GeometryStatus · GeometryDiagnostic · SurfacePreparation · SurfaceSource

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

TryEvaluateSurface

GeometryStatus ludus::foundation::geometry::TryEvaluateSurface(const SurfaceView &surface, SurfaceParameter parameter, math::Vector3 &outPosition) noexcept
Evaluate a chunk-relative position at a surface parameter (Rounded; corners Exact).

Returns

InvalidDomain for an out-of-range patch index or a parameter outside [0,1]; NonFiniteInput for a nonfinite parameter; OutOfRange. outPosition is unchanged on failure.

Related types: GeometryStatus · SurfaceParameter · SurfaceView · math::Vector3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

TryEvaluateSurface

GeometryStatus ludus::foundation::geometry::TryEvaluateSurface(const SurfaceView &surface, SurfaceParameter parameter, math::PatchSample &outSample) noexcept
Evaluate position and first/second partials per normalized U and V, with the position overload's contract.

Related types: GeometryStatus · SurfaceParameter · SurfaceView · math::PatchSample

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

TryEvaluateSurfaceNormal

GeometryStatus ludus::foundation::geometry::TryEvaluateSurfaceNormal(const SurfaceView &surface, SurfaceParameter parameter, math::Vector3 &outNormal) noexcept
Geometric unit normal normalize(Cross(DU, DV)) at a surface parameter (Rounded).
Uses the surface's NormalMinDerivativeLength and NormalMinSinAngle as the math::PatchNormalPolicy. The position remains valid where the normal is not.

Returns

Degenerate for exactly zero or parallel partials; IllConditioned at or below the thresholds; plus the TryEvaluateSurface statuses. outNormal is unchanged on failure.

Related types: GeometryStatus · SurfaceParameter · SurfaceView · math::Vector3

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

TryMapEdgeParameter

GeometryStatus ludus::foundation::geometry::TryMapEdgeParameter(const SurfaceView &surface, usize edgeIndex, usize incidence, float64 edgeParameter, SurfaceParameter &outParameter) noexcept
Map a canonical edge parameter t to an incident patch's surface parameter.
Incidence 0 uses s = t; incidence 1 uses s = 1 - t when the edge is reversed. Exact for dyadic t, because 1 - t is then exact.
ParameterDescription
surface
Borrowed prepared surface.
edgeIndex
Prepared edge index.
incidence
0 for the owner, 1 for the other side of a shared edge.
edgeParameter
Canonical t in [0,1].
outParameter
Written only on Success.

Returns

InvalidDomain for a bad edge index, incidence or t outside [0,1]; NonFiniteInput for a nonfinite t.

Related types: float64 · usize · GeometryStatus · SurfaceParameter · SurfaceView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/surface.hpp

TryPlanSweepMesh

GeometryStatus ludus::foundation::geometry::TryPlanSweepMesh(const PathView &path, const DistanceMapView &map, const FramesView &frames, const SweepRequest &request, SweepMeshPlan &outPlan, GeometryDiagnostic *outDiagnosticOrNull)
Plan a ribbon or tube sweep along a framed path.
Requires frames with one run over the whole path and G1 joints; a closed path requires periodic frames (ClosedFramePolicy::DistributeTwist), and its last ring copies the first ring with V = the path's estimated total length, so the UV seam is explicit and positions match bitwise. Each span is stepped over dyadic intervals, starting a ring at every span start; an interval is accepted when the distance of its control hull from the chord plus the midpoint deviation of every section point is at most LongitudinalError. A tube uses the fewest segments whose polygon error at the largest profile scale is at most CrossSectionError.
ParameterDescription
path
Borrowed prepared path; its revision is pinned in the plan.
map
Distance map of the same revision, for ring distances and profile lookup.
frames
Frames of the same revision.
request
Section, profile, budgets and limits.
outPlan
Replaced by the new plan only on Success.
outDiagnosticOrNull
Optional; receives the failure's details.

Returns

Success; InvalidArgument for an empty path, malformed request, unordered or nonpositive profile, or caps on a ribbon or closed path; NonFiniteInput; MissingCache or StaleRevision for the map or frames; DegenerateFrame when the frames have gaps, corners or an aperiodic closed seam; BudgetExceeded for ring, depth, test, byte, segment, vertex or index limits; OutOfRange when an output would exceed float32 or uint32 indices; OutOfMemory. outPlan is replaced only on Success.

Related types: SweepMeshPlan · GeometryStatus · DistanceMapView · FramesView · GeometryDiagnostic · PathView · SweepRequest

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/sweep.hpp

TryEmitSweepMesh

GeometryStatus ludus::foundation::geometry::TryEmitSweepMesh(const PathView &path, const SweepMeshPlanView &plan, BorrowedView< SweepVertex > outVertices, BorrowedView< uint32 > outIndices) noexcept
Write a planned sweep into caller-owned ranges.
Vertices are ring-major. A ribbon ring has the -Binormal then +Binormal edge; a tube ring has SectionSegmentCount + 1 vertices, the last repeating the first position with U = 1. Flat caps follow the rings: each has a center then one vertex per segment. Indices form a triangle list.
ParameterDescription
path
Path whose revision the plan pinned.
plan
Borrowed plan.
outVertices
At least Report.VertexCount entries; must not overlap outIndices.
outIndices
At least Report.IndexCount entries.

Returns

Success; MissingCache for an empty plan; StaleRevision when path is not the pinned revision; CapacityExceeded when either range is too small. Nothing is written on failure, and emission never fails after it starts writing.

Related types: BorrowedView · uint32 · GeometryStatus · PathView · SweepMeshPlanView · SweepVertex

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/sweep.hpp

TryBuildSurfaceMesh

GeometryStatus ludus::foundation::geometry::TryBuildSurfaceMesh(const SurfaceView &surface, const SurfaceMeshProfile &profile, SurfaceMesh &outMesh, GeometryDiagnostic *outDiagnosticOrNull)
Select dyadic grid levels, verify their Certified error bounds and build a crack-free mesh.
Every patch starts at level (0, 0). While its largest cell bound misses the profile, the direction whose refinement gives the clearly smaller normalized bound is refined. When the two candidates agree within a relative 1e-9 (for example mirror-symmetric patches whose enclosures differ only by rounding), the coarser direction is refined, and u when both levels are equal, so isotropic patches stay balanced. Each shared edge then takes the larger of its two along-edge levels; patches whose levels changed are rechecked and refined again until all shared edges agree. Corner positions are the stored controls; edge samples are evaluated once on the canonical curve; interior samples on their patch. Each emitted position is the float32 rounding of an outward enclosure, and its rounding error is part of every cell bound.
ParameterDescription
surface
Borrowed prepared surface; its Revision is recorded in the mesh.
profile
Accuracy, precision, degeneracy policy and budgets.
outMesh
Replaced by the new mesh only on Success.
outDiagnosticOrNull
Optional; on BudgetExceeded it receives the achieved Certified bound and the patch.

Returns

Success; InvalidArgument for an empty surface, an invalid profile or a coarser-mesh request on a Strict profile; NonFiniteInput; UnsupportedPrecision when PositionError is below the surface floor or a Strict profile requests a normal bound; BudgetExceeded when MaxLevel (without an accepted coarser mesh), MaxCellTests, MaxVertices, MaxTriangles or MaxOutputBytes is exhausted; Degenerate or IllConditioned under SurfaceDegeneracyPolicy::Reject; OutOfRange when an enclosure overflows or the vertex count exceeds the uint32 index range; OutOfMemory. outMesh is replaced only on Success.

Related types: SurfaceMesh · GeometryStatus · GeometryDiagnostic · SurfaceMeshProfile · SurfaceView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/tessellation.hpp

TryPrepareTrack

GeometryStatus ludus::foundation::geometry::TryPrepareTrack(BorrowedView< const TrackKey > keys, const WorkLimits &limits, PreparedTrack &outTrack, GeometryDiagnostic *outDiagnosticOrNull)
Validate keys and build a prepared track.
Requires at least two keys within Limits.MaxSpans, finite times, values and slopes, strictly increasing times and known interpolation values. Equal times are rejected: the runtime never resolves an undocumented tie.
ParameterDescription
keys
Source keys, borrowed for the call only.
limits
MaxSpans (key count) and MaxPreparedBytes apply.
outTrack
Replaced by the new owner only on Success.
outDiagnosticOrNull
Optional; receives the offending key index and property.

Returns

Success; InvalidArgument; NonFiniteInput; InvalidDomain for nonincreasing times; OutOfRange when a Hermite control overflows float32; BudgetExceeded; OutOfMemory. outTrack is replaced only on Success.

Related types: BorrowedView · PreparedTrack · GeometryStatus · GeometryDiagnostic · TrackKey · WorkLimits

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/track.hpp

TryEvaluateTrack

GeometryStatus ludus::foundation::geometry::TryEvaluateTrack(const TrackView &track, TrackTime time, BoundaryPolicy policy, SpanSide side, TrackSample &outSample) noexcept
Evaluate a track at a time under a boundary policy and span side.
Inside [start, end] every policy evaluates the same value. An exact interior key selects the outgoing span unless side is Incoming; the last key selects the last span at u = 1. Clamp evaluates the nearest endpoint with its one-sided derivative from inside; Hold returns the endpoint value with zero derivative; Loop maps into [start, end); PingPong reflects with period 2D and negates the derivative on the reflected half.

Returns

MissingCache for an empty view; NonFiniteInput; InvalidDomain outside the domain under Reject; InvalidArgument for Wrap or an unknown policy or side; OutOfRange. outSample is unchanged on failure.

Related types: BoundaryPolicy · SpanSide · GeometryStatus · TrackSample · TrackTime · TrackView

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/track.hpp

Aliases

int32

using ludus::foundation::core::int32 = std::int32_t
Exact 32-bit signed integer for explicit-width values.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/frame.hpp

float32

using ludus::foundation::core::float32 = float
IEEE binary32 scalar; does not select rounding, trap or denormal policy.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

float64

using ludus::foundation::core::float64 = double
IEEE binary64 scalar; does not select rounding, trap or denormal policy.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

uint64

using ludus::foundation::core::uint64 = std::uint64_t
Exact 64-bit unsigned integer for explicit-width values.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

uint8

using ludus::foundation::core::uint8 = std::uint8_t
Exact 8-bit unsigned integer for explicit-width values.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

usize

using ludus::foundation::core::usize = std::size_t
Native unsigned size/index type; matches sizeof and container sizes, not a wire format.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/status.hpp

uint32

using ludus::foundation::core::uint32 = std::uint32_t
Exact 32-bit unsigned integer for explicit-width values.

Declared in modules/foundation/geometry/include/ludus/foundation/geometry/sweep.hpp