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();
}
}
三个语义要点:
- 等值守卫:
timePos != mTimePos才处理,避免同值重复触发脏标记; - 循环 = fmod 回绕:
std::fmod(mTimePos, mLength)把时间折叠进[0, mLength);负值(时间被回调)加一个mLength补正——所以-0.5在 2 秒动画里变成1.5,而非负值或错误; - 非循环 = 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(...) 采样到骨架。
源码定位
OgreMain/include/OgreAnimationState.h:AnimationState(mTimePos/mLength/mWeight/mEnabled/mLoop)、AnimationStateSet(createAnimationState/getAnimationState/mEnabledAnimationStates)OgreMain/src/OgreAnimationState.cpp:setTimePosition回绕/钳制、addTime、hasEnded、setEnabled、_notifyAnimationStateEnabled
上游引用固定到 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 二进制序列化格式 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。