ludus::gameplay::sequencer

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

Related declarations

• ludus::gameplay::sequencer::PreparedSequence
• ludus::gameplay::sequencer::SequenceCameraTrack
• ludus::gameplay::sequencer::SequenceFrameRate
• ludus::gameplay::sequencer::SequenceFrameSchedule
• ludus::gameplay::sequencer::SequenceLensKey
• ludus::gameplay::sequencer::SequenceLimits
• ludus::gameplay::sequencer::SequenceObjectSample
• ludus::gameplay::sequencer::SequenceObjectTrack
• ludus::gameplay::sequencer::SequencePositionKey
• ludus::gameplay::sequencer::SequenceRotationKey
• ludus::gameplay::sequencer::SequenceSource
• ludus::gameplay::sequencer::SequenceTime
• ludus::gameplay::sequencer::SequenceVectorKey
• ludus::gameplay::sequencer::SequenceVisibilityKey

Enumerations

SequenceInterpolation

enum class SequenceInterpolation : foundation::uint8

Interpolation of the outgoing span. Exact keys select their own value; endpoints hold.

Related types: foundation::uint8

Step

Step

Hold the left key throughout [left time, right time).

Linear

Linear

Linear scalar/vector interpolation; shortest-path spherical rotation interpolation.

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

SequenceStatus

enum class SequenceStatus : foundation::uint8

Result of sequence preparation or sampling. Failure preserves the requested output.

Related types: foundation::uint8

Success

Success

A complete validated result was published.

InvalidArgument

InvalidArgument

An invalid view, time, rate, base value or enum was supplied.

InvalidKeys

InvalidKeys

Keys are unordered, nonfinite, nonunit or outside the channel's domain.

DuplicateBinding

DuplicateBinding

More than one track group names the same binding; combine its channels.

BudgetExceeded

BudgetExceeded

The requested track/key/storage payload exceeds the supplied limits.

OutOfMemory

OutOfMemory

A fallible preparation allocation failed.

OutOfRange

OutOfRange

Checked time arithmetic or a sampled value is not representable.

Unprepared

Unprepared

The sequence has no accepted prepared revision.

MissingBinding

MissingBinding

No track of the requested kind has that binding identity.

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/time.hpp

Constants and variables

DEFAULT_SEQUENCE_MAX_TRACKS

constexpr foundation::usize ludus::gameplay::sequencer::DEFAULT_SEQUENCE_MAX_TRACKS = 256

Default admission count for object/camera track groups, independent of World limits.

Related types: foundation::usize

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

DEFAULT_SEQUENCE_MAX_KEYS

constexpr foundation::usize ludus::gameplay::sequencer::DEFAULT_SEQUENCE_MAX_KEYS = 65536

Default total key admission count across every channel of one prepared sequence.

Related types: foundation::usize

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

DEFAULT_SEQUENCE_MAX_PREPARED_BYTES

constexpr foundation::usize ludus::gameplay::sequencer::DEFAULT_SEQUENCE_MAX_PREPARED_BYTES = foundation::usize{8} * 1024 * 1024

Default storage payload allowance for one immutable prepared revision, in bytes.

Related types: foundation::usize

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

MAX_SEQUENCE_SPAN_TICKS

constexpr foundation::uint64 ludus::gameplay::sequencer::MAX_SEQUENCE_SPAN_TICKS = foundation::uint64{1} << 53

Largest span duration admitted for exact integer-to-binary64 local timing conversion.

Related types: foundation::uint64

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

SEQUENCE_ROTATION_UNIT_TOLERANCE

constexpr foundation::float32 ludus::gameplay::sequencer::SEQUENCE_ROTATION_UNIT_TOLERANCE = 1e-4F

Maximum absolute squared-norm error admitted before a quaternion is normalized at preparation.

Related types: foundation::float32

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

Functions

TryPrepareSequence

SequenceStatus ludus::gameplay::sequencer::TryPrepareSequence(const SequenceSource &source, const SequenceLimits &limits, PreparedSequence &outSequence)

Validate and copy source channels into a candidate immutable revision. Keys must be strictly ordered with span widths <= MAX_SEQUENCE_SPAN_TICKS. Duplicate groups are rejected instead of silently assigning writer priority. Rotations within the unit tolerance are normalized in the owned copy; source data is unchanged.

Parameter	Description
source	Borrowed groups/keys; storage need not survive a successful return.
limits	Track/key/payload admission policy; preparation has no thread affinity.
outSequence	Replaced only on Success, preserving any accepted revision on every failure.

Returns

Success, InvalidArgument, InvalidKeys, DuplicateBinding, BudgetExceeded or OutOfMemory.

Related types: PreparedSequence · SequenceStatus · SequenceLimits · SequenceSource

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

TryEvaluateSequenceObject

SequenceStatus ludus::gameplay::sequencer::TryEvaluateSequenceObject(const PreparedSequence &sequence, foundation::uint64 bindingId, SequenceTime time, SequenceObjectSample &outSample)

Sample one object's complete local value at an absolute time, independently of earlier calls. Empty channels retain the base; nonempty channels hold their first/last endpoints. Exact interior keys select the outgoing span; a single key is a constant channel.

Parameter	Description
sequence	Prepared immutable owner retained for the call.
bindingId	Nonzero object binding identity; camera bindings are a different requested kind.
time	Nonnegative proper-fraction authored ticks; no caller tick-grid rounding is needed.
outSample	Replaced only on Success, including when time/binding validation fails.

Returns

Success, Unprepared, MissingBinding or InvalidArgument. No allocation or thread affinity.

Related types: PreparedSequence · foundation::uint64 · SequenceStatus · SequenceObjectSample · SequenceTime

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

TryEvaluateSequenceCamera

SequenceStatus ludus::gameplay::sequencer::TryEvaluateSequenceCamera(const PreparedSequence &sequence, foundation::uint64 bindingId, SequenceTime time, camera::CameraSample &outSample)

Sample one rigid camera's pose/lens at an absolute time; retain BaseSample's metadata. Uses the same boundary/ownership rules as TryEvaluateSequenceObject. Position remains float64. The caller owns shot selection, history/cut revisions, presentation counters and scene publication.

Parameter	Description
sequence	Prepared immutable owner retained for the call.
bindingId	Nonzero camera binding identity.
time	Nonnegative proper-fraction authored ticks.
outSample	Replaced only on Success; a numerically invalid interpolated lens preserves it.

Returns

Success, Unprepared, MissingBinding, InvalidArgument or OutOfRange. Allocation-free.

Related types: PreparedSequence · foundation::uint64 · SequenceStatus · camera::CameraSample · SequenceTime

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/sequence.hpp

TryGetSequenceFrameTime

SequenceStatus ludus::gameplay::sequencer::TryGetSequenceFrameTime(const SequenceFrameSchedule &schedule, foundation::uint64 frameOrdinal, SequenceTime &outTime) noexcept

Compute startTick + frameOrdinal * ticksPerSecond / rate exactly.

Parameter	Description
schedule	Positive rate/frequency and nonnegative epoch; rate need not already be reduced.
frameOrdinal	Absolute nonnegative output frame ordinal, including subset renders.
outTime	Replaced by a reduced proper fraction on Success; unchanged otherwise.

Returns

InvalidArgument for a zero rate/frequency; OutOfRange when the resulting whole tick exceeds uint64. Avoidable intermediate multiplication overflow is handled.

Note

Allocation-free, no thread affinity. Negative/pre-roll times are not supported yet.

Related types: foundation::uint64 · SequenceStatus · SequenceFrameSchedule · SequenceTime

Declared in modules/gameplay/sequencer/include/ludus/gameplay/sequencer/time.hpp