Add a Transform3DImageFilter to apply perspective projection effects. #938

StarryThrone · 2025-09-18T09:04:21Z

1、新增Transform3DImageFilter，支持设置44矩阵和Size类型视口大小对输入图像应用3D投影变换。
2、从DrawOp派生Rect3DDrawOp实现渲染任务。使用Transform3DGeometryProcessor实现顶点处理逻辑。
3、接口层暴露Vector和Matrix3D用于构建44变换矩阵。

domchen · 2025-09-18T10:50:50Z

src/gpu/processors/QuadPerEdgeAA3DGeometryProcessor.h

+/**
+ * A geometry processor for rendering 3D transformed quads with optional per-edge anti-aliasing.
+ */
+class QuadPerEdgeAA3DGeometryProcessor : public GeometryProcessor {


建议和滤镜同名：Transform3DGeometryProcessor

已经修改。

domchen · 2025-09-22T01:21:47Z

src/gpu/tasks/Transform3DRenderTask.cpp

+    return;
+  }
+
+  constexpr auto loadOp = LoadAction::Clear;


这个声明一个变量的意义是什么？

这个变量声明确实多余了。另外按最新意见，整个Transform3DRenderTask已经重构。

domchen · 2025-09-22T01:26:06Z

src/gpu/tasks/Transform3DRenderTask.cpp

+  constexpr auto loadOp = LoadAction::Clear;
+  const RenderPassDescriptor descriptor(rt->getRenderTexture(), loadOp, StoreAction::Store,
+                                        Color::Transparent(), nullptr);
+  const auto renderPass = encoder->beginRenderPass(descriptor);


这个类没有看到任何调用深度缓冲和模板缓冲的代码，是不是没有必要单独写个RenderTask，走公共的RectDrawOp就可以了？

按最新意见，整个Transform3DRenderTask已经重构，直接使用实现Rect3DDrawOp。

shlzxjp · 2025-09-23T14:51:50Z

include/tgfx/core/ImageFilter.h

+   * @param matrix 3D transformation matrix used to convert model coordinates to clip space.
+   * @param viewSize Window view size, used to map NDC coordinates to window coordinates.
+   */
+  static std::shared_ptr<ImageFilter> Transform3D(const Matrix3D& matrix, const Size& viewSize);


viewSize 不是 Rect的大小吗？这里注释写是Window view size,容易让人误解

我把NDC坐标最后做视口变换的那一步看成是映射到一个窗口，所有注释这么写了。参数我改成viewportsize，这样和GL的接口glViewport一致，更容易理解。

shlzxjp · 2025-09-23T14:55:02Z

include/tgfx/core/MathVector.h

+   * Returns the quotient of this vector and a scalar, computed as (v.x / s, v.y / s).
+   */
+  friend Vec2 operator/(const Vec2& v, float s) {
+    return {v.x / s, v.y / s};


s需要防止被0除

只增加DEBUG_ASSERT(!FloatNearlyZero(s));判断，不错额外处理，因为除以0并不会直接crash，会得到NaN，这个异常值可以返回给使用者，引擎内部隐藏错误可能不太好，

shlzxjp · 2025-09-23T15:00:05Z

include/tgfx/core/Matrix3D.h

+  /**
+   * Creates a Matrix3D set to the identity matrix.
+   */
+  constexpr Matrix3D() : Matrix3D(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1) {


按4行4列书写，禁用clang-format，方便阅读

已经修改，通过注释的方式增加可读性

shlzxjp · 2025-09-23T15:18:50Z

include/tgfx/core/Matrix3D.h

+    return this->mapPoint(v.x, v.y, v.z, v.w);
+  }
+
+  float values[16];


初始化下

已经修改。

shlzxjp · 2025-09-23T15:20:00Z

src/core/Matrix3D.cpp

+  dst[15] = src[15];
+}
+
+static bool Invert4x4Matrix(const float inMat[16], float outMat[16]) {


把概念统一一下，要么统一叫Matrix44，要么统一叫Matrix3D，不要混用

已经修改。

shlzxjp · 2025-09-23T15:23:59Z

src/core/filters/Transform3DImageFilter.cpp

+      source->isAlphaOnly(), 1, args.mipmapped, ImageOrigin::TopLeft, args.backingFit);
+  auto sourceTextureProxy = source->lockTextureProxy(args);
+
+  const auto srcW = static_cast<float>(source->width());


这些const都可以删除掉

已经修改。

shlzxjp · 2025-09-23T15:25:45Z

src/gpu/glsl/processors/GLSLQuadPerEdgeAA3DGeometryProcessor.cpp

+#define UNIFORM_NDC_OFFSET_NAME "ndcOffset"
+
+PlacementPtr<Transform3DGeometryProcessor> Transform3DGeometryProcessor::Make(
+    BlockBuffer* buffer, AAType aa, const Matrix3D& transformMatrix, const Vec2& ndcScale,


transform 和 matrix很多时候是等价的概念

已经修改。

shlzxjp · 2025-09-23T15:26:14Z

src/gpu/glsl/processors/GLSLQuadPerEdgeAA3DGeometryProcessor.cpp

+}
+
+void GLSLQuadPerEdgeAA3DGeometryProcessor::emitCode(EmitArgs& args) const {
+  const auto vertBuilder = args.vertBuilder;


const都去掉

已经修改。

shlzxjp · 2025-09-23T15:28:46Z

src/gpu/processors/Transform3DGeometryProcessor.h

+
+  void onComputeProcessorKey(BytesKey* bytesKey) const override;
+
+  Attribute position;


成员变量都初始化下

已经修改。

shlzxjp · 2025-09-23T15:29:37Z

src/gpu/ops/DrawOp.h

 class DrawOp {
 public:
-  enum class Type { RectDrawOp, RRectDrawOp, ShapeDrawOp, AtlasTextOp };
+  enum class Type { RectDrawOp, RRectDrawOp, ShapeDrawOp, AtlasTextOp, Rect3DDrawOp };


这里支持吃了Rect做3D变换吗？RRect、Shape呢

是的。PRect和Shape还没有支持，但理论上都可以通过一个投影矩阵和视口大小实现3D投影的。这里先暂时满足需求应该就好了。

shlzxjp · 2025-09-25T02:55:38Z

include/tgfx/core/Vec.h

vec2、vec3、vec4的逻辑都是一样的，看能否合并，内部的实现逻辑都转成vec4的，这样就避免有大量重复代码

如果优化需要使用匿名结构体，这个属于非标准的CPP用法。

shlzxjp · 2025-09-25T02:58:34Z

include/tgfx/core/ImageFilter.h

 namespace tgfx {
 class TextureProxy;
 enum class SrcRectConstraint;
+struct PerspectiveInfo;


这个前向声明应该删除吧

已经修改。

shlzxjp · 2025-09-25T03:23:55Z

src/gpu/processors/Transform3DGeometryProcessor.h

+                                                         const Vec2& ndcOffset);
+
+  std::string name() const override {
+    return "QuadPerEdgeAA3DGeometryProcessor";


这个名字和类名保持一致

已经修改。

shlzxjp · 2025-09-25T10:57:10Z

include/tgfx/core/Matrix3D.h

+    values[i + 12] = v.w;
+  }
+
+  void setCol(int i, const Vec4& v) {


setColumn写全称吧

已经修改。

shlzxjp · 2025-09-25T11:00:29Z

src/gpu/ops/Rect3DDrawOp.cpp

+  const Vec2 scale2(drawArgs.viewportSize.width / static_cast<float>(renderTarget->width()),
+                    drawArgs.viewportSize.height / static_cast<float>(renderTarget->height()));


宽高的有效性检查下，防止除以0

已加DEBUG_ASSERT。

domchen · 2025-09-25T13:03:06Z

include/tgfx/core/Vec.h

这个文件要么命名为Vec.h和内容保持一致。要么和Skia一样，把里面的内容都放到Matrix3D.h文件的前面。

已经改名。

domchen · 2025-09-25T13:07:05Z

src/core/filters/Transform3DImageFilter.cpp

+  return result;
+}
+
+std::shared_ptr<TextureProxy> Transform3DImageFilter::lockTextureProxy(


这个方法里没有实现args.drawScale的缩放优化吧？

已经补充，同时补充了单测用例。

domchen · 2025-09-25T13:22:13Z

src/gpu/glsl/processors/GLSLQuadPerEdgeAA3DGeometryProcessor.cpp

+#define UNIFORM_TRANSFORM_MATRIX_NAME "transformMatrix"
+#define UNIFORM_NDC_SCALE_NAME "ndcScale"
+#define UNIFORM_NDC_OFFSET_NAME "ndcOffset"


我们尽量避免使用#define, 缺少作用域，都改成static constexpr char*

已经修改。

domchen · 2025-09-26T03:29:55Z

src/core/filters/Transform3DImageFilter.cpp

+    std::shared_ptr<Image> source, const Rect& renderBounds, const TPArgs& args) const {
+  float dstDrawWidth = renderBounds.width();
+  float dstDrawHeight = renderBounds.height();
+  const float tmpDrawScale = std::max(0.f, args.drawScale);


这个变量如果不允许小于0，直接DEBUG_ASSERT(args.drawScale>0.0f)，不用赋值给一个大于等于零的临时变量再DEBUG_ASSERT

已经修改。

domchen · 2025-09-26T03:32:47Z

src/gpu/glsl/processors/GLSLQuadPerEdgeAA3DGeometryProcessor.cpp

+static constexpr const char* UniformTransformMatrixName = "transformMatrix";
+static constexpr const char* UniformNdcScaleName = "ndcScale";
+static constexpr const char* UniformNdcOffsetName = "ndcOffset";


改成这种写法：static constexpr const char UniformTransformMatrixName[] =

已经修改。

StarryThrone added 30 commits September 9, 2025 16:27

feat: Initialize perspective image filter.

4bff6e7

feat: Add math vector.

aada7a7

feat: Add matrix 3D.

0d0068b

feat: Map rect by matrix 3D.

db8e708

feat: Try calculate filtered rect.

20fc94f

feat: Provide perspective filter interface.

5dc850e

feat: Define perspective render task.

8a46f36

feat: Set index and vertex buffer.

b05bdcf

feat: Render with perspective task.

c1806c2

feat: Add resource task before execute render task.

b4b8bd1

feat: Correct matrix calculate logic.

d85e2e4

feat: Correct filtered bounds.

ad3a9e2

feat: Try apply transform matrix.

d866cac

feat: Adjust NDC point.

c700e13

Merge branch 'main' into feature/jasonrjchen_3D_render

44d8dfe

feat: Sample with correct coordinate.

21d7f06

feat: Clear texture first.

8965238

feat: Move NDC scale and offset logic to filter.

e86f285

feat: Allow set depth.

de39de7

feat: Calculate correct filtered bounds.

e291331

feat: Scale and translate NDC rect to display required content.

f2ac46d

feat: Complete unit test.

4bdfa12

feat: Add perspective layer filter.

bdd7342

feat: Complete unit test.

90b7926

feat: Define css project model.

d4d66ec

feat: Use css project type.

f66a498

feat: Allow caller control project type.

5a2dc2d

feat: Optimize code.

d2ad7fb

feat: Complete unit test case.

4c520c9

feat: Add annotations.

57832bc

domchen reviewed Sep 18, 2025

View reviewed changes

domchen changed the title ~~Provide perspective filters for applying perspective projection effects on the canvas (Paint) and on layers.~~ Add a Transform3DImageFilter to apply perspective projection effects. Sep 19, 2025

domchen reviewed Sep 22, 2025

View reviewed changes

StarryThrone added 3 commits September 22, 2025 20:32

feat: Rename symbol and simplify input parameters of 3D image filter.

d541f59

feat: Optimize code.

b773749

feat: Optimize code.

1dcf21f

shlzxjp reviewed Sep 23, 2025

View reviewed changes

StarryThrone added 2 commits September 24, 2025 19:04

feat: Optimize code.

2eb665b

Merge branch 'main' into feature/jasonrjchen_3D_render

5110d29

shlzxjp reviewed Sep 25, 2025

View reviewed changes

feat: Optimize code.

66f03ba

shlzxjp reviewed Sep 25, 2025

View reviewed changes

StarryThrone added 3 commits September 25, 2025 20:02

feat: Optimize code.

0a07b42

feat: Optimize code.

dd1cfa6

feat: Optimize code.

8be82b9

shlzxjp previously approved these changes Sep 25, 2025

View reviewed changes

domchen reviewed Sep 25, 2025

View reviewed changes

feat: Optimize code.

1c97b5b

StarryThrone dismissed shlzxjp’s stale review via 1c97b5b September 26, 2025 03:13

domchen reviewed Sep 26, 2025

View reviewed changes

feat: Optimize code.

671483c

domchen approved these changes Sep 26, 2025

View reviewed changes

domchen merged commit aa5de9f into main Sep 26, 2025
9 checks passed

domchen deleted the feature/jasonrjchen_3D_render branch September 26, 2025 04:23


		void onComputeProcessorKey(BytesKey* bytesKey) const override;

		Attribute position;

		const Vec2 scale2(drawArgs.viewportSize.width / static_cast<float>(renderTarget->width()),
		drawArgs.viewportSize.height / static_cast<float>(renderTarget->height()));

Add a Transform3DImageFilter to apply perspective projection effects. #938

Add a Transform3DImageFilter to apply perspective projection effects. #938

Uh oh!

Conversation

StarryThrone commented Sep 18, 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!

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!

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

StarryThrone commented Sep 18, 2025 •

edited

Loading

domchen Sep 25, 2025 •

edited

Loading

domchen Sep 25, 2025 •

edited

Loading