# 通用渲染控制
Sprite 和 Spine 均支持按帧指定取景、变换和整体透明度;播放模式保存在动画实例上。
`render(time, width, height)` 使用 `RenderOptions::default()`:自动适配、居中和完整透明度。
`render_with_options(time, width, height, &options)` 使用本次传入的视觉选项,不写入实例。
两种 render 方法均遵守实例的播放模式,初始为 Loop。每次仍传入目标尺寸,不需要 resize 事件。
## Rust API
```rust
use std::time::Duration;
use anitty::{Animation, PlaybackMode, RenderOptions, RgbaFrame, SpriteAnimation, Transform};
let original = RgbaFrame::new(2, 1, vec![255, 0, 0, 255, 0, 255, 0, 128])?;
let mut animation = SpriteAnimation::new(vec![original], Duration::from_millis(100))?;
animation.set_playback_mode(PlaybackMode::Once);
let options = RenderOptions {
transform: Transform {
scale: [-1.0, 1.0], // 水平镜像;两种来源使用同一套选项
..Transform::default()
},
opacity: 0.8,
..RenderOptions::default()
};
let elapsed = Duration::from_millis(150);
let finished = animation.is_finished(elapsed);
let frame = animation.render_with_options(elapsed, 128, 128, &options)?;
assert!(finished);
assert_eq!((frame.width(), frame.height()), (128, 128));
# Ok::<(), anitty::Error>(())
```
`render_with_options(time, width, height, &options)` 与 `render` 一样返回借用的 RGBA 帧。
选项只影响本次调用;切换选项不重置时间、重载素材或改变后续默认渲染。已有输出缓冲继续复用,
容量不足才扩容,没有缓存历史帧、后台播放线程或隐式终端操作。
调用方可以在循环外创建一个 `RenderOptions`,逐帧借用传入,不必重复构造。
第三方实现 `Animation` 时,需要实现 `bounds` 和 `render_with_options`;默认 `render` 委托给后者。
`mapping(width, height, &options)` 默认按来源边界等比居中,自定义自动适配规则的来源应覆盖它,
使查询与渲染相符。需要对应本次绘制时,传入相同尺寸和 options。
动作查询与切换也通过 `Animation` 的 `animations`/`animation_name`/`set_animation` 提供,
Sprite 命名片段、局部时间和第三方实现要求见 [多动作说明](animations.md)。
播放模式需由实现保存,通过 `playback_mode`/`set_playback_mode` 查询与设置;
`is_finished(elapsed)` 默认使用当前模式与真实片段时长判断,无需另存完成状态。
## 变换和透明度
| `transform.translation` | 画布像素中的 `[x, y]` 位移;X 向右,Y 向下 |
| `transform.scale` | 基础适配后的 X/Y 缩放,默认 `[1, 1]`;负值镜像,零值报错 |
| `transform.rotation` | 弧度,正值顺时针;Rust 可用 `degrees.to_radians()` |
| `transform.pivot` | 基础适配后的画布坐标;`None` 为画布中心 |
| `opacity` | `[0, 1]` 的整体透明度,默认 1 |
顺序为:基础取景 → 围绕 pivot 缩放/镜像 → 围绕同一 pivot 旋转 → 平移 → 裁剪到输出画布。
尺寸决定画布,scale 决定角色大小;旋转不会自动放大画布,也不会改变动画时间。
中心镜像且没有其他空间变换时直接重排本帧像素,保持镜像前后的 RGBA 精确对应;没有额外重采样。
其他变换中,Sprite 从原始帧做预乘 alpha 双线性采样,Spine 直接变换顶点并光栅化。
变换后的 Spine 三角形对公共边采用一致的计算方向,避免旋转后因浮点符号差异重复覆盖半透明接缝。
通用旋转/缩放仍按像素中心采样,不添加超采样抗锯齿,也不承诺任意浮点变换往返后像素完全还原。
opacity 在角色内部混合结束、得到 RGBA8 后应用:alpha 四舍五入为 `原 alpha × opacity`。
非零 alpha 的 RGB 不变;opacity 非 1 时,最终 alpha 为零的像素清为透明黑。
这与逐 attachment 降低 alpha 的结果不同,重叠部位不会因整体淡出改变内部混合关系。
非法尺寸、非有限值、零 scale、越界 opacity 或无法表示的映射返回错误。
`opacity = 0` 在校验输入后直接清空输出,跳过 Sprite 采样和 Spine 求姿/光栅化。
恢复非零 opacity 时仍按本次绝对时间正常渲染,不需要补算隐藏期间的帧。
是否清除终端中的旧图仍由 backend 与宿主的覆盖语义决定。
## 固定取景和坐标查询
`Animation::bounds()` 返回当前来源的边界,统一为 X 向右、Y 向下:
- Sprite:原始帧的像素边界,原点为左上角。
- Spine:骨骼单位,原始 runtime 的 Y 坐标取反;范围是当前动作 121 个采样点的估计,不含自动适配边距。
默认自动取景规则:Sprite 的目标内容尺寸取整到像素并居中,Spine 保留 5% 的每侧边距。
设置 `options.view = Some(Bounds { x, y, width, height })` 后,两者都把指定矩形等比居中适配到画布,
不再加自动边距。宽高必须为正;view 决定映射,不是额外的裁剪遮罩,矩形外的内容仍可能出现在画布内。
如果要跨 Spine 动作保持比例和位置,可以保存一个参考动作的边界,或显式给定能容纳多个动作的矩形,
在每次渲染时复用同一个 view。固定矩形不随 `set_animation` 改变;用估算边界时仍可能裁剪超出范围的姿态。
`set_animation` 切换到不同动作时仍会测量动作边界。
`animation.mapping(width, height, &options)` 查询完整映射,不求姿、不改变动画状态:
- `map_point([x, y])`:来源坐标 → 画布坐标。
- `unmap_point([x, y])`:画布坐标 → 来源坐标。
整数坐标表示像素边缘,像素中心为 `(x + 0.5, y + 0.5)`。映射查询不进行像素取整,
Spine 默认光栅路径保留 f32 顶点运算,因此最后的浮点取整可能与 f64 坐标查询略有差异。
画布坐标不包含终端字符单元、光标位置或宿主布局偏移。
## 播放时间与结束
`animation.set_playback_mode(mode)` 设置实例的播放模式,`animation.playback_mode()` 查询它,默认 Loop。
模式在切换动作、替换 Sprite 片段定义、改变画布尺寸或渲染选项后保留,直到再次设置。
它是实例级的播放策略,不为每个命名片段分别保存;设置模式不重置时间。
`PlaybackMode::Loop` 按周期循环,`is_finished` 始终为 false。
`PlaybackMode::Once` 在结束后保持 Sprite 最后一帧或 Spine 的准确结束姿态;它不会自动隐藏画面或退出应用。
两种模式都允许任意绝对时间和回跳,没有基于上次 render 的状态。
完成判断使用 `animation.is_finished(elapsed)`;Once 在到达结束时刻时为 true。
`clip_duration()` 返回真实动作时长;静态 Spine 动作为零,Once 在零时刻即完成,但仍可反复渲染静态姿势。
`duration()` 返回非零周期,静态 Spine 返回一秒;判断实际结束时刻应使用 `clip_duration()`。
暂停、继续、调速、定位和重新开始由宿主维护局部时间即可:暂停时保持时间不变,恢复后继续累加,
调速时把后续增量时间乘以速度,定位或重播时直接设置局部时间。动态调速不要直接改变
“总墙钟经过时间 × 速度”,否则切换速度时会跳帧。库不强制增加播放器对象。
完成状态是无副作用的查询,不会触发回调;动作决策、队列和完成通知由宿主管理。
## 变换开销与帧预算
取景、缩放、旋转、pivot 和平移会合成为一个坐标映射。Sprite 每个目标像素只从原帧采样一次,
Spine 将变换应用到顶点后光栅化一次,不会每增加一种变换就多渲染整张图。
只有中心镜像的专门路径使用像素重排;非默认整体 opacity 在 RGBA8 输出上额外遍历一次。
主要成本取决于画布尺寸、变换后的覆盖面积,以及 Spine 的网格复杂度和重叠层数。
例如放大角色通常增加需要采样/混合的像素;移出画布则可能减少工作量。
不能把某一种组合变换的耗时作为所有组合的固定成本。
帧预算应包括 render、backend 编码、写入和终端处理,不能仅用 render 耗时推断实际帧率。
建议使用 release 构建,并在目标素材、尺寸和终端上测量。
60 FPS 的总预算约为 16.67ms;CLI 来不及按间隔绘制时会按当前绝对时间继续采样,
降低实际帧率,不补算所有中间姿势。
## 返回帧与错误处理
`render` 返回的帧借用自动画实例。使用完该借用后才能再次可变访问实例;
需要长期保存画面时可显式 `clone()`,这会复制像素。
`RgbaFrame` 的格式与输入要求见 [动画指南](animations.md)。
错误以 `Result` 返回:`InvalidFrame` 表示非法帧尺寸或缓冲区,`InvalidSprite` 表示片段或图集定义错误,
`InvalidRender` 表示视觉参数或映射无效,`AnimationNotFound` 表示不存在的动作,
`InvalidBackend` 表示 backend 配置无效。编码和 I/O 失败保留为 `Image`、`Sixel`、`Io`,
启用 Spine 时另有 `Spine` 错误。
应用负责展示错误和恢复自己的终端会话,库不会把失败伪装成空白帧。
CLI 参数与运行示例见 [示例指南](examples.md)。