Add 3D rendering context support with depth occlusion for layers. #1098

StarryThrone · 2025-12-09T12:44:26Z

主要功能

3D 变换支持：Layer 新增 matrix3D() 和 setMatrix3D() 接口，支持完整的 4x4 矩阵变换
TransformStyle 属性：新增 transformStyle() 属性，支持 Flat 和 Preserve3D 两种模式
深度排序：实现 BSP 树算法进行 3D 多边形深度排序，正确处理相交面的渲染顺序
3D 合成器：新增 Context3DCompositor 处理 3D 渲染上下文的最终合成，支持多边形分割和边缘抗锯齿

技术实现

新增 BspTree 类实现二叉空间分割树，用于 3D 多边形深度排序
新增 DrawPolygon3D 类表示 3D 渲染上下文中的绘制多边形
新增 Quads3DDrawOp 和 QuadPerEdgeAA3DGeometryProcessor 支持带边缘 AA 的 3D 四边形绘制
扩展 Matrix3D 类，增加 project()、getRow()、setRow() 等方法
重构 Layer 绘制流程，支持 3D 渲染上下文的创建、传播和合成

…ering context.

…ext.

# Conflicts: # include/tgfx/layers/Layer.h # src/gpu/DrawingManager.cpp # src/layers/Layer.cpp # test/baseline/version.json

…e current layer.

…semi-transparent problem when the layer is too close to the observer.

…layer.

…and uses the Canvas to calculate the cropping area.

…D compositor.

Hparty · 2025-12-12T08:12:28Z

include/tgfx/layers/Layer.h

-      const DrawArgs& args, Canvas* canvas, float alpha,
-      const LayerStyleSource* layerStyleSource = nullptr, const Layer* stopChild = nullptr,
-      const std::unordered_set<LayerStyleExtraSourceType>& styleExtraSourceTypes = {});
+  void drawByStarting3DContext(const DrawArgs& args, Canvas* canvas, float alpha,


建议把Preserve3d流程直接写在drawOffscreen和drawDirectly里。目前看来，Preserve3d就是把child和content的绘制目标从2d变成3d空间。在drawOffscreen里，其实是把离屏的纹理画在3d空间，而drawDirectly里，是把内容和子项都一个个画在3d空间里

Layer的3D空间看起来可以让parent直接提供，这样layer也不需要处理创建3d空间的行为，只需要处理有/无3d空间的绘制流程。
对于layer来说，如果child开了3d空间，如果args存在3d空间，那直接传给child就可以，如果args不存在3d空间，则创建一个3d空间给child

已经修改。

Hparty · 2025-12-12T08:18:07Z

include/tgfx/layers/Layer.h

+   */
+  Matrix3D calculate3DContextDepthMatrix();
+
+  bool canExtend3DContext() const;


由于alpha、blendmode是由parent传下来的，因此没法在updateRenderBounds里直接判断。建议如果本身在3d空间内了，舍弃GroupAlpha和blendmode的行为，仍然执行drawDirectly。这样可以保证updateRenderBounds和draw的rect是一致的

已经修改。

…ation.

Hparty · 2026-01-08T12:40:36Z

src/layers/Layer.cpp

+    if (canPreserve3D() || child->canPreserve3D()) {
+      // Child is inside a 3D rendering context.
+      childTransformer = RegionTransformer::MakeFromMatrix3D(childMatrix, transformer);
+    } else if (IsMatrix3DAffine(childMatrix)) {


这个用child.bitfield就能判断了吧

已经修改。

Hparty · 2026-01-08T12:49:10Z

src/layers/Render3DContext.cpp

+  newTransform.postConcat(baseTransform);
+  _stateStack.push({});
+  _stateStack.top().transform = newTransform;
+  _stateStack.top().antialiasing = antialiasing;


这里组装好再push吧···

已经修改。

Hparty · 2026-01-08T12:49:37Z

src/layers/compositing3d/Render3DContext.cpp

+  bounds.roundOut();
+  auto matrix = Matrix::MakeTrans(-bounds.x(), -bounds.y());
+  auto image = Image::MakeFrom(std::move(picture), FloatCeilToInt(bounds.width()),
+                               FloatCeilToInt(bounds.height()), &matrix, std::move(colorSpace));


roundOut就不用ceil了

已经修改。

…nds handling.

…aptation.

…D_context

domchen · 2026-01-09T08:19:17Z

include/tgfx/layers/Layer.h

+   * These features require projecting child layers into the current layer's local coordinate
+   * system, which is incompatible with 3D context preservation.
+   */
+  TransformStyle transformStyle() const {


这个和CSS一样，加个bool值的preserve3D的开关不行吗？

已经修改。

domchen

Code Review

1. RegionTransformer.cpp:190 - 逻辑错误

outerMatrix3D->canCombineWith(outerMatrix3D) 是自己与自己比较，永远返回 true（当 combineMode 都是 Combinable 时）。

应该检查当前 transformer 是否可以与 outer 合并，建议改为：

if (combineMode == Matrix3DCombineMode::Combinable &&
    outerMatrix3D->combineMode == Matrix3DCombineMode::Combinable) {

2. DrawPolygon3D.cpp:209 - 未使用的方法

isFacingPositiveZ() 方法已定义但在代码中未被使用，是否需要保留？如果是为未来扩展预留，建议添加注释说明。

3. 版权年份不一致

新增文件中部分使用 2025，部分使用 2026（如 Matrix3DUtils.h/cpp）。根据项目规范，新增文件应使用当前年份。

4. DrawPolygon3D.cpp:43 - 函数语义可优化

ProjectPoint 函数名表示投影点，但实际上 mapPoint 返回的是 Vec3，这里只取了 x, y 分量。建议改名为 ProjectTo2D 或添加注释说明只取 x, y 分量的原因。

domchen

代码简化建议

1. 重复的 styleSourceTypes 初始化逻辑

在 drawByStarting3DContext (Layer.cpp:1874-1875) 和 createChildArgs (Layer.cpp:1919-1920) 中有完全相同的代码：

contextArgs.styleSourceTypes = {LayerStyleExtraSourceType::None,
                                LayerStyleExtraSourceType::Contour};

建议提取为常量或辅助函数：

// 在文件顶部定义
static const std::vector<LayerStyleExtraSourceType> kStyleSourceTypesFor3DContext = {
    LayerStyleExtraSourceType::None, LayerStyleExtraSourceType::Contour};

2. DrawArgs 的 styleSourceTypes 默认值可考虑移除

DrawArgs.h:55-57 定义了 styleSourceTypes 的默认值，但每次进入 3D context 时都会重新设置。可以考虑只在需要时才设置，减少冗余赋值。

3. drawChildren 中的 clipChildScrollRectHandler lambda 可以提取

Layer.cpp:1828-1843 的 lambda 只在两处调用（canvas 和 backgroundCanvas），可以提取为私有成员函数，减少 drawChildren 的复杂度：

void Layer::clipScrollRect(Canvas* canvas, const Matrix3D& transform, bool isAffine) {
  if (!_scrollRect) return;
  if (isAffine) {
    canvas->clipRect(*_scrollRect);
  } else {
    Path path;
    path.addRect(*_scrollRect);
    path.transform3D(transform);
    canvas->clipPath(path);
  }
}

4. BspTree::traverseNode 中的重复代码

BspTree.h:78-107 中 if/else 两个分支结构相似，只是遍历顺序不同。可以提取公共部分：

template <typename Action>
void traverseNode(Action& action, const BspNode* node) const {
  BspNode* first = node->data->isFacingPositiveZ() ? node->backChild.get() : node->frontChild.get();
  BspNode* second = node->data->isFacingPositiveZ() ? node->frontChild.get() : node->backChild.get();
  auto& firstCoplanars = node->data->isFacingPositiveZ() ? node->coplanarsBack : node->coplanarsFront;
  auto& secondCoplanars = node->data->isFacingPositiveZ() ? node->coplanarsFront : node->coplanarsBack;
  
  if (first) traverseNode(action, first);
  for (const auto& p : firstCoplanars) action(p.get());
  action(node->data.get());
  for (const auto& p : secondCoplanars) action(p.get());
  if (second) traverseNode(action, second);
}

5. Context3DCompositor::drawQuads 可以简化

Context3DCompositor.cpp:169-177 中对 subQuads 是否为空的处理可以合并：

auto quadsToProcess = subQuads.empty() 
    ? std::vector<const QuadCW*>{nullptr}  // nullptr 表示使用原始 rect
    : /* convert subQuads to pointers */;

for (const auto* subQuad : quadsToProcess) {
  auto [quad, aaFlags] = GetQuadAndAAFlags(originalRect, aaType, subQuad);
  quadRecords.push_back(allocator->make<QuadRecord>(quad, aaFlags, vertexColor));
}

6. Render3DContext 中的 invScale 计算重复

Render3DContext.cpp:55 和 :86 都计算了 1.0f / _contentScale。可以在构造函数中预计算并存储为成员变量 _invContentScale。

7. canPreserve3D() 调用频繁

canPreserve3D() 在 Layer.cpp 中被调用了 18 次。由于其依赖条件（_transformStyle, _filters, _layerStyles, mask, scrollRect）都会触发 invalidateTransform()，可以考虑缓存结果在 bitFields 中，类似 matrix3DIsAffine 的处理方式。

…lication.

…D_context # Conflicts: # test/baseline/version.json

StarryThrone added 19 commits November 21, 2025 14:27

feat: Clip layer which behind viewer.

ae3ca76

feat: Draw child with preserve 3D style.

bb792a6

feat: Draw offscreen split children for layer which started a 3D rend…

6fba9b4

…ering context.

feat: Draw layer with depth occultation.

651e776

feat: Clip filter image only for layers outside the 3D rendering cont…

b43a371

…ext.

feat: Calculate render bounds correctly.

b4e9e05

Merge branch 'main' into feature/jasonrjchen_3D_context

83b3f1a

# Conflicts: # include/tgfx/layers/Layer.h # src/gpu/DrawingManager.cpp # src/layers/Layer.cpp # test/baseline/version.json

feat: Draw rasterized image cache.

4a34b31

feat: Hide layer when any point behind viewer.

7d30598

feat: Enable MSAA to solve aliasing issue.

e15aac6

feat: Draw image of 3D rendering context into background canvas.

01984d0

feat: Disable the background style of all subsequent sub-layers of th…

9f4bafb

…e current layer.

feat: Adjust the clipping area and anti-aliasing method to solve the …

4adb42f

…semi-transparent problem when the layer is too close to the observer.

feat: Disable the background style of the subsequent nodes of the 3D …

37590ad

…layer.

feat: The subsequent layer of the 3D layer obtains the content image …

f414663

…and uses the Canvas to calculate the cropping area.

Merge branch 'main' into feature/jasonrjchen_3D_context

ebfb512

Refactor 3D rendering context propagation and add alpha support for 3…

091810d

…D compositor.

Merge branch 'main' into feature/jasonrjchen_3D_context

2db8bb7

Translate Chinese comments to English in Layer.cpp.

a0fa69f

StarryThrone requested review from Hparty, domchen and shlzxjp as code owners December 9, 2025 12:44

StarryThrone added 3 commits December 9, 2025 21:19

feat: Resolve build problem.

16409b5

feat: Resolve build problem.

d710d42

feat: Optimize code.

5b4956e

Hparty reviewed Dec 12, 2025

View reviewed changes

StarryThrone added 3 commits December 16, 2025 16:14

feat: Refactor 3D context rendering logic and simplify draw functions.

c1c7c78

Move styleSourceTypes from function parameter to DrawArgs.

22d1417

Add 3D context handling to computeBounds for consistent bounds calcul…

a93777a

…ation.

Hparty reviewed Jan 8, 2026

View reviewed changes

StarryThrone and others added 14 commits January 9, 2026 00:03

Add behind-camera checks in computeBounds and fix Create3DContext bou…

2802e82

…nds handling.

Use emplace to construct Render3DContextState in place.

2f1c8a1

Remove redundant backgroundCanvas restore call.

9e99b06

Use cached matrix3DIsAffine instead of IsMatrix3DAffine call.

e78b3fc

Add behind-camera check to Transform3DImageFilter and defer matrix ad…

af61ad1

…aptation.

Add missing include for std::optional in RegionTransformer.h.

b4a24f3

Remove redundant FloatCeilToInt after roundOut in PictureToImage.

6b2ec12

Refactor behindCamera logic and fix background style processing.

8604fb5

Refactor Render3DContext with improved encapsulation and memory safety.

1ace7c1

Add Matrix3DUtils class to centralize Matrix3D utility functions.

f1de2a7

Remove Transform3DFilter and add ScaleAdaptedMatrix3D utility.

e425a4f

Merge remote-tracking branch 'origin/main' into feature/jasonrjchen_3…

9d41b69

…D_context

Use makeTextureImage instead of lockTextureProxy in Context3DCompositor.

2874403

Add boundary checks for Create3DContext function.

04c0a7f

domchen reviewed Jan 9, 2026

View reviewed changes

StarryThrone added 7 commits January 9, 2026 17:02

Replace TransformStyle enum with bool preserve3D property.

bc6009d

Replace Matrix3DCombineMode enum with bool canCombine parameter.

006e37c

Extract duplicate styleSourceTypes initialization to a static constant.

6ff760e

Extract scroll rect clipping lambda to static function ClipScrollRect.

d1ee2d8

Refactor BspTree traversal by extracting visitNode to reduce code dup…

30ff73e

…lication.

Merge remote-tracking branch 'origin/main' into feature/jasonrjchen_3…

3b9f227

…D_context # Conflicts: # test/baseline/version.json

domchen approved these changes Jan 9, 2026

View reviewed changes

domchen merged commit 484bda4 into main Jan 9, 2026
9 checks passed

domchen deleted the feature/jasonrjchen_3D_context branch January 9, 2026 11:51

Add 3D rendering context support with depth occlusion for layers. #1098

Add 3D rendering context support with depth occlusion for layers. #1098

Uh oh!

Conversation

StarryThrone commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

主要功能

技术实现

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

domchen left a comment

Choose a reason for hiding this comment

Code Review

1. RegionTransformer.cpp:190 - 逻辑错误

2. DrawPolygon3D.cpp:209 - 未使用的方法

3. 版权年份不一致

4. DrawPolygon3D.cpp:43 - 函数语义可优化

Uh oh!

domchen left a comment

Choose a reason for hiding this comment

代码简化建议

1. 重复的 styleSourceTypes 初始化逻辑

2. DrawArgs 的 styleSourceTypes 默认值可考虑移除

3. drawChildren 中的 clipChildScrollRectHandler lambda 可以提取

4. BspTree::traverseNode 中的重复代码

5. Context3DCompositor::drawQuads 可以简化

6. Render3DContext 中的 invScale 计算重复

7. canPreserve3D() 调用频繁

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

StarryThrone commented Dec 9, 2025 •

edited

Loading