《OGRE 3D 渲染引擎原理与架构》9.3 AnimationState 与动画播放

AnimationState 是动画的运行时状态:时间位置、长度、权重、是否启用与是否循环。setTimePosition 在循环下用 fmod 回绕(负值补长度)、非循环下用 clamp 钳制到 [0,length];addTime 累加时间;hasEnded 仅在非循环且到尾部时为真。AnimationStateSet 按名字登记状态,重复抛错,维护 enabled 列表与 dirty 帧号。lab 用 C++ 复现播放状态机。

9.3 AnimationState 与动画播放

Animation 是动画的静态定义(轨道 + 关键帧,9.2),AnimationState 是动画的运行时状态:现在播到哪个时间点、总长多少、权重多少、是否启用、是否循环。实体/骨架播放动画时持有一组 AnimationState(由 AnimationStateSet 管理),每帧推进时间再交给 Animation 应用。

本章与站内既有内容的分工

9.2 讲关键帧数据的定义与插值;本节的 AnimationState 讲播放状态机——时间如何回绕/钳制、何时算结束、何时触发脏标记。helio 卷三的动画状态机讲 TypeScript 播放调度,这里讲 OGRE 源码里的对应实现。

AnimationState:六个运行时字段

OgreAnimationState.h 里 AnimationState 的成员是一组播放参数:

// OgreMain/include/OgreAnimationState.h:AnimationState 成员(v14.6.3 源码摘录,已删减)
        String mAnimationName;
        AnimationStateSet* mParent;
        Real mTimePos;
        Real mLength;
        Real mWeight;
        bool mEnabled;
        bool mLoop;
  • mAnimationName:绑定的动画名(对应 Animation 的 name);
  • mTimePos:当前时间位置(秒);
  • mLength:本状态的可播长度(可以短于整个动画);
  • mWeight:影响力权重(多动画混合时,1.0 全量,小于 1.0 淡入淡出);
  • mEnabled:是否启用(未启用不参与采样);
  • mLoop:是否循环(默认 true)。

setTimePosition:回绕与钳制

OgreAnimationState.cpp 的 setTimePosition 是播放的核心。时间设置先存值,再按循环与否做归一化:

// OgreMain/src/OgreAnimationState.cpp:AnimationState::setTimePosition(v14.6.3 源码摘录,已删减)
    void AnimationState::setTimePosition(Real timePos)
    {
        if (timePos != mTimePos)
        {
            mTimePos = timePos;
            if (mLoop)
            {
                // Wrap
                mTimePos = std::fmod(mTimePos, mLength);
                if(mTimePos < 0) mTimePos += mLength;
            }
            else
            {
                // Clamp
                mTimePos = Math::Clamp(mTimePos, Real(0), mLength);
            }

            if (mEnabled)
                mParent->_notifyDirty();
        }
    }

三个语义要点:

  1. 等值守卫:timePos != mTimePos 才处理,避免同值重复触发脏标记;
  2. 循环 = fmod 回绕:std::fmod(mTimePos, mLength) 把时间折叠进 [0, mLength);负值(时间被回调)加一个 mLength 补正——所以 -0.5 在 2 秒动画里变成 1.5,而非负值或错误;
  3. 非循环 = clamp 钳制:Math::Clamp(mTimePos, 0, mLength) 把越界时间钉在端点,配合 hasEnded 判断播放是否到头。

addTime 与 hasEnded

addTime 是增量推进(逐帧驱动动画的入口),hasEnded 是结束判定:

// OgreMain/src/OgreAnimationState.cpp:AnimationState::addTime / hasEnded(v14.6.3 源码摘录,已删减)
    void AnimationState::addTime(Real offset)
    {
        setTimePosition(mTimePos + offset);
    }
    //---------------------------------------------------------------------
    bool AnimationState::hasEnded(void) const
    {
        return (mTimePos >= mLength && !mLoop);
    }

addTime(offset) 等价于 setTimePosition(mTimePos + offset)——增量推进复用同一套回绕/钳制逻辑,所以循环动画会自动回绕。hasEnded 只在非循环且时间到达尾部时为真:循环动画永不结束,非循环动画靠 clamp 把时间钉在 mLength 后,mTimePos >= mLength 成立。

setEnabled 与脏标记

setEnabled 把启用状态通知给父级 AnimationStateSet,让父级维护「启用的动画状态」列表:

// OgreMain/src/OgreAnimationState.cpp:AnimationState::setEnabled(v14.6.3 源码摘录,已删减)
    void AnimationState::setEnabled(bool enabled)
    {
        mEnabled = enabled;
        mParent->_notifyAnimationStateEnabled(this, enabled);
    }

_notifyAnimationStateEnabled 先从 enabled 列表移除目标,若启用再加入,然后递增脏帧号:

// OgreMain/src/OgreAnimationState.cpp:AnimationStateSet::_notifyAnimationStateEnabled(v14.6.3 源码摘录,已删减)
    void AnimationStateSet::_notifyAnimationStateEnabled(AnimationState* target, bool enabled)
    {
        OGRE_LOCK_AUTO_MUTEX;
        // Remove from enabled animation state list first
        mEnabledAnimationStates.remove(target);

        // Add to enabled animation state list if need
        if (enabled)
        {
            mEnabledAnimationStates.push_back(target);
        }

        // Set the dirty frame number
        _notifyDirty();
    }

脏帧号(mDirtyFrameNumber)是增量计数器:每次动画状态被修改(时间/权重/启用)都递增。每帧开始,播放器检查脏帧号是否变化,决定要不要重新应用动画——这是「只重算有变化的状态」的惰性机制,对应 OGRE 里「animation state set dirty 驱动采样」的设计。

AnimationStateSet:按名字登记

AnimationStateSet 持有整组状态。创建同名状态抛 ERR_DUPLICATE_ITEM,取不存在的抛 ERR_ITEM_NOT_FOUND:

// OgreMain/src/OgreAnimationState.cpp:AnimationStateSet::createAnimationState / getAnimationState(v14.6.3 源码摘录,已删减)
    AnimationState* AnimationStateSet::createAnimationState(const String& name,  
        Real timePos, Real length, Real weight, bool enabled)
    {
        ...
        AnimationStateMap::iterator i = mAnimationStates.find(name);
        if (i != mAnimationStates.end())
        {
            OGRE_EXCEPT(Exception::ERR_DUPLICATE_ITEM, 
                "State for animation named '" + name + "' already exists.", 
                "AnimationStateSet::createAnimationState");
        }
        AnimationState* newState = OGRE_NEW AnimationState(name, this, timePos, 
            length, weight, enabled);
        mAnimationStates[name] = newState;
        return newState;
    }
    //---------------------------------------------------------------------
    AnimationState* AnimationStateSet::getAnimationState(const String& name) const
    {
        ...
        AnimationStateMap::const_iterator i = mAnimationStates.find(name);
        if (i == mAnimationStates.end())
        {
            OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND, 
                "No state found for animation named '" + name + "'", 
                "AnimationStateSet::getAnimationState");
        }
        return i->second;
    }

mAnimationStates 是 std::map<String, AnimationState*>,以动画名作键。播放循环通常:getAnimationState(name) 取状态 → addTime(dt) 推进 → 若 dirty 则 animation.apply(...) 采样到骨架。

源码定位

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现播放状态机:回绕/钳制、addTime、hasEnded、enabled 列表与 dirty 帧号。它与 src/09-3-animation-state.cpp 逐字节一致:

// file: src/09-3-animation-state.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/09-3-animation-state.cpp -o bin/09-3-animation-state && ./bin/09-3-animation-state
//
// 复现 OgreAnimationState / OgreAnimationStateSet:
//   setTimePosition 循环 fmod 回绕(负值补长度)、非循环 clamp 到 [0,length];
//   addTime = setTimePosition(mTimePos + offset);hasEnded 仅非循环且到尾部;
//   AnimationStateSet 按名字登记、重复抛错、enabled 列表维护、dirty 帧号递增。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cmath>
#include <map>
#include <string>
#include <vector>

namespace ogre_repro {

// 对应 OGRE_EXCEPT 的两个错误场景
struct DuplicateItem {};
struct ItemNotFound {};

// 对应 AnimationState(OgreAnimationState.h/OgreAnimationState.cpp)
class AnimationStateSet;

class AnimationState {
 public:
  std::string mAnimationName;
  AnimationStateSet* mParent;
  double mTimePos = 0.0;
  double mLength = 0.0;
  double mWeight = 1.0;
  bool mEnabled = false;
  bool mLoop = true;

  AnimationState(const std::string& animName, AnimationStateSet* parent,
                 double timePos, double length, double weight, bool enabled)
      : mAnimationName(animName), mParent(parent), mTimePos(timePos),
        mLength(length), mWeight(weight), mEnabled(enabled), mLoop(true) {}

  const std::string& getAnimationName() const { return mAnimationName; }
  double getTimePosition() const { return mTimePos; }
  double getLength() const { return mLength; }
  void setLength(double len) { mLength = len; }
  double getWeight() const { return mWeight; }
  bool getEnabled() const { return mEnabled; }
  bool getLoop() const { return mLoop; }
  void setLoop(bool loop) { mLoop = loop; }

  // 对应 AnimationState::setTimePosition:循环回绕、非循环钳制
  void setTimePosition(double timePos);

  // 对应 AnimationState::addTime
  void addTime(double offset) { setTimePosition(mTimePos + offset); }

  // 对应 AnimationState::hasEnded
  bool hasEnded() const { return (mTimePos >= mLength && !mLoop); }

  // 对应 AnimationState::setWeight
  void setWeight(double weight);

  // 对应 AnimationState::setEnabled:登记到父的 enabled 列表
  void setEnabled(bool enabled);
};

// 对应 AnimationStateSet(OgreAnimationState.h)
class AnimationStateSet {
 public:
  std::map<std::string, AnimationState*> mAnimationStates;
  std::vector<AnimationState*> mEnabledAnimationStates;
  unsigned long mDirtyFrameNumber = std::numeric_limits<unsigned long>::max();

  ~AnimationStateSet() {
    for (auto& kv : mAnimationStates) delete kv.second;
  }

  // 对应 createAnimationState:同名抛 ERR_DUPLICATE_ITEM
  AnimationState* createAnimationState(const std::string& name, double timePos,
                                       double length, double weight, bool enabled) {
    if (mAnimationStates.find(name) != mAnimationStates.end())
      throw DuplicateItem();
    AnimationState* s = new AnimationState(name, this, timePos, length, weight, enabled);
    mAnimationStates[name] = s;
    return s;
  }

  // 对应 getAnimationState:未找到抛 ERR_ITEM_NOT_FOUND
  AnimationState* getAnimationState(const std::string& name) const {
    auto i = mAnimationStates.find(name);
    if (i == mAnimationStates.end()) throw ItemNotFound();
    return i->second;
  }

  bool hasAnimationState(const std::string& name) const {
    return mAnimationStates.find(name) != mAnimationStates.end();
  }

  void removeAnimationState(const std::string& name) {
    auto i = mAnimationStates.find(name);
    if (i != mAnimationStates.end()) {
      auto& el = mEnabledAnimationStates;
      el.erase(std::remove(el.begin(), el.end(), i->second), el.end());
      delete i->second;
      mAnimationStates.erase(i);
    }
  }

  // 对应 _notifyAnimationStateEnabled
  void _notifyAnimationStateEnabled(AnimationState* target, bool enabled) {
    auto& el = mEnabledAnimationStates;
    el.erase(std::remove(el.begin(), el.end(), target), el.end());
    if (enabled) el.push_back(target);
    _notifyDirty();
  }

  // 对应 _notifyDirty:dirty 帧号递增
  void _notifyDirty() { ++mDirtyFrameNumber; }

  bool hasEnabledAnimationState() const { return !mEnabledAnimationStates.empty(); }
  unsigned long getDirtyFrameNumber() const { return mDirtyFrameNumber; }
};

// 方法定义在 AnimationStateSet 之后(需调用其 _notifyDirty 等)
void AnimationState::setTimePosition(double timePos) {
  if (timePos != mTimePos) {
    mTimePos = timePos;
    if (mLoop) {
      // Wrap
      mTimePos = std::fmod(mTimePos, mLength);
      if (mTimePos < 0) mTimePos += mLength;
    } else {
      // Clamp
      mTimePos = std::clamp(mTimePos, 0.0, mLength);
    }
    if (mEnabled) mParent->_notifyDirty();
  }
}

void AnimationState::setWeight(double weight) {
  mWeight = weight;
  if (mEnabled) mParent->_notifyDirty();
}

void AnimationState::setEnabled(bool enabled) {
  mEnabled = enabled;
  mParent->_notifyAnimationStateEnabled(this, enabled);
}

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  AnimationStateSet set;
  CHECK(set.getDirtyFrameNumber() == std::numeric_limits<unsigned long>::max());

  // 创建状态:默认 mLoop = true
  AnimationState* walk = set.createAnimationState("Walk", 0.0, 2.0, 1.0, false);
  CHECK(set.hasAnimationState("Walk"));
  CHECK(walk->getLoop());

  // 同名重复创建 → 抛 DuplicateItem
  bool threw = false;
  try {
    set.createAnimationState("Walk", 0.0, 2.0, 1.0, false);
  } catch (const DuplicateItem&) {
    threw = true;
  }
  CHECK(threw);

  // 不存在 → 抛 ItemNotFound
  threw = false;
  try {
    set.getAnimationState("Nope");
  } catch (const ItemNotFound&) {
    threw = true;
  }
  CHECK(threw);
  CHECK(!set.hasAnimationState("Nope"));

  // 循环回绕:2.5 mod 2.0 == 0.5;负值补长度:-0.5 + 2.0 == 1.5
  walk->setTimePosition(2.5);
  CHECK(walk->getTimePosition() == 0.5);
  walk->setTimePosition(-0.5);
  CHECK(walk->getTimePosition() == 1.5);

  // 非循环钳制:3.0 被 clamp 到 2.0
  walk->setLoop(false);
  walk->setTimePosition(3.0);
  CHECK(walk->getTimePosition() == 2.0);
  CHECK(walk->hasEnded());  // mTimePos >= mLength && !mLoop

  // addTime = setTimePosition(mTimePos + offset)(浮点加法,用近似比较)
  walk->setTimePosition(0.4);
  walk->addTime(0.2);
  CHECK(std::abs(walk->getTimePosition() - 0.6) < 1e-9);

  // 未启用时修改时间不触发 dirty
  CHECK(walk->getEnabled() == false);
  unsigned long before = set.getDirtyFrameNumber();
  walk->setTimePosition(0.8);
  CHECK(set.getDirtyFrameNumber() == before);  // 未启用,无 dirty 通知

  // setEnabled(true) → 进入 enabled 列表并触发 dirty
  walk->setEnabled(true);
  CHECK(walk->getEnabled());
  CHECK(set.hasEnabledAnimationState());
  CHECK(set.getDirtyFrameNumber() == before + 1);
  before = set.getDirtyFrameNumber();
  walk->setTimePosition(0.9);  // 启用后修改触发 dirty
  CHECK(set.getDirtyFrameNumber() == before + 1);

  // setEnabled(false) → 移出 enabled 列表
  walk->setEnabled(false);
  CHECK(!set.hasEnabledAnimationState());

  // setWeight
  walk->setWeight(0.5);
  CHECK(walk->getWeight() == 0.5);

  // removeAnimationState:按名字移除,enabled 列表同步清出
  set.removeAnimationState("Walk");
  CHECK(!set.hasAnimationState("Walk"));

  return lab::report("09-3 骨架动画:AnimationState 与动画播放");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 20/20 通过。

小结

  • AnimationState 是动画的运行时状态:时间位置、长度、权重、启用、循环六字段。
  • setTimePosition:循环用 fmod 回绕(负值补长度),非循环用 clamp 钳制到 [0, length];等值守卫避免重复触发脏标记。
  • addTime(offset) 复用 setTimePosition(mTimePos + offset);hasEnded 仅非循环且到尾部为真。
  • setEnabled 让父级维护 enabled 列表并递增脏帧号,驱动「有变化才重采样」的惰性机制。
  • AnimationStateSet 按名字登记状态,重复创建抛 ERR_DUPLICATE_ITEM、取不存在抛 ERR_ITEM_NOT_FOUND。

阅读导航:上一节:9.2 Animation 与关键帧 · 下一节:10.1 二进制序列化格式 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图