Skip to content

Interpolate an animated perspective like CSS - #3819

Merged
shlzxjp merged 4 commits into
Tencent:mainfrom
mite085:feature/mite085_perspective_interp
Nov 17, 2026
Merged

shlzxjp merged 4 commits into
Tencent:mainfrom
mite085:feature/mite085_perspective_interp

Conversation

@mite085

@mite085 mite085 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

问题

项 说明
现象 导出的 HTML 动画首尾帧一致,差异集中在中间帧
原因 浏览器插值的是透视的投影系数 -1/d,PAGX 插值的是距离 d
量化 1000px → 200px 的中点:浏览器 d = 333.3,PAGX 为 600

改动

所有写入透视距离的路径统一到同一份混合实现,公开 API 不变:

写入路径 改动
关键帧求值 透视通道走专用求值,混合投影系数;其余通道与原逻辑完全一致
时间轴 crossfade、带权重的数据绑定 变换分量的混合对透视复用同一份实现,因此与关键帧同速率
其余属性与通道 不变

透视的判定只有一处(通道求值层按通道名分流),EvaluateKeyframeSequence 的签名与行为、include/ 与通道表均未改动。落地文件:

文件 作用
src/pagx/animation/Channel.cpp 按 name == "perspective" 分流到透视求值,其余通道走原函数
src/pagx/runtime/KeyframeEvaluatorImpl.h 新增 EvaluatePerspectiveSequence;EvaluateKeyframeSequence 签名与行为不变,选段与求缓动的逻辑抽成 ResolveKeyframeSegment 共用
src/pagx/runtime/MixUtils.h 新增 MixPerspectiveDistance,全项目唯一的 -1/d 混合实现
src/renderer/LayerBuilder.cpp applyComponent 的 PerspectiveDistance 复用同一份混合;负距离显式拒绝
test/src/PAGXRuntimeTest.cpp 3 个用例:系数混合、0 端点连续性、导入端到端
spec/pagx_spec.md、spec/pagx_spec.zh_CN.md §8.1.4 与通道表补充透视插值说明

行为

场景 行为
1000 → 200 中点 333.3;缓动作用在系数上,Linear / Bezier / Hold 语义不变
一端为 0(无透视) 视为系数 0,即 d → ∞ 那一端:0 → 200 中点 400、第一帧 d ≈ 12000,整段连续
缓动越界使系数 ≤ 0 夹到"无透视",不会产生负距离
写入负距离 拒绝,与既有校验一致

效果

12_perspective.pagx,pagx 源模式(参考为 pagx render --time,候选为导出 HTML 在浏览器按同一采样时刻截图),共 8 帧:

SSIM 均值 SSIM 最低
改动前 0.8185 0.7170
改动后 0.9982 0.9961

两侧 motion span 均为 3.49(确实都在动),pixelDiff 0.00%,残差 rgbΔ 0.05 属两家光栅器的抗锯齿差异。

用例输入:

12_perspective.pagx
12-perspective.html

验证

  • PAGFullTest_OpenGL 全量 2808 例通过

@codecov-commenter

codecov-commenter commented Nov 5, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.85714% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.71%. Comparing base (afab5c8) to head (b8c38bd).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
src/pagx/runtime/KeyframeEvaluatorImpl.h 84.21% 2 Missing and 4 partials ⚠️
src/pagx/runtime/MixUtils.h 88.88% 0 Missing and 1 partial ⚠️
src/renderer/LayerBuilder.cpp 88.88% 0 Missing and 1 partial ⚠️
test/src/PAGXRuntimeTest.cpp 98.38% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3819      +/-   ##
==========================================
+ Coverage   83.34%   83.71%   +0.36%     
==========================================
  Files         754      762       +8     
  Lines      111162   113692    +2530     
  Branches    31182    31476     +294     
==========================================
+ Hits        92644    95172    +2528     
+ Misses      11317    11232      -85     
- Partials     7201     7288      +87     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Hparty Hparty left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

方向是对的:透视确实该按投影系数插值,端点、spec 和测试也都对上了。但为一个通道加整套插值空间机制偏重,建议退回就地实现,细节见行内评论;另外 0 端点区间的预期也确认一下。

Comment thread include/pagx/nodes/Channel.h Outdated
* channel constructed programmatically keeps the Value default, so a caller creating a
* perspective channel by hand must set this itself.
*/
KeyframeInterpolationSpace interpolationSpace = KeyframeInterpolationSpace::Value;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里没必要为透视单独引一套插值空间机制。全项目只有 Layer.perspective 用到倒数插值(通道表里 FIELD_PERSPECTIVE 就一行),为它新增公共 enum、Channel 字段、ChannelDef 列和导入末尾的派生 pass,成本明显高于收益。

建议就地实现:

  1. KeyframeEvaluatorImpl.h 里只留一个透视专用求值(1/d 混合),EvaluateKeyframeSequence 的签名不动;
  2. 判断放在 Channel.cpp,name == "perspective" 时走它——那里本来就有 name,项目里也有 Matrix3DComponentFromChannel 这种按名字映射的先例;
  3. LayerBuilder::applyComponent 里对 PerspectiveDistance 用同一份混合,状态机 crossfade 和数据绑定带权重的写入也就一致了。

这样 KeyframeInterpolationSpace、Channel::interpolationSpace、GetChannelInterpolationSpace 和 PAGXImporter 里那遍 ResolveChannelInterpolationSpaces 都可以删掉。

另外 0 端点想确认一下预期:现在这段回退成按距离线性,perspective 0 → 200 在第 1 帧就到 d≈3.3(系数 -0.30,而终点才 -0.005),等于从无透视一帧内冲到强透视再回落。按系数 0(无穷远)映射的话整段是连续的。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

两条都采纳了,已更新。

  1. 去掉那套插值空间机制。 只保留透视这一处的就地实现:判定放在通道求值那一层,混合逻辑全项目只有一份,crossfade 和带权重的数据绑定复用它,所以和关键帧插值一致了。改动面从 10 个文件降到 7 个,公开头文件和通道表都没动。

  2. 0 端点改成按系数 0(即无穷远)映射。 0 → 200 现在整段连续:第一帧 d ≈ 12000、中点 400、末端 200。原来回退成按距离线性,第一帧会冲到 d ≈ 3.3 再回落,确实是跳变。

顺手补了一个坑:混合会把负距离折叠成"无透视",所以写入负值时现在显式拒绝,原有那条 component 写入校验的用例覆盖到了。

@mite085
mite085 force-pushed the feature/mite085_perspective_interp branch 2 times, most recently from 55e54da to d419b08 Compare November 16, 2026 02:15
@mite085
mite085 force-pushed the feature/mite085_perspective_interp branch from d419b08 to 6462092 Compare November 16, 2026 06:49
}
// A negative distance is not a projection. The perspective blend folds it into "no projection"
// along with the d -> infinity end, so reject it here rather than write a cleared projection.
if (component == Matrix3DComponent::PerspectiveDistance && *v < 0.0f) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里新增的负距离拒绝是该函数里唯一没有日志的分支:兄弟分支(467、475 行)都用 rejectedXxxLogged 做一次性 LOGE,改动前这条负值在 mix=1 时还会走到 commitComponents 打出 494 行的日志。现在动画或数据绑定写入负距离后投影直接定格,且没有任何提示,排查成本较高。建议同样加一个 rejectedValueLogged 一次性 LOGE(或在导入端拒绝负值,与静态属性校验保持一致)。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已补:沿用兄弟分支的 rejectedXxxLogged 写法,首次拒绝负距离时打一次 LOGE。

commit 82b84e02f。

// A perspective distance mixes its projection coefficient, so a crossfade or a weighted data
// bind moves the projection at the same rate as a keyframe blend does.
if (component == Matrix3DComponent::PerspectiveDistance) {
*field = MixPerspectiveDistance(static_cast<float>(*field), *v, mix);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这条分支(crossfade、带权重的数据绑定)是本 PR 改 LayerBuilder.cpp 的目的,但目前没有测试覆盖:三个新用例只验证 EvaluatePerspectiveSequence / MixPerspectiveDistance 与 Channel 派发,把这里改回 MixFloat 新用例仍会全绿(Codecov 对该文件 patch 覆盖也只有 33.33%)。建议补 2~3 个 binding 级用例:从 0 起 apply("perspective", 200, 0.5) 读回 400;从 1000 起同目标读回 333.33;-1 返回 false 且值不变。MixPerspectiveDistance 的缓动过冲夹取分支也没有覆盖,可一并补上。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已补 binding 级用例,覆盖 0 → 200 权重 0.5 得 400、1000 → 200 得 333.33、负值被拒且值不变,另补了过冲夹取分支。为确认用例有效,我把实现临时换回 MixFloat,该用例会失败。

commit 82b84e02f。

return 0.0f;
}
if (framePosition <= static_cast<double>(keyframes.front().time)) {
return keyframes.front().value;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里的首尾钳制(241、244 行)原样返回关键帧值,而区段内会经 MixPerspectiveDistance 把负值折叠成"无透视",同一份非法数据因此表现不一致:区段内 d 趋向 ∞,到端点却返回负距离、被 LayerBuilder 静默丢弃,出现定格或跳变。根因在导入端:PAGXImporter 对关键帧只校验 std::isfinite(1744-1751),不像静态属性(522-524)那样拒绝 perspective 负值,而 spec 第 1005 行已声明负值非法。建议在导入端按通道名拒绝负值;若不在导入端处理,这里的三个返回点应统一做 < 0 → 0 归一。

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已改为“负值一律视为无透视”:首帧钳制、尾帧钳制、Hold 段三个返回点统一归一,与区段内混合保持一致,不再出现定格或跳变。

依据是在 Chrome 里实测 CSS 的行为:负值属非法值,浏览器丢弃该声明;端点非法时回退到元素的静态值。而 PAGX 图层的静态 perspective 通常就是 0,所以“按无透视”与 CSS 等价,也与导出侧(非正值不写 perspective())一致。

已知偏差:中间关键帧为负时我们是“经过无透视”,CSS 是跳过该帧;要完全对齐需把静态值注入端点,代价较大,故先保持现状。spec 已补说明,并加了首/尾/Hold 三处用例。

commit d110b7a27。

Comment thread spec/pagx_spec.md Outdated
| `Bezier` | Cubic bezier easing using `bezierOut` and the next keyframe's `bezierIn` handles |
| `Hold` | Holds value until the next keyframe, then jumps |

**Perspective interpolation**: a `Layer`'s `perspective` reaches the renderer as the projection coefficient `-1/d`, so its keyframes interpolate that coefficient rather than the distance — a distance animating from 1000 to 200 passes through about 333 at the midpoint instead of 600. This is how a browser interpolates the `perspective()` transform function of a CSS keyframe animation, and it keeps the projection tightening at a constant rate. The easing applies to the coefficient, so `Linear`, `Bezier` and `Hold` keep their meaning. A distance of 0 means no projection, which is the coefficient 0, i.e. the infinite-distance end of that space, so it blends continuously with a finite distance: mixing 0 with 200 halfway yields 400 rather than snapping to a near camera. A negative distance is not a projection either: a keyframe holding one reads as no projection, which mirrors a browser dropping the invalid declaration and falling back to the element's static distance. Every other channel interpolates its values.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这句“falling back to the element's static distance”与实际实现不一致:SanitizePerspectiveDistance(src/pagx/runtime/MixUtils.h:64)无条件返回 0,求值器的首帧/尾帧/Hold 三个返回点(src/pagx/runtime/KeyframeEvaluatorImpl.h:244/247/253)都会把负值归一为“无透视”。当图层本身有非零静态 perspective(如 500)时,CSS 会回退到 500,PAGX 却会清空为无透视。建议把这句改成“按无透视处理”,或明确这是 PAGX 的简化约定;中文 spec 同一句(spec/pagx_spec.zh_CN.md:2474)也需同步。属文档措辞问题,不影响功能正确性。

@shlzxjp
shlzxjp merged commit 243b289 into Tencent:main Nov 17, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants