File 与 Artboard

Rive .riv 文件是一个二进制容器，包含 artboards、animations、state machines、view models 和 assets。C++ API 既提供对这个容器的只读访问（File、Artboard），也提供可推进、可绘制的可变实例（ArtboardInstance、StateMachineInstance）。

导入文件

#include "rive/file.hpp"

ImportResult result;
rcp<File> file = File::import(
    Span<const uint8_t>{bytes.data(), bytes.size()},
    factory,        // Factory*，通常是你的 RenderContext
    &result,        // 可选
    assetLoader);   // 可选 rcp<FileAssetLoader>

switch (result) {
    case ImportResult::success:           break;
    case ImportResult::unsupportedVersion: /* runtime 比文件旧 */ break;
    case ImportResult::malformed:          /* 字节数据损坏 */       break;
}

File 使用引用计数（rcp<File>）。它持有解析后的对象图和 in-band 导入的资源。只要仍有从它派生出的 artboard instance 存活，就需要保持 File 存活。

注意

传入的 Factory* 负责构造文件产生的所有 RenderPath、RenderPaint、RenderImage、字体和音频源。使用 Rive GPU renderer 时，这通常是你的 RenderContext；使用自定义 renderer 时，则是你的 Factory 实现。

确定性

File::deterministicMode = true;

这是一个静态标志，会为后续所有加载强制使用固定 RNG seed 和基于时间戳的滚动。它适合 golden-image 测试和逐帧捕获。

查询 Artboards

size_t count = file->artboardCount();
std::string name = file->artboardNameAt(0);

Artboard* byName = file->artboard("Hero");          // 按名称
Artboard* byIndex = file->artboard(size_t{0});      // 按索引
Artboard* first = file->artboard();                 // 文件中的第一个 artboard

这些访问器返回的 Artboard* 是只读元数据，不要直接 advance 或 draw。要播放画板，请创建实例。

实例化

// 最常见：复制文件的默认 artboard。
std::unique_ptr<ArtboardInstance> ab = file->artboardDefault();

// 也可以按名称 / 索引：
auto namedAb = file->artboardNamed("Hero");
auto indexedAb = file->artboardAt(2);

每次调用都会返回一个全新、独立的副本。你可以同时播放同一个 artboard 的多个实例，每个实例都有自己的状态机、数据绑定和布局。

size_t   anims  = ab->animationCount();
size_t   states = ab->stateMachineCount();
std::string animName = ab->animationNameAt(0);
std::string smName   = ab->stateMachineNameAt(0);

// 设计师标记的默认状态机（如果有）。
int defaultIdx = ab->defaultStateMachineIndex();   // 没有则为 -1

创建 State Machine

StateMachineInstance 是 C++ 中的播放单元：你每帧推进它、绘制它，并向它转发指针事件。

#include "rive/animation/state_machine_instance.hpp"

std::unique_ptr<StateMachineInstance> sm = ab->defaultStateMachine();
if (!sm && ab->stateMachineCount() > 0) {
    sm = ab->stateMachineAt(0);
}

尺寸与布局

Artboard 有在编辑器中设置的固有尺寸，也可以有可选的布局模式（由 Yoga 驱动）。对于非 layout fit，artboard 保持固有尺寸；对于 Fit::layout，你需要自行驱动宽高：

#include "rive/layout.hpp"

if (fit == Fit::layout) {
    ab->width(static_cast<float>(windowWidth));
    ab->height(static_cast<float>(windowHeight));
} else {
    ab->resetSize();   // 回到固有尺寸
}

// 在下一次 draw 前重新计算布局。
sm->advanceAndApply(0.f);

Artboard::bounds() 返回当前矩形，可传给 computeAlignment，把 artboard-space 映射到 viewport。

File 生命周期

引用计数所有权能让生命周期更简单：

rcp<File> file = File::import(...);
auto ab = file->artboardDefault();   // unique_ptr<ArtboardInstance>
auto sm = ab->defaultStateMachine(); // unique_ptr<StateMachineInstance>

// 按相反顺序销毁：
sm.reset();
ab.reset();
file = nullptr;     // 最后一个 rcp 释放 File

始终在销毁 RenderContext 之前销毁 Rive 对象，因为它们持有由 context 拥有的 GPU 资源引用。