Docs/Classes/Mc3Animation

Animation Types (Mc3Animation.hpp)

Keyframe animation data model: Mc3Action, Mc3Channel, Mc3Keyframe, and the channel evaluator.

Header

mc3/include/MeshCraft/Mc3/Mc3Animation.hpp

Namespace

MeshCraft::Mc3

Types Overview

enum class Interpolation { Step, Linear, CubicBezier };

enum class AnimatedProperty {
    PositionX, PositionY, PositionZ,
    RotationX, RotationY, RotationZ,
    ScaleX, ScaleY, ScaleZ,
    Visible,
    DeformX, DeformY, DeformZ,
    MaterialBaseColorR, MaterialBaseColorG, MaterialBaseColorB, MaterialBaseColorA,
    MaterialRoughness, MaterialMetallic,
    MaterialEmissiveR, MaterialEmissiveG, MaterialEmissiveB,
};

struct Mc3BezierHandle { float dt, dv; };

struct Mc3Keyframe {
    float          time;
    float          value;
    Interpolation  interpolation;   // applies to the segment AFTER this keyframe
    Mc3BezierHandle handleLeft;     // in-tangent (dt negative)
    Mc3BezierHandle handleRight;    // out-tangent (dt positive)
};

struct Mc3Channel {
    string         targetObject;   // name of the Mc3Object to animate
    AnimatedProperty property;
    vector<Mc3Keyframe> keyframes; // must be sorted ascending by time
};

struct Mc3Action {
    string name;
    float  duration;   // clip length in seconds
    bool   loop;
    vector<Mc3Channel> channels;
};

Free Functions

SignatureDescription
const char* animatedPropertyName(AnimatedProperty) Returns the string name used in XML (e.g., "position.x"). Used by the XML writer.
optional<AnimatedProperty> animatedPropertyFromName(const string&) Parses a string name back to the enum. Returns nullopt on unknown names. Used by the XML parser.
float evaluateChannel(const Mc3Channel&, float time) Evaluates the channel at the given time. Returns 0.0f for empty channels. Clamps to the first/last keyframe outside the range. Applies Step, Linear, or Cubic Bézier interpolation as specified by the preceding keyframe's interpolation field.

Interpolation Modes

ModeBehaviour
StepValue jumps instantly at the next keyframe. Suitable for binary properties like visible.
LinearLinear interpolation between consecutive keyframe values.
CubicBezierSmooth cubic curve. The tangent handles (handleLeft/handleRight) are offsets from the keyframe's (time, value). When exported to glTF, cubic channels are sampled at 30 fps and written as LINEAR.

Animatable Properties — glTF Export

PropertyglTF export
position.x/y/z→ translation VEC3
rotation.x/y/z→ rotation quaternion VEC4 (converted from Euler)
scale.x/y/z→ scale VEC3
visibleNot exported (no glTF equivalent)
deform.*Not exported
material.*Not exported

Usage Example (evaluation)

// Get the Y position of "BouncingBox" at time 1.5
const Mc3Action& action = doc.actions.at("Bounce");
for (const auto& ch : action.channels) {
    if (ch.targetObject == "BouncingBox" &&
        ch.property == AnimatedProperty::PositionY) {
        float y = evaluateChannel(ch, 1.5f);
    }
}