SequenceRuntime.hpp

Go to the documentation of this file.

#pragma once
 
#include "ResourceRuntime.hpp"
#include "SequenceChildSchedule.hpp"
#include "SequenceClock.hpp"
#include "SequenceTransforms.hpp"
 
#include <array>
#include <memory>
#include <string>
 
namespace monopoly::sequence
{
    enum class RuntimeErrorCode
    {
        DataFailure, DecodeFailure, UnsupportedType, UnsupportedAttribute,
        InvalidLimits, DepthLimit, DescriptionLimit, ReferenceLimit, IndirectCycle,
        LiveNodeLimit, BirthLimit, InvalidHandle, ClockFailure, TweekerFailure,
        IdentifierExhausted
    };
    struct RuntimeError
    {
        RuntimeErrorCode code{};
        data::DataId dataId{};
        std::size_t offset{};
        std::string detail;
        std::variant<std::monostate, data::DataError, data::ChunkError,
            data::SequenceError, ClockError> cause;
    };
    struct DescriptionLimits
    {
        std::size_t maximumDepth{64}; // root counts as one; hard safety ceiling 128
        std::size_t maximumDescriptions{4096};
        std::size_t maximumReferences{65'536};
    };
 
    struct SequenceDescription
    {
        data::DataId dataId{};
        data::LegacySequenceRecord record;
        SequenceChildSchedule children;
        data::LegacySequenceAttributes attributes;
        // Resolved exactly as LI_SEQNCR_StartUpSequence does for 3D mesh
        // records. Empty for records which do not expose renderable content.
        std::optional<data::DataId> contentsDataId;
        // One program index for each record in the schedule, in DISK order.
        std::vector<std::size_t> childDescriptions;
        // Runtime-only TakeOverAndPlayBinkVideo option; never decoded from DAT.
        bool binkDoubleSize{};
        // LE_SEQNCR_Start clears the internal TAB offset only for raw bitmaps.
        bool zeroBitmapOffset{};
    };
 
    // Immutable, bounded description DAG. Shared sublists are not expanded
    // exponentially; cycles are rejected by (DATA ID, chunk offset). Every
    // CNK lease needed by the supported tree is acquired before publication.
    // Currently executable: grouping/indirect, 2D bitmap, sound, video,
    // preloader, legacy 3D model/mesh, 3D camera and transform/FOV/audio tweekers.
    // Attributes are immutable input.
    // Other decoded kinds and attributes fail explicitly; no fake renderer.
    class SequenceProgram final
    {
    public:
        [[nodiscard]] static std::expected<std::shared_ptr<const SequenceProgram>, RuntimeError>
        load(const data::DataSource& source, data::DataId id,
            std::size_t offset = 0, DescriptionLimits limits = {});
        // Runtime loading also applies Monopoly's default PrepareSequenceData:
        // raw assets, or the direct bitmap/sound children of a grouping. As in
        // Main.cpp, UseReferenceCounts is false: the warmed cache stays evictable.
        [[nodiscard]] static std::expected<std::shared_ptr<const SequenceProgram>, RuntimeError>
        load(std::shared_ptr<const data::ResourceSnapshot> resources, data::DataId id,
            std::size_t offset = 0, DescriptionLimits limits = {});
        [[nodiscard]] static std::expected<std::shared_ptr<const SequenceProgram>, RuntimeError>
        rawBitmap(data::DataId id, data::LegacyDataType sourceType,
            DescriptionLimits limits = {});
        // External media is owned by the video backend. Its real EOF, not a
        // guessed sequence duration, ends this runtime-created video record.
        [[nodiscard]] static std::expected<std::shared_ptr<const SequenceProgram>, RuntimeError>
        runtimeVideo(data::DataId id, std::string fileName,
            data::SequenceVideoData options,
            data::Sequence2DBoundingBoxAttribute bounds,
            bool binkDoubleSize = false);
        [[nodiscard]] std::span<const SequenceDescription> descriptions() const noexcept;
        [[nodiscard]] std::shared_ptr<const data::ResourceSnapshot> resources() const noexcept;
    private:
        SequenceProgram() = default;
        std::vector<SequenceDescription> descriptions_;
        std::shared_ptr<const data::ResourceSnapshot> resources_;
    };
 
    using SequenceNodeId = std::uint64_t; // zero means no node; never reused
    enum class SequenceEventKind { Created, Updated, ReachedEnd, Rewound, Destroyed };
    struct SequenceEvent
    {
        SequenceEventKind kind{};
        SequenceNodeId node{};
        SequenceNodeId parent{};
        data::DataId dataId{};
        std::size_t offset{};
        std::uint16_t priority{};
        std::uint8_t label{};
        std::uint8_t sequenceType{};
        std::uint8_t endingAction{};
        std::int32_t clock{};
    };
    struct SequenceMeshChoice3D
    {
        std::int16_t meshIndexA{};
        std::int16_t meshIndexB{};
        float meshProportion{};
        auto operator<=>(const SequenceMeshChoice3D&) const = default;
    };
    struct SequenceSpatial2DView
    {
        Matrix2D worldTransform{};
        data::Sequence2DBoundingBoxAttribute bounds{};
        std::uint64_t movementRevision{};
    };
    struct SequenceCamera2DView
    {
        SequenceNodeId node{};
        Matrix2D worldTransform{};
        data::Sequence2DBoundingBoxAttribute bounds{};
        // Only a Camera chunk replaces the slot's previous scale.
        std::optional<float> scale;
    };
    struct SequenceCamera3DView
    {
        SequenceNodeId node{};
        std::uint8_t label{};
        std::uint16_t priority{};
        std::int32_t clock{};
        Matrix3D worldTransform{};
        float fieldOfView{0.7853981633974483F};
        float nearPlane{1.0F};
        float farPlane{5000.0F};
    };
    struct SequenceNodeView
    {
        SequenceNodeId node{};
        SequenceNodeId parent{};
        data::DataId dataId{};
        std::size_t offset{};
        std::uint16_t priority{};
        std::uint8_t label{};
        std::int32_t clock{};
        std::int32_t endTime{};
        std::uint8_t timeMultiple{};
        bool paused{};
        bool needsRedraw{};
        std::uint8_t dimensionality{};
        std::optional<data::DataId> contentsDataId;
        bool explicitlyPositioned{};
        SequenceTransform localTransform;
        bool tweekerTransformApplied{};
        SequenceTransform tweekerTransform;
        SequenceTransform worldTransform;
        std::vector<SequenceNodeId> children; // runtime priority order
        SequenceMeshChoice3D meshChoice{};
        std::uint16_t pitch{};
        std::uint8_t volume{100};
        std::int8_t panning{};
    };
 
    struct SequenceInfoView
    {
        SequenceNodeId node{};
        std::int32_t sequenceClock{};
        std::int32_t endTime{};
        std::uint8_t dimensionality{};
        std::optional<Matrix3D> sequenceToWorldTransformation;
    };
 
    struct SequenceBitmapInstanceView
    {
        SequenceNodeId node{};
        data::DataId contentsDataId{};
        std::uint16_t priority{};
        std::int32_t clock{};
        Matrix2D worldTransform{};
        std::optional<data::Sequence2DBoundingBoxAttribute> bounds;
        bool zeroBitmapOffset{};
        // Presentation provenance; leaf placement and ordering stay authored.
        data::DataId rootSequenceDataId{};
        SequenceNodeId rootSequenceNode{};
        std::uint16_t rootSequencePriority{};
    };
    struct SequenceSoundInstanceView
    {
        SequenceNodeId node{};
        data::DataId contentsDataId{};
        std::uint16_t priority{};
        std::int32_t clock{};
        std::uint8_t endingAction{};
        std::uint8_t dimensionality{};
        std::uint16_t pitch{};
        std::uint8_t volume{100};
        std::int8_t panning{};
        std::optional<std::int32_t> screenCenterX2D;
        std::string fileName;
        bool paused{};
        std::uint64_t seekGeneration{};
        std::optional<SequenceSpatial2DView> spatial2D;
        // Direct buffer commands bypass positional attenuation/panning until
        // the next SequenceMoved. Already included in volume/panning above.
        std::optional<std::uint8_t> volumeOverride;
        std::optional<std::int8_t> panningOverride;
    };
    struct SequenceVideoInstanceView
    {
        SequenceNodeId node{};
        std::uint16_t priority{};
        std::int32_t clock{};
        data::SequenceVideoData video{};
        std::string fileName;
        std::optional<data::Sequence2DBoundingBoxAttribute> boundingBox;
        Matrix2D worldTransform{};
        std::uint8_t endingAction{};
        bool binkDoubleSize{};
        std::int32_t elapsedParentClock{};
        std::uint16_t pitch{};
        std::uint8_t volume{100};
        std::int8_t panning{};
    };
    struct SequenceBounds3D
    {
        std::array<float, 3> minimum{};
        std::array<float, 3> maximum{};
        auto operator<=>(const SequenceBounds3D&) const = default;
    };
 
    struct SequenceScrollingWorldView
    {
        SequenceNodeId node{};
        std::uint8_t dimensionality{};
        SequenceTransform worldTransform;
        std::optional<data::Sequence2DBoundingBoxAttribute> bounds2D;
        std::optional<SequenceBounds3D> bounds3D;
        bool onScreen{true};
    };
 
    struct SequenceMeshInstanceView
    {
        SequenceNodeId node{};
        data::DataId contentsDataId{};
        // Top-level CNK that owns this live mesh. Modern presentation can use
        // this to distinguish a resting token sequence from movement sequences
        // even when both reference the same HMD.
        data::DataId rootSequenceDataId{};
        std::uint16_t priority{};
        std::int32_t clock{};
        Matrix3D worldTransform{};
        SequenceMeshChoice3D meshChoice{};
        std::optional<SequenceBounds3D> bounds;
        std::optional<data::DataId> textureMapDataId;
        std::optional<data::DataId> jointPositionsDataId;
        // Qualification provenance; priority above stays the authored leaf
        // ordering priority. Source L_Seqncr.cpp:3797-3799,5318-5319 gives
        // user priority only to the root, not its disk-born children.
        std::uint16_t rootSequencePriority{};
    };
    struct RuntimeLimits
    {
        std::size_t maximumLiveNodes{65'536};
        std::size_t maximumBirthsPerOperation{65'536};
    };
 
    // CPU forest below the historical implicit root. No SDL, UI callbacks,
    // scene or GPU objects. All mutations are on the owner thread. Children
    // are uniquely owned; handles/views never expose mutable node pointers.
    // Start is staged. An update/seek failure destroys the forest explicitly
    // instead of leaving a partially evaluated tree looking successful.
    class SequenceRuntime final
    {
    public:
        explicit SequenceRuntime(RuntimeLimits limits = {});
        ~SequenceRuntime();
        SequenceRuntime(const SequenceRuntime&) = delete;
        SequenceRuntime& operator=(const SequenceRuntime&) = delete;
 
        [[nodiscard]] std::expected<SequenceNodeId, RuntimeError> start(
            std::shared_ptr<const SequenceProgram> program,
            std::uint16_t priority = 0, ClockStartOptions options = {},
            std::optional<SequenceTransform> initialTransform = std::nullopt,
            std::uint8_t labelOverride = 0);
        [[nodiscard]] std::expected<void, RuntimeError> requestSoundFailure(SequenceNodeId id);
        [[nodiscard]] std::expected<void, RuntimeError> requestSoundClock(
            SequenceNodeId id, std::int32_t mediaClock);
        [[nodiscard]] std::expected<void, RuntimeError> requestVideoClock(
            SequenceNodeId node, std::int32_t mediaClock, std::int32_t duration, bool ended);
        [[nodiscard]] std::expected<void, RuntimeError> update(std::int32_t parentClock);
        [[nodiscard]] std::expected<void, RuntimeError> stop(SequenceNodeId node);
        void stopAll();
        [[nodiscard]] std::expected<void, RuntimeError> setPaused(SequenceNodeId node, bool paused);
        [[nodiscard]] std::expected<void, RuntimeError> seek(SequenceNodeId node, std::int32_t time);
        [[nodiscard]] std::expected<void, RuntimeError> setEndingAction(SequenceNodeId node, std::uint8_t action);
        [[nodiscard]] std::expected<void, RuntimeError> setVolume(
            SequenceNodeId node, std::uint8_t volume);
        [[nodiscard]] std::expected<void, RuntimeError> setPitch(
            SequenceNodeId node, std::uint16_t pitch);
        [[nodiscard]] std::expected<void, RuntimeError> setPanning(
            SequenceNodeId node, std::int8_t panning);
        [[nodiscard]] std::expected<void, RuntimeError>
            setScrollingWorldVisibility(SequenceNodeId node, bool onScreen);
 
        // Historical command targeting excludes nested records (offset != 0),
        // including during whole-tree searches. Duplicate matches are legal.
        [[nodiscard]] std::vector<SequenceNodeId> matching(data::DataId id,
            std::uint16_t priority, bool wholeTree = false) const;
        [[nodiscard]] std::size_t stopMatching(data::DataId id,
            std::uint16_t priority, bool wholeTree = false);
        [[nodiscard]] std::expected<std::size_t, RuntimeError> setEndingActionMatching(
            data::DataId id, std::uint16_t priority, std::uint8_t action,
            bool wholeTree = false);
        [[nodiscard]] std::size_t setVolumeMatching(
            data::DataId id, std::uint16_t priority, std::uint8_t volume,
            bool wholeTree = false);
        [[nodiscard]] std::size_t setPitchMatching(
            data::DataId id, std::uint16_t priority, std::uint16_t pitch,
            bool wholeTree = false);
        [[nodiscard]] std::size_t setPanningMatching(
            data::DataId id, std::uint16_t priority, std::int8_t panning,
            bool wholeTree = false);
        [[nodiscard]] std::size_t moveMatching(data::DataId id,
            std::uint16_t priority, const SequenceTransform& transform,
            bool wholeTree = false);
        [[nodiscard]] std::size_t forceRedrawMatching(data::DataId id,
            std::uint16_t priority, bool wholeTree = false);
 
        [[nodiscard]] std::optional<SequenceNodeView> inspect(SequenceNodeId node) const;
        // Source-compatible LE_SEQNCR_GetInfo subset used by Monopoly: first
        // DataID/priority match at offset zero, optionally including descendants.
        [[nodiscard]] std::optional<SequenceInfoView> info(data::DataId id,
            std::uint16_t priority, bool wholeTree = false) const;
        // LE_SEQNCR_IsSequenceFinished: true when the first matching sequence
        // has reached its end time or when no matching sequence is active.
        [[nodiscard]] bool isSequenceFinished(
            data::DataId id, std::uint16_t priority,
            bool wholeTree = false) const;
        // LE_SEQNCR_GetChildMeshWorldMatrix: select the first matching top-level
        // root, then search only that root/subtree for the first active 3D mesh.
        [[nodiscard]] std::optional<Matrix3D> childMeshWorldMatrix(
            data::DataId id, std::uint16_t priority) const;
        // Active 3D mesh leaves in runtime traversal order. This is CPU render
        // intent only: no HMD decoding, GPU resource or render-slot ownership.
        // Active 2D bitmap leaves in runtime traversal order.
        [[nodiscard]] std::vector<SequenceBitmapInstanceView> bitmapInstances() const;
        [[nodiscard]] std::vector<SequenceSoundInstanceView> soundInstances() const;
        [[nodiscard]] std::vector<SequenceVideoInstanceView> videoInstances() const;
        [[nodiscard]] std::vector<SequenceMeshInstanceView> meshInstances() const;
        [[nodiscard]] std::vector<SequenceScrollingWorldView>
            scrollingWorldInstances() const;
        // Active 3D camera sequences with raw ArtLib FOV semantics. Projection
        // interpretation remains the renderer's responsibility.
        [[nodiscard]] std::vector<SequenceCamera3DView> cameraInstances() const;
        // Any current label owner in 2D can drive the render-slot camera.
        // Bitmap bounds are replaced by resolved image metadata at publication.
        [[nodiscard]] std::optional<SequenceCamera2DView> camera2DForLabel(
            std::uint8_t label) const;
        // Any current 3D label owner supplies the pose; non-camera nodes use
        // the retail half-FOV and clip defaults. The newest owner wins, and
        // removing it does not restore an older overlapping owner.
        [[nodiscard]] std::optional<SequenceCamera3DView> cameraForLabel(
            std::uint8_t label) const;
        [[nodiscard]] std::vector<SequenceNodeId> roots() const;
        [[nodiscard]] std::size_t liveNodeCount() const noexcept;
        // Diagnostic lifecycle trace for the last operation, not ArtLib label
        // notifications/callbacks. Cleared on each mutation: no growing queue.
        [[nodiscard]] std::span<const SequenceEvent> events() const noexcept;
 
    private:
        struct Node;
        using Nodes = std::vector<std::unique_ptr<Node>>;
        [[nodiscard]] Node* find(SequenceNodeId id) const;
        [[nodiscard]] std::expected<std::unique_ptr<Node>, RuntimeError> create(
            std::shared_ptr<const SequenceProgram> program, std::size_t description,
            Node* parent, std::uint16_t priority, ClockStartOptions options,
            std::uint8_t labelOverride = 0);
        void insert(Nodes& siblings, std::unique_ptr<Node> node);
        void emit(SequenceEventKind kind, const Node& node);
        void destroyChildren(Node& node);
        void destroy(std::unique_ptr<Node>& node);
        void erase(Node& node);
        void clearForest();
        void forceAncestors(Node& node);
        void forceDescendants(Node& node);
        void clearRedrawFlags();
        void move(Node& node, const SequenceTransform& transform);
        void updatePosition(Node& node);
        [[nodiscard]] std::expected<void, RuntimeError> birthChildren(Node& node,
            std::optional<std::int32_t> previous);
        [[nodiscard]] std::expected<void, RuntimeError> rebuildChildren(Node& node);
        [[nodiscard]] std::expected<bool, RuntimeError> seekNode(Node& node, std::int32_t time);
        [[nodiscard]] std::expected<void, RuntimeError> applyTweeker(Node& node);
        [[nodiscard]] std::expected<bool, RuntimeError> updateNode(Node& node, std::int32_t parentClock);
        RuntimeLimits limits_;
        Nodes roots_;
        std::vector<SequenceEvent> events_;
        SequenceNodeId nextId_{1};
        std::size_t liveNodes_{};
        std::size_t births_{};
        std::int32_t parentClock_{};
        bool clockStarted_{};
        // Mirrors the single legacy LE_SEQNCR_LabelArray shared by
        // cameras and explicitly labelled sequences. The newest owner wins;
        // deleting it does not restore an older overlapping owner.
        std::array<SequenceNodeId, 256> labelOwners_{};
    };
}