Skip to content

Support 3D layer transform in PAG rendering - #3815

Merged
shlzxjp merged 17 commits into
mainfrom
feature/markffan_transform_3d
Nov 16, 2026
Merged

shlzxjp merged 17 commits into
mainfrom
feature/markffan_transform_3d

Conversation

@CodeJhF

@CodeJhF CodeJhF commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

背景与范围

补齐开源 libpag 对 PAG 三维图层和相机的渲染支持,并修复原评审指出的非 GL 管线、特效偏移、父链、透明遮挡及测量/命中问题。
当前提交 b57125a86 已 rebase 到 main ae22417d7。本 PR 不实现景深,不引入独立矩阵库、新的 SDK 公共方法或额外逐层深度预计算纹理。

原评审阻塞项处理

原问题 当前处理
uniform stage 未指定 顶点/片元 block 分别声明 ShaderVisibility::Vertex / Fragment
深度附件与管线格式不匹配 显式使用 DEPTH24_STENCIL8
非法 clearDepth 和裁剪约定 clear 为 0,投影输出适配零到 w,片元检查原视锥
3D 与特效 offset 重复累加 入口清零、滤镜覆盖写偏移,CornerPin 等路径有回归
Apply 职责过多 拆出属性采样、模型父链和相机视图;复用 tgfx::Matrix3D,Apply 仅编排投影滤镜

Has3DSupport() 不再恒为 true:检查 stencil 附件能力、采样器/尺寸/uniform 限制及颜色格式。能力不足或变换无效时,不将三维层退回未经变换的二维绘制。

实现与必要配套

  • 矩阵与相机:复用 tgfx 标准投影和矩阵,累乘完整父链,支持 3D 父层下的 2D 子层;按活动区间和可见性选择共享相机上下文。
  • 透明遮挡:连续三维层在 composition 级组织,逐像素 depth peeling 后合成,保留透明度、共面图层顺序和混合模式。不再用跨图层深度写入剔除后方内容,也不再用 layer ID 或 frameSequence() 猜帧边界。
  • 深度一致性与性能:CPU 稳定求解深度平面;普通片元用有界 Q32 整数乘加,一次量化为 24 位码。转换前检查范围,超范围或裁剪/量化不确定区间复用原高精度编码,不丢图层。颜色、深度、索引输出及 peeling 轮次使用相同规则;std140 布局有 size/offset 断言。
  • 视口与命中:运行时尺寸、奇数/小数倍率的逻辑视口与深度采样一致;getBounds、hitTest、嵌套容器和 track matte 同步适配。
  • 资源与缓存:静态场景复用已有录制/快照缓存;工作纹理复用并计入名义字节,空闲或查询结束时释放,查询不创建快照或修改 LRU。
  • 依赖:DEPS 锁定 tgfx bbada45535585150d98b0a0d8204c484e1b143f8,集成已合入的 Fix WebGPU stencil support and texture query translation tgfx#1622。镜像可获取,并包含 main 使用的 glass 像素语义修复。

验证与证据边界

Rebase 后原生验证

启用 PAG_BUILD_TESTS=ON 的 Debug 全模块构建,Apple M3 Pro 实机串行执行两个后端:

后端 完整测试结果 截图比较
OpenGL 2852 通过,0 失败,0 跳过 8750 个唯一 key;8745 严格比较,5 个版本比较跳过
Metal 2862 通过,0 失败,1 项既有跳过 8749 个唯一 key;8744 严格比较,5 个版本比较跳过
  • Metal 跳过项为 TGFXCastTest.ForeignMetalTexturePreservesBackendTag。
  • 5 个版本比较跳过来自 main 已接受更新与本地缓存标签不一致:PAGCompareFrameTest/feature_all.pag/0291、0307,以及 PAGXTest/html/shape_glyph_run、text_box、text_writing_mode。未为此刷新基线,不能称整套截图全部严格比较。
  • 三维与资源回归共 47 项在两个后端均通过,三维截图全部严格比较。覆盖父链、多相机、透明相交、共面、3D+特效、bounds/命中/matte、resize、缓存失效及资源释放。
  • 新增 FixedDepthRangeAndClipBoundaries;编码参考、立方体实际交界像素及零 Z 缩放测试保持通过。三维基准经主动接受流程审核;基准是回归参考,不是对 AE 全部像素的正确性认证。

WebGPU 与性能验证

  • 依赖集成阶段使用独立的 25 份精确提交源码检出及全新构建目录,OpenGL/Metal 全模块构建及完整测试通过;正式 WebGPU SDK 使用 Emscripten 4.0.15 Release 编译成功。
  • 本地 Apple 硬件 WebGPU 诊断:安全定点的 10 项重点回归全部通过,包括 BoxBoundaryDepthEncoding、BoxBoundaryDepthOrder、溢出/裁剪、零 Z 缩放和透明相交;原高精度对照 10 项亦通过,无 GPU validation error。
  • 48 组颜色/深度/索引输出在重复帧及切换帧后稳定;近深度和共面压力场景的编码、图层选择与原高精度路径一致。诊断对应的三维滤镜与回归源码哈希在 rebase 前后相同,不能据此宣称 rebase 后整个 WebGPU SDK 已实机全量通过。
  • 同一硬件 GPUDevice、Release 配置、双轮反序、每配置每路径 60 个样本:1024×1024、8 层动态透明场景关闭缓存时,高精度路径中位延迟 51.9 ms → 安全定点 14.0 ms;4 层为 14.3 → 5.6 ms。计时为 CPU 提交到 GPU 完成等待,不是纯 GPU timestamp,不承诺所有设备/临界输入相同收益。
  • 不保留新增的独立 test/webgpu/ 框架。附加 Web runner/bundle 检查因本地缺 Cypress/TypeScript 依赖及 JS bundle 产物未完成;新 CI 结果以 PR 检查区为准。

真实限制与后续

  • 相机实现视图变换和 zoom;depthOfField、focusDistance、aperture、blurLevel、iris* 尚不渲染。
  • Depth peeling 最坏成本仍为 O(N²),大视口、多层动态透明内容有开销;极端范围/临界片元仍走高精度慢路径。
  • WebGPU 未完成 rebase 后整套实机重测。此前跨原生参考的两项文字截图、Camera 截图和分数视口回读断言差异仍有记录,未放宽比较消除;布局校准不保证不同字形栅格器逐像素相同。
  • Vulkan/D3D12 未进行本 PR 的实机验证,共享代码可编译不等于完整支持已经验证。
  • 带 3D 属性的图层此前可能被跳过,启用后会显示,这是用户可感知的行为变化。完整父链、非 255 透明度、bounds/命中/matte 已实现并有回归,不再列为旧描述中的未支持项。

请基于当前提交复核原阻塞项与上述验证范围;本描述不自动将原评审线程标为已解决。

@codecov-commenter

codecov-commenter commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.69043% with 204 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.71%. Comparing base (6e5418e) to head (9eb7fbd).

Files with missing lines Patch % Lines
test/src/PAGTransform3DTest.cpp 97.41% 26 Missing and 8 partials ⚠️
src/rendering/filters/Transform3DSceneFilter.cpp 84.43% 17 Missing and 16 partials ⚠️
src/rendering/filters/Transform3DFilter.cpp 89.41% 12 Missing and 17 partials ⚠️
src/rendering/graphics/Transform3DScene.cpp 80.27% 19 Missing and 10 partials ⚠️
src/rendering/renderers/FilterRenderer.cpp 41.02% 13 Missing and 10 partials ⚠️
src/rendering/PAGPlayer.cpp 57.14% 4 Missing and 8 partials ⚠️
src/rendering/layers/PAGComposition.cpp 86.51% 4 Missing and 8 partials ⚠️
src/rendering/caches/LayerCache.cpp 46.66% 5 Missing and 3 partials ⚠️
src/rendering/filters/utils/Filter3DFactory.cpp 80.95% 4 Missing and 4 partials ⚠️
src/rendering/renderers/CompositionRenderer.cpp 61.53% 3 Missing and 2 partials ⚠️
... and 6 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3815      +/-   ##
==========================================
+ Coverage   83.34%   83.71%   +0.37%     
==========================================
  Files         754      762       +8     
  Lines      111162   113586    +2424     
  Branches    31182    31607     +425     
==========================================
+ Hits        92648    95094    +2446     
+ Misses      11315    11230      -85     
- Partials     7199     7262      +63     

☔ 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.

}

std::vector<tgfx::BindingEntry> Transform3DFilter::uniformBlocks() const {
return {{"VertexUniforms", 0}, {"FragmentUniforms", 1}};

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.

uniformBlocks 未指定 ShaderVisibility,默认 VertexFragment。tgfx 的 ResolveUniformSlots 要求每个 block 在 visibility 覆盖的每个 stage 都存在(VaryingShaderModule.h:141-158),而 VertexUniforms 只在顶点着色器、FragmentUniforms 只在片元着色器,因此 Metal/WebGPU/Vulkan/D3D12 上 pipeline 会被直接拒绝,3D 图层在这些后端完全不渲染。GL 按名绑定不看 visibility,所以现有测试只覆盖了 GL。建议为两个 block 分别指定 Vertex / Fragment 可见性(参考 MotionBlurFilter.cpp:143-144)。

}

void Transform3DFilter::onConfigurePipeline(tgfx::RenderPipelineDescriptor* descriptor) const {
descriptor->depthStencil.depthCompare = tgfx::CompareFunction::GreaterEqual;

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.

onConfigurePipeline 未设置 depthStencil.format(默认 Unknown)。Metal 只在 format 非 Unknown 时设置 depthAttachmentPixelFormat,WebGPU 则整体跳过 depthStencilState,而本滤镜的 render pass 挂了 DEPTH24_STENCIL8 深度附件,pipeline 与 pass 不匹配(参见 tgfx StandardDrawOp.cpp:49-56 的同款注释)。建议补 descriptor->depthStencil.format = tgfx::PixelFormat::DEPTH24_STENCIL8。

auto isFirstLayerInFrame = prepareFrameState(transform3DResources, state);
auto loadAction = isFirstLayerInFrame ? tgfx::LoadAction::Clear : tgfx::LoadAction::Load;
renderPassDesc->depthStencilAttachment = tgfx::DepthStencilAttachment(
state->depthTexture, loadAction, tgfx::StoreAction::Store, -1.0f, false);

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.

clearDepth 传 -1.0f 超出 [0,1]:GL 会钳到 0(所以 GL 上恰好正确),WebGPU 会校验失败、Metal 同样要求 [0,1],tgfx 各后端均原样透传。另外这里按 GL 的 NDC z∈[-1,1] 编码深度,而 Metal/WebGPU 的裁剪空间是 z∈[0,w],整片 quad 会被近平面裁掉(默认相机下 ndc_z≈-0.81)。建议投影输出 z∈[0,1](或顶点着色器做 z=(z+w)*0.5),clear 值改为与 GreaterEqual 自洽的 0.0f。

Comment on lines +64 to +295
std::shared_ptr<tgfx::Image> Transform3DFilter::Apply(
const std::shared_ptr<tgfx::Image>& input, RenderCache* cache, Layer* layer, Frame layerFrame,
const tgfx::Rect& contentBounds, const tgfx::Point& sourceScale, tgfx::Point* offset) {
auto transform3D = layer->transform3D;
Transform3D* cameraTransform = nullptr;
CameraOption* cameraOption = nullptr;
Transform3D* parentTransform3D = nullptr;
Transform2D* parentTransform2D = nullptr;

if (layer->parent) {
if (layer->parent->transform3D) {
parentTransform3D = layer->parent->transform3D;
} else {
parentTransform2D = layer->parent->transform;
}
}
auto containingComposition = layer->containingComposition;
for (auto aLayer : containingComposition->layers) {
if (aLayer->type() == LayerType::Camera) {
auto cameraLayer = static_cast<CameraLayer*>(aLayer);
cameraTransform = cameraLayer->transform3D;
cameraOption = cameraLayer->cameraOption;
break;
}
}
Point3D position = {};
if (transform3D->position) {
position = transform3D->position->getValueAt(layerFrame);
} else {
float xPosition = transform3D->xPosition->getValueAt(layerFrame);
float yPosition = transform3D->yPosition->getValueAt(layerFrame);
float zPosition = transform3D->zPosition->getValueAt(layerFrame);
position = Point3D::Make(xPosition, yPosition, zPosition);
}
auto anchorPoint = transform3D->anchorPoint->getValueAt(layerFrame);
auto scale = transform3D->scale->getValueAt(layerFrame);
auto orientation = transform3D->orientation->getValueAt(layerFrame);
auto xRotation = transform3D->xRotation->getValueAt(layerFrame);
auto yRotation = transform3D->yRotation->getValueAt(layerFrame);
auto zRotation = transform3D->zRotation->getValueAt(layerFrame);
auto opacity = transform3D->opacity->getValueAt(layerFrame);

float cameraZoom;
if (cameraOption) {
cameraZoom = cameraOption->zoom->getValueAt(layerFrame);
} else {
cameraZoom = 1000.f;
}
auto targetWidth = ceilf(static_cast<float>(containingComposition->width) * sourceScale.x);
auto targetHeight = ceilf(static_cast<float>(containingComposition->height) * sourceScale.y);
auto aspectScale = static_cast<float>(input->width()) / targetWidth;
auto sourceAspectScaleMatrix = Matrix3D::Scale(
1.0, static_cast<float>(input->height()) / static_cast<float>(input->width()));
auto targetAspectScaleMatrix = Matrix3D::Scale(1.0, targetHeight / targetWidth);
auto aspectScaleMatrix = Matrix3D::Scale(aspectScale, aspectScale);
sourceAspectScaleMatrix.postConcat(aspectScaleMatrix);
Matrix3D invertTargetAspectScaleMatrix;
targetAspectScaleMatrix.invert(&invertTargetAspectScaleMatrix);

auto scalar = targetWidth / sourceScale.x;
auto ratio = targetHeight / targetWidth;
auto sourceBounds = contentBounds;
sourceBounds.scale(sourceScale.x, sourceScale.y);
sourceBounds.roundOut();
auto sourceOrigin =
tgfx::Point::Make(sourceBounds.x() / sourceScale.x, sourceBounds.y() / sourceScale.y);

Matrix3D modelMatrix = {};
modelMatrix.postTranslate(1.0, 1.0);
modelMatrix.postConcat(sourceAspectScaleMatrix);
modelMatrix.postConcat(invertTargetAspectScaleMatrix);
modelMatrix.postTranslate((-anchorPoint.x + sourceOrigin.x) / scalar * 2.0f,
(-anchorPoint.y + sourceOrigin.y) / (scalar * ratio) * 2.0f,
anchorPoint.z / scalar * 2.0f);
modelMatrix.postConcat(targetAspectScaleMatrix);
auto scaleMatrix = Matrix3D::Scale(scale.x, scale.y, scale.z);
modelMatrix.postConcat(scaleMatrix);
auto xOMatrix = Matrix3D::Rotate({1.0, 0.0, 0.0}, DegreesToRadians(-orientation.x));
auto yOMatrix = Matrix3D::Rotate({0.0, 1.0, 0.0}, DegreesToRadians(-orientation.y));
auto zOMatrix = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(orientation.z));
auto xRMatrix = Matrix3D::Rotate({1.0, 0.0, 0.0}, DegreesToRadians(-xRotation));
auto yRMatrix = Matrix3D::Rotate({0.0, 1.0, 0.0}, DegreesToRadians(-yRotation));
auto zRMatrix = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(zRotation));
modelMatrix.postConcat(zRMatrix).postConcat(yRMatrix).postConcat(xRMatrix);
modelMatrix.postConcat(zOMatrix).postConcat(yOMatrix).postConcat(xOMatrix);
modelMatrix.postConcat(invertTargetAspectScaleMatrix);
modelMatrix.postTranslate(position.x / scalar * 2.0f, position.y / (scalar * ratio) * 2.0f,
-position.z / scalar * 2.0f);
modelMatrix.postTranslate(-1.0, -1.0);

if (parentTransform3D != nullptr) {
Point3D positionP = {};
if (parentTransform3D->position) {
positionP = parentTransform3D->position->getValueAt(layerFrame);
} else {
float xPosition = parentTransform3D->xPosition->getValueAt(layerFrame);
float yPosition = parentTransform3D->yPosition->getValueAt(layerFrame);
float zPosition = parentTransform3D->zPosition->getValueAt(layerFrame);
positionP = Point3D::Make(xPosition, yPosition, zPosition);
}
auto anchorPointP = parentTransform3D->anchorPoint->getValueAt(layerFrame);
auto scaleP = parentTransform3D->scale->getValueAt(layerFrame);
auto orientationP = parentTransform3D->orientation->getValueAt(layerFrame);
auto xRotationP = parentTransform3D->xRotation->getValueAt(layerFrame);
auto yRotationP = parentTransform3D->yRotation->getValueAt(layerFrame);
auto zRotationP = parentTransform3D->zRotation->getValueAt(layerFrame);

auto parentMatrix = Matrix3D();
parentMatrix.postTranslate(1.0, 1.0);
parentMatrix.postTranslate(-anchorPointP.x / scalar * 2.0f,
-anchorPointP.y / (scalar * ratio) * 2.0f,
anchorPointP.z / scalar * 2.0f);
parentMatrix.postConcat(targetAspectScaleMatrix);
auto scaleMatrixP = Matrix3D::Scale(scaleP.x, scaleP.y, scaleP.z);
parentMatrix.postConcat(scaleMatrixP);
auto xOMatrixP = Matrix3D::Rotate({1.0, 0.0, 0.0}, DegreesToRadians(-orientationP.x));
auto yOMatrixP = Matrix3D::Rotate({0.0, 1.0, 0.0}, DegreesToRadians(-orientationP.y));
auto zOMatrixP = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(orientationP.z));
auto xRMatrixP = Matrix3D::Rotate({1.0, 0.0, 0.0}, DegreesToRadians(-xRotationP));
auto yRMatrixP = Matrix3D::Rotate({0.0, 1.0, 0.0}, DegreesToRadians(-yRotationP));
auto zRMatrixP = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(zRotationP));
parentMatrix.postConcat(zRMatrixP).postConcat(yRMatrixP).postConcat(xRMatrixP);
parentMatrix.postConcat(zOMatrixP).postConcat(yOMatrixP).postConcat(xOMatrixP);
parentMatrix.postConcat(invertTargetAspectScaleMatrix);
parentMatrix.postTranslate(positionP.x / scalar * 2.0f, positionP.y / (scalar * ratio) * 2.0f,
-positionP.z / scalar * 2.0f);
parentMatrix.postTranslate(-1.0, -1.0);

modelMatrix.postConcat(parentMatrix);
} else if (parentTransform2D != nullptr) {
Point positionP = {};
if (parentTransform2D->position) {
positionP = parentTransform2D->position->getValueAt(layerFrame);
} else {
float xPosition = parentTransform2D->xPosition->getValueAt(layerFrame);
float yPosition = parentTransform2D->yPosition->getValueAt(layerFrame);
positionP = Point::Make(xPosition, yPosition);
}
auto anchorPointP = parentTransform2D->anchorPoint->getValueAt(layerFrame);
auto scaleP = parentTransform2D->scale->getValueAt(layerFrame);
auto rotationP = parentTransform2D->rotation->getValueAt(layerFrame);

auto parentMatrix = Matrix3D();
parentMatrix.postTranslate(1.0, 1.0);
parentMatrix.postTranslate(-anchorPointP.x / scalar * 2.0f,
-anchorPointP.y / (scalar * ratio) * 2.0f, 0.0f);
parentMatrix.postConcat(targetAspectScaleMatrix);
auto scaleMatrixP = Matrix3D::Scale(scaleP.x, scaleP.y, 1.0f);
parentMatrix.postConcat(scaleMatrixP);
auto zRMatrixP = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(rotationP));
parentMatrix.postConcat(zRMatrixP);
parentMatrix.postConcat(invertTargetAspectScaleMatrix);
parentMatrix.postTranslate(positionP.x / scalar * 2.0f, positionP.y / (scalar * ratio) * 2.0f,
0.0f);
parentMatrix.postTranslate(-1.0, -1.0);

modelMatrix.postConcat(parentMatrix);
}

float cameraFov = atanf(0.5f * scalar / cameraZoom) * 2.0f;
Vec3 cameraEye = {0.0f, 0.0f, 0.0f};
Vec3 cameraCoa = {0.0f, 0.0f, 0.0f};
Vec3 cameraUp = {0.0f, 1.0f, 0.0f};

Matrix3D viewMatrix = {};
if (cameraTransform) {
Point3D cameraPosition;
Vec3 cameraTransformPosition;
if (cameraTransform->position) {
cameraPosition = cameraTransform->position->getValueAt(layerFrame);

} else {
cameraPosition.x = cameraTransform->xPosition->getValueAt(layerFrame);
cameraPosition.y = cameraTransform->yPosition->getValueAt(layerFrame);
cameraPosition.z = cameraTransform->zPosition->getValueAt(layerFrame);
}

auto transZ =
1.0f * -cameraPosition.z / (scalar / 2.0f) + (cameraPosition.z > 0.0f ? 1.0f : -1.0f);
cameraTransformPosition = {cameraPosition.x / scalar * 2.0f - 1.0f,
cameraPosition.y / (scalar * ratio) * 2.0f - 1.0f, transZ};

cameraEye += cameraTransformPosition;

auto cOrientation = cameraTransform->orientation->getValueAt(layerFrame);
auto cXRotation = cameraTransform->xRotation->getValueAt(layerFrame);
auto cYRotation = cameraTransform->yRotation->getValueAt(layerFrame);
auto cZRotation = cameraTransform->zRotation->getValueAt(layerFrame);

if (cameraTransform->anchorPoint) {
auto cameraPointOfInterest = cameraTransform->anchorPoint->getValueAt(layerFrame);
Vec3 cameraTransformPOI = {cameraPointOfInterest.x / scalar * 2.0f - 1.0f,
cameraPointOfInterest.y / (scalar * ratio) * 2.0f - 1.0f, 0.0f};

cameraCoa += cameraTransformPOI;
}

viewMatrix = Matrix3D::LookAt(cameraEye, cameraCoa, cameraUp);
viewMatrix.postConcat(targetAspectScaleMatrix);
viewMatrix.postTranslate(0.0f, 0.0f, -1.0f);
auto cXOMatrix = Matrix3D::Rotate({1.0, 0.0, 0.0}, DegreesToRadians(cOrientation.x));
auto cYOMatrix = Matrix3D::Rotate({0.0, 1.0, 0.0}, DegreesToRadians(cOrientation.y));
auto cZOMatrix = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(-cOrientation.z));
auto cXRMatrix = Matrix3D::Rotate({1.0, 0.0, 0.0}, DegreesToRadians(cXRotation));
auto cYRMatrix = Matrix3D::Rotate({0.0, 1.0, 0.0}, DegreesToRadians(cYRotation));
auto cZRMatrix = Matrix3D::Rotate({0.0, 0.0, 1.0}, DegreesToRadians(-cZRotation));
viewMatrix.postConcat(cXOMatrix).postConcat(cYOMatrix).postConcat(cZOMatrix);
viewMatrix.postConcat(cXRMatrix).postConcat(cYRMatrix).postConcat(cZRMatrix);
viewMatrix.postTranslate(0.0f, 0.0f, 1.0f);
viewMatrix.postConcat(invertTargetAspectScaleMatrix);
} else {
cameraEye += {0.0f, 0.0f, 2.0f * cameraZoom / scalar - 1.0f};
viewMatrix = Matrix3D::LookAt(cameraEye, cameraCoa, cameraUp);
}

float zNear = -0.25f;
float zFar = 100.0f;
Matrix3D projectionMatrix = Matrix3D::Perspective(zNear, zFar, cameraFov);
auto finalMatrix = modelMatrix;
finalMatrix.postConcat(viewMatrix);
finalMatrix.postConcat(projectionMatrix);

auto filter = std::make_shared<Transform3DFilter>(
cache, containingComposition->uniqueID, layer->id, static_cast<int>(targetWidth),
static_cast<int>(targetHeight), opacity, finalMatrix);
auto result = input->makeWithFilter(tgfx::ImageFilter::Runtime(filter));
if (offset) {
// Cancel the scaled, rounded input origin set by CreatePictureImage().
offset->offset(-sourceBounds.x(), -sourceBounds.y());
}
return result;
}

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.

Apply 共 232 行,远超 80 行约定,且同时承担 7 项职责:查父层/相机、采样 8 个属性、构建本层/父 3D/父 2D 三段矩阵、view/projection、创建 filter 与修 offset。scalar/ratio/sourceOrigin 在 4 段间隐式传递,改任一矩阵顺序都只能整体重审。建议拆为 SampleTransform / BuildTransformMatrix / BuildViewMatrix / BuildProjectionMatrix,Apply 只做编排。

auto result = input->makeWithFilter(tgfx::ImageFilter::Runtime(filter));
if (offset) {
// Cancel the scaled, rounded input origin set by CreatePictureImage().
offset->offset(-sourceBounds.x(), -sourceBounds.y());

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.

这里用 offset->offset() 在上一阶段的残留值上累加,而 FilterRenderer::ApplyFilters 在 313/320 行会对同一个 offset 变量各累加一次;ApplyEffects 与 ApplyMotionBlur 入口都会先 set(0,0),只有 3D 分支没有。结果是图层同时有 3D 与位移类特效(CornerPin/MotionTile 等 filterBounds 原点非零)时最终偏移变成 2E+D,整层错位。建议 3D 分支先 offset->set(0,0),并改用 makeWithFilter(Runtime(filter), offset) 覆盖写。

Transform3D* parentTransform3D = nullptr;
Transform2D* parentTransform2D = nullptr;

if (layer->parent) {

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.

只取直接父层,而 2D 路径 TransformCache::createCache(TransformCache.cpp:53-59)是 while 遍历整条父链,多级父子链下祖父层的位移/旋转/缩放会被静默丢弃。另外 TransformCache.cpp:51-53 在 layer->transform 为空时直接返回单位矩阵,导致 3D 父层下的 2D 子层既丢失父层 3D 变换、也不进入 depth pass。建议沿 parent 递归累乘,或在已知限制中明确该语义。


void Transform3DFilter::onConfigurePipeline(tgfx::RenderPipelineDescriptor* descriptor) const {
descriptor->depthStencil.depthCompare = tgfx::CompareFunction::GreaterEqual;
descriptor->depthStencil.depthWriteEnabled = true;

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.

深度写入对所有 alpha>0 的片元生效(shader 仅在 a<=0 时 discard)。每个 3D 层各自渲染到独立 color target,深度只用于剔除片元;当近层 opacity<1 或存在抗锯齿软边时,它会写深度并整片剔除后面的远层,导致远层消失、重叠区无法透过近层正确合成。建议按深度排序后只比较不写深度,或仅对 alpha 超阈值片元写深度,并补 opacity 非 255 的用例。

if (filterList->layer->transform3D) {
auto oldBounds = *filterBounds;
auto containingComposition = filterList->layer->containingComposition;
*filterBounds = tgfx::Rect::MakeWH(containingComposition->width, containingComposition->height);

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.

这里把 3D 层输出扩到整幅 composition,但测量侧没有同步:FilterRenderer::MeasureFilterBounds(FilterRenderer.cpp:143-157)没有 3D 分支,LayerRenderer::MeasureLayerBounds 用单位矩阵映射 3D 层。结果 PAGComposition/PAGLayer 的 getBounds 偏小、getLayersUnderPoint 命中错位,PAGComposition.cpp:481-489 的 track matte 相交还可能把 3D 层裁成空。建议测量阶段对 3D 层同样返回 composition 矩形。

}
tgfx::TextureDescriptor descriptor(width, height, tgfx::PixelFormat::DEPTH24_STENCIL8, false, 1,
tgfx::TextureUsage::RENDER_ATTACHMENT);
state.depthTexture = gpu->createTexture(descriptor);

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.

深度纹理尺寸取自该层 contentScale,同 composition 内两层尺寸不同时会在这里每层重建一次;但重建只更新了尺寸,没有重置 frameInitialized/frameSequence,随后 prepareFrameState 仍判定本帧非首层并走 LoadAction::Load,对未初始化纹理做 Load。建议尺寸只由 composition 决定,或重建时强制 Clear。

}
}
auto containingComposition = layer->containingComposition;
for (auto aLayer : containingComposition->layers) {

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.

取图层列表里第一个 Camera 后直接 break:不判断 visibleAt、不判断 startTime/duration,多相机时固定取最底层;AE 语义是当前时间区间内的活动相机。该扫描还在每层每帧重复执行。建议按时间区间与可见性筛选,并缓存到 CompositionState。

modelMatrix.postTranslate(-1.0, -1.0);

if (parentTransform3D != nullptr) {
Point3D positionP = {};

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.

position 解析(89-97、155-163、194-201、230-239)重复 4 次且写法不一致;矩阵构建(131-152、171-190、206-218)重复 3 段,父 3D 块与本层块只差 sourceAspectScaleMatrix/sourceOrigin。建议抽 SamplePosition(Transform3D/Transform2D) 与 BuildTransformMatrix。

Comment thread src/rendering/filters/utils/Matrix3D.h Outdated
* Matrix3D is a 4x4 matrix stored in column-major order. It assumes a right-handed coordinate
* system where +X goes to the right, +Y goes down and +Z goes into the screen.
*/
class Matrix3D {

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.

tgfx 已有 tgfx::Matrix3D(include/tgfx/core/Matrix3D.h)与 tgfx::Vec3:getColumnMajor/postConcat/LookAt/invert/Scale/Rotate/postTranslate 语义等价(postConcat 同为 setConcat(m,*this),invert 同一余子式算法与阈值)。这里相当于新增第三套实现,违反“复用已有功能”的原则。建议复用 tgfx,仅保留 PAG 特有投影;即便保留,也应放 src/base/utils/ 而非 filters/utils/。

if (resources == nullptr) {
return;
}
struct VertexUniforms {

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.

uniform 结构体没有 alignas(16) / static_assert(HasStd140UniformLayout) / offsetof 校验,FragmentUniforms 用 float padding[3] 手写补齐。项目已有 Std140Uniforms.h,MotionTile/BrightnessContrast/Bulge 等 7 处都按该模式校验,建议对齐,避免成员增删时静默破坏 std140 布局。

} else {
cameraZoom = 1000.f;
}
auto targetWidth = ceilf(static_cast<float>(containingComposition->width) * sourceScale.x);

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.

3D 层的 scaleFactorLimit 是 FLT_MAX(FilterRenderer.cpp:42-48),这里 ceilf 后又在 287 行 static_cast,没有有限性与上限校验;Composition::verify 只校验宽高大于 0。超大合成或高倍 zoom 下 float 转 int 越界是 UB,且深度/颜色纹理都按该尺寸申请。建议 clamp 到 GPU 上限并在超限时回退。

float halfAngle = angle * 0.5f;
float cot = cosf(halfAngle) / sinf(halfAngle);

Matrix3D result = {};

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.

Matrix3D result = {} 走默认构造得到单位阵,只覆盖 m00/m11/m22/m23/m32,m33 仍为 1(标准透视应为 0)。当前靠 zNear=-0.25 与相机 eye.z=2*zoom/scalar-1 三者互相抵消才得到恒等投影,改任一处都会整体错位,而注释仍是通用描述。建议显式设置 m33 并注释推导,或改为标准约定后在顶点着色器做 NDC 适配。


float cameraZoom;
if (cameraOption) {
cameraZoom = cameraOption->zoom->getValueAt(layerFrame);

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.

cameraZoom 未校验非零/有限:zoom 为 0 时 fov 约等于 π、cot 约等于 0,整层压成一条线;zoom 为 NaN/Inf 时 finalMatrix 为 NaN 并直接上传 GPU(全程无 FloatsAreFinite 检查)。CameraOption::verify 只校验指针非空。建议非法时回退默认值,并对 finalMatrix 做有限性校验。


namespace pag {

struct Transform3DResources : public FilterResources {

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.

其余中低优先级问题建议本 PR 一并处理:(1)Has3DSupport() 恒 true 后 LayerCache.cpp:135 的判断成为死代码,且失去后端降级开关;(2)内部头 include pag/pag.h 公共伞头,Transform3DResources 暴露在 pag 命名空间;(3)Apply 注释称 Returns nullptr,但实现从不返回 nullptr,失败时会被当 2D 未变换绘制;(4)LookAt 在 eye==center 时静默 setIdentity;(5)用文件里的 layer->id(可重复、缺省为 0)推断 pass 边界;(6)死代码 Matrix3D::setScale、Vec3::operator+/operator-;(7)大量 1.0/0.0 double 字面量;(8)3D 层永久绕过 filter 缓存(ContentCache.cpp:69),静止场景每帧全量重绘;(9)每层一次整幅 pass 且裁剪分支每帧新建整幅纹理,相机矩阵每层重算;(10)测试覆盖不足(父子链、多相机、透明度、3D+特效、bounds/hitTest 未覆盖),Matrix3D 差分测试建议入库。

@shlzxjp shlzxjp 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.

评审结论:当前不建议合入

本次评审共提出 17 条行级意见(P0×3、P1×5、P2×8、汇总×1),针对 61d320a0,均已在二次确认后逐条复核。核心判断:该 PR 对外承诺"支持 3D 图层渲染",但当前实现只在 OpenGL 后端成立,且存在会输出错误画面的缺陷与违反项目硬性规范的实现。

阻塞项(必须修)

  1. Transform3DFilter.cpp:355 — uniformBlocks 未声明 ShaderVisibility,tgfx 的 ResolveUniformSlots 会直接 reject pipeline,3D 在 Metal/WebGPU/Vulkan/D3D12 上完全不渲染(GL 按名绑定不看 visibility,所以现有测试只覆盖了 GL)。
  2. Transform3DFilter.cpp:429 — 未设置 depthStencil.format,pipeline 与 DEPTH24_STENCIL8 深度附件不匹配。
  3. Transform3DFilter.cpp:450 + Matrix3D.cpp:159 — 深度按 GL 的 NDC z∈[-1,1] 编码,且 clearDepth = -1;Metal/WebGPU 裁剪空间为 z∈[0,w],整片 quad 会被近平面裁掉。
  4. Transform3DFilter.cpp:292 — offset 在上一阶段残值上累加,FilterRenderer::ApplyFilters 又各累加一次;3D 层叠加 CornerPin/MotionTile 等特效时最终偏移为 2E+D,整层错位(属错误输出,非"未支持")。
  5. Transform3DFilter.cpp:64-295 — Apply 232 行,违反"函数 ≤ 80 行"规范,且同时承担 7 项职责。

合入前最小清单

  • 修复上述 5 项;
  • Metal 与 WebGPU 各跑一条 3D 用例并把结果贴到 PR(当前 workflow 不执行任何 PAGFullTest,Metal lane 仅编译,CI 绿不构成验证);
  • rebase 到最新 main,并将 DEPS bump 到 tgfx bbada455 或更新 —— tgfx#1622 的 stencilAttachmentSupported 修复已合并,但本 PR 的 tgfx pin 落后主干 12 个提交,libpag main 也落后 2 个,两者都还不包含该修复;
  • 在 PR 描述中补齐真实已知限制:只处理直接父层(含"3D 父层下的 2D 子层"语义)、opacity != 255 与软边的遮挡、getBounds/hitTest/track matte 未适配、非 GL 后端不生效。

补充说明

  • 现有 5 个截图基线由本实现自身生成,只能证明无回归,不能证明正确性;建议至少在第二个后端复现同一画面。
  • 建议将 Has3DSupport() 改为按后端能力返回(isFormatRenderable(DEPTH24_STENCIL8) + 深度附件支持),而非恒 true,避免在未支持的后端声明支持;这样非 GL 平台行为与当前一致,也不会误导使用者。

其余 P2/P3 项(与 tgfx Matrix3D/Vec3 重复、std140 断言、相机选择、深度纹理重建与回收、性能、补充单测)建议后续迭代处理,不阻塞本 PR。

@CodeJhF
CodeJhF force-pushed the feature/markffan_transform_3d branch from db82f32 to b57125a Compare November 11, 2026 09:16
Comment thread include/pag/pag.h Outdated

private:
VectorComposition* emptyComposition = nullptr;
std::shared_ptr<Graphic> cached3DGraphic = nullptr;

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.

这里的缓存被放进了公共头 include/pag/pag.h,会给 PAG_API PAGComposition 增加两个数据成员,改变 sizeof,对按旧头编译、动态链接 libpag 的宿主构成 ABI 破坏;同时把渲染缓存语义带进了公共接口。建议把 cached3DGraphic / cached3DContentVersion 移到 .cpp 侧(例如按 PAGComposition 指针索引的表,随对象析构清理),公共头只保留既有成员;若确实要改布局,请在 release note 中明确标注 ABI 变更。

auto viewportScaleX = targetWidth / (static_cast<double>(width) * scale);
auto viewportScaleY = targetHeight / (static_cast<double>(height) * scale);
for (const auto& layer : layers) {
auto image = MakeSource(layer.graphic, cache, targetWidth, targetHeight, scale);

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.

3D 场景的显存没有预算约束:Transform3DSceneFilter 固定持有 8 张 RGBA + 1 张深度(约 36 B/px,1080p 约 74MB),这里又会为每个 3D 层再生成一张全幅中间图,images 同时持有 N 张全幅纹理。Clamp3DScale 只按 maxTextureDimension2D 限幅、不看显存,4K 合成乘 2 倍缩放会到 GB 级;prepareTextures 分配失败后整帧 3D 直接消失且无日志。建议联动 MAX_GRAPHICS_MEMORY 设显存预算、超限时降采样或分批合成,并在失败路径打日志。

value.mode = static_cast<uint32_t>(blendModes[index]);
value.flags |= pass == 0 ? 1 : 0;
value.output = output;
auto buffer = MakeUniformBuffer(gpu, 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.

每次场景绘制都会新建 2 次 peel 乘 3 个输出乘 N 层,共 6N 个 uniform buffer,再加 1 个 vertex buffer;配合 drawPeel 每层 3 个全屏 render pass(含混合与拷贝共 4N+1 个 pass),代价随图层数线性增长。建议合并为一个大 UBO(用偏移索引)并跨帧复用这些 buffer,而不是每帧重新分配。

}
}
Transform3DSceneBuilder scene(_width, _height);
for (auto& childLayer : layers) {

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.

这段改造让所有合成(包括完全没有 3D 层的纯 2D 文件)都变成每个子层单独 Recorder 再 MakeCompose。这是 3D 分批所必需的,但改变了全部 PAG 文件的录制与绘制结构,可能带来 2D 场景的性能与合批回归。建议在无 3D 子层时保留原来的直录路径,并用一个 2D 大文件做帧耗时基准对比。

}
CameraLayer* camera = nullptr;
Frame frame = 0;
for (auto item = parent->layers.rbegin(); item != parent->layers.rend(); ++item) {

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.

相机选择存在两套实现:Transform3DFilter::MakeContext(Transform3DFilter.cpp:210)正序遍历取第一个并判 isActive,这里逆序遍历取第一个并判 layerVisible/frameVisible。多个相机同时激活时,绘制路径与 bounds/hitTest 路径可能选出不同相机,导致包围盒与命中结果和画面不一致。建议统一到一处(AE 语义通常是时间区间内的顶层相机),并补多相机用例。

namespace {

// Q32 depth codes avoid software binary64 arithmetic except near uncertain boundaries.
static constexpr char PEEL_SHADER[] = R"(

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.

这里的深度比较在片元着色器里用软件方式模拟 binary64(约 200 行 uvec 位运算加 while 循环),每个像素要执行多次 64 位加法和比较,且依赖 highp int/float(部分移动端 fragment 的 highp 不保证)。功能上能保证共面与相邻平面的排序精度,但低端 GPU 上有正确性与性能双重风险。建议在低端 Android 真机上补帧耗时与视觉验证,并优先走定点快路径(uFlags 的第 2 位)。

}

bool hitTest(RenderCache* cache, float x, float y) override {
auto surface = tgfx::Surface::Make(cache->getContext(), 1, 1);

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.

hitTest 为读 1 个像素创建 1x1 surface,但仍会走完整场景绘制:分配 9 张全幅场景纹理和 N 张图层中间图,跑 4N+1 个全屏 pass,再回读 1 像素。像素级命中测试在 3D 图层上开销会非常明显。建议命中测试走几何路径(ProjectedMatrix 反变换加图层内容命中,GetChildLayerAtPoint 已这么做),仅在必要时才回退到绘制回读。

croppedMatrix.postScale(width / targetWidth, height / targetHeight, 1);
croppedMatrix.postTranslate((width + 2 * offset.x) / targetWidth - 1,
(height + 2 * offset.y) / targetHeight - 1, 0);
#ifdef TGFX_USE_WEBGPU

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.

后端差异以 ifdef TGFX_USE_WEBGPU 的形式埋进了渲染数学(这里与 Transform3DSceneFilter.cpp:584 各一处),同一份代码在不同编译配置下走不同的 Y 轴约定;如果将来某个构建同时启用多个后端会直接失效。建议把 Y 轴约定收敛到 tgfx 的 origin 处理(例如复用 ToVertexPoint/ToTexturePoint)或集中封装成一个工具函数,避免散落在两处矩阵与顶点计算里。

…omposition scene cache off the public header.
…ownsample instead of risking gigabyte level usage.
@CodeJhF
CodeJhF force-pushed the feature/markffan_transform_3d branch from cc76274 to 3a7b641 Compare November 16, 2026 11:22
Comment thread src/rendering/caches/RenderCache.h Outdated
size_t memoryUsage() const {
return graphicsMemory;
}
/** 返回快照和滤镜直接持有资源的名义字节总数,不含 Context 的资源缓存。 */

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.

注释都使用英文

@shlzxjp
shlzxjp merged commit e2cac80 into main Nov 16, 2026
12 checks passed
@shlzxjp
shlzxjp deleted the feature/markffan_transform_3d branch November 16, 2026 12:42
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.

3 participants