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

Co-authored-by: 陈杰 <chenjie@chenjiedeMac-mini.local>

Author: StarryThrone

include/tgfx/core/Matrix3D.h

@@ -74,6 +74,13 @@ class Matrix3D {
    */
   Vec4 getRow(int i) const;
 
+  /**
+   * Sets the matrix values at the given row.
+   * @param i  Row index, valid range 0..3.
+   * @param v  Vector containing the values to set.
+   */
+  void setRow(int i, const Vec4& v);
+
   /**
    * Returns the matrix value at the given row and column.
    * @param r  Row index, valid range 0..3.
@@ -204,6 +211,11 @@ class Matrix3D {
     postSkew(kxy, 0, kyx, 0, 0, 0);
   }
 
+  /**
+   * Concatenates the given matrix with this matrix, and stores the result in this matrix. M' = M * m.
+   */
+  void preConcat(const Matrix3D& m);
+
   /**
    * Concatenates this matrix with the given matrix, and stores the result in this matrix. M' = M * m.
    */
@@ -253,9 +265,24 @@ class Matrix3D {
 
   /**
    * Maps a 3D point using this matrix.
+   * The point is treated as (x, y, z, 1) in homogeneous coordinates.
    * The returned result is the coordinate after perspective division.
    */
-  Vec3 mapVec3(const Vec3& v) const;
+  Vec3 mapPoint(const Vec3& point) const;
+
+  /**
+   * Maps a 3D vector using this matrix.
+   * The vector is treated as (x, y, z, 0) in homogeneous coordinates, so translation does not
+   * affect the result.
+   */
+  Vec3 mapVector(const Vec3& vector) const;
+
+  /**
+   * Maps a 4D homogeneous coordinate (x, y, z, w) using this matrix.
+   * If the current matrix contains a perspective transformation, the returned Vec4 is not
+   * perspective-divided; i.e., the w component of the result may not be 1.
+   */
+  Vec4 mapHomogeneous(float x, float y, float z, float w) const;
 
   /**
    * Returns true if the matrix is an identity matrix.
@@ -293,11 +320,6 @@ class Matrix3D {
    */
   void setConcat(const Matrix3D& a, const Matrix3D& b);
 
-  /**
-   * Concatenates the given matrix with this matrix, and stores the result in this matrix. M' = M * m.
-   */
-  void preConcat(const Matrix3D& m);
-
   /**
    * Pre-concatenates a scale to this matrix. M' = M * S.
    */
@@ -308,34 +330,25 @@ class Matrix3D {
    */
   Matrix3D transpose() const;
 
-  /**
-   * Maps a 4D point (x, y, z, w) using this matrix.
-   * If the current matrix contains a perspective transformation, the returned Vec4 is not
-   * perspective-divided; i.e., the w component of the result may not be 1.
-   */
-  Vec4 mapPoint(float x, float y, float z, float w) const;
-
   Vec4 getCol(int i) const {
     Vec4 v;
     memcpy(&v, values + i * 4, sizeof(Vec4));
     return v;
   }
 
-  void setAll(float m00, float m01, float m02, float m03, float m10, float m11, float m12,
-              float m13, float m20, float m21, float m22, float m23, float m30, float m31,
-              float m32, float m33);
-
-  void setRow(int i, const Vec4& v) {
-    values[i + 0] = v.x;
-    values[i + 4] = v.y;
-    values[i + 8] = v.z;
-    values[i + 12] = v.w;
-  }
-
+  /**
+   * Sets the matrix values at the given column.
+   * @param i  Column index, valid range 0..3.
+   * @param v  Vector containing the values to set.
+   */
   void setColumn(int i, const Vec4& v) {
     memcpy(&values[i * 4], v.ptr(), sizeof(v));
   }
 
+  void setAll(float m00, float m01, float m02, float m03, float m10, float m11, float m12,
+              float m13, float m20, float m21, float m22, float m23, float m30, float m31,
+              float m32, float m33);
+
   void setIdentity() {
     *this = Matrix3D();
   }
@@ -353,7 +366,7 @@ class Matrix3D {
   }
 
   Vec4 operator*(const Vec4& v) const {
-    return this->mapPoint(v.x, v.y, v.z, v.w);
+    return this->mapHomogeneous(v.x, v.y, v.z, v.w);
   }
 
   float values[16] = {.0f};

include/tgfx/core/Vec.h

@@ -172,6 +172,13 @@ struct Vec3 {
     return sqrtf(Dot(*this, *this));
   }
 
+  /**
+   * Returns the squared length of the vector.
+   */
+  float lengthSquared() const {
+    return Dot(*this, *this);
+  }
+
   /**
    * Returns a pointer to the vector's immutable data.
    */

include/tgfx/layers/Layer.h

@@ -37,6 +37,7 @@ class DisplayList;
 class DrawArgs;
 class RegionTransformer;
 class RootLayer;
+class Render3DContext;
 struct LayerStyleSource;
 struct MaskData;
 class BackgroundContext;
@@ -125,6 +126,8 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   /**
    * Sets the blend mode of the layer.
+   * Note: Layers inside a 3D Rendering Context (see preserve3D()) always use SrcOver blend mode
+   * regardless of this setting.
    */
   void setBlendMode(BlendMode value);
 
@@ -139,6 +142,8 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   /**
    * Sets whether the layer passes through its background to sublayers.
+   * Note: Layers that can start or extend a 3D Rendering Context (see preserve3D()) always disable
+   * pass-through background regardless of this setting.
    */
   void setPassThroughBackground(bool value);
 
@@ -178,6 +183,39 @@ class Layer : public std::enable_shared_from_this<Layer> {
    */
   void setMatrix3D(const Matrix3D& value);
 
+  /**
+   * Returns whether the layer preserves the 3D state of its content and child layers. The default
+   * value is false.
+   *
+   * When false, content and child layers are projected onto the layer's local space. Child layers
+   * are drawn in the order they were added, so later-added opaque layers completely cover earlier
+   * ones.
+   *
+   * When true, 3D rendering is enabled. If the parent layer has preserve3D disabled, this layer
+   * establishes a new 3D Rendering Context. If the parent also has preserve3D enabled, this layer
+   * inherits and extends the parent's context.
+   *
+   * Within a 3D Rendering Context, all child layers share the coordinate space of the context
+   * root's parent (or the DisplayList if no parent exists). Depth occlusion is applied based on
+   * actual 3D positions: opaque pixels closer to the observer occlude those farther away at the
+   * same xy coordinates.
+   *
+   * Note: preserve3D falls back to false behavior when any of the following conditions are met:
+   * 1. Layer styles is not empty.
+   * 2. Filters is not empty.
+   * 3. Mask is not empty.
+   * These features require projecting child layers into the current layer's local coordinate
+   * system, which is incompatible with 3D context preservation.
+   */
+  bool preserve3D() const {
+    return _preserve3D;
+  }
+
+  /**
+   * Sets whether the layer preserves the 3D state of its content and child layers.
+   */
+  void setPreserve3D(bool value);
+
   /**
    * Returns whether the layer is visible. The default value is true.
    */
@@ -217,6 +255,8 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   /**
    * Sets whether the layer is allowed to be composited as a separate group from their parent.
+   * Note: Layers inside a 3D Rendering Context (see preserve3D()) always apply alpha individually
+   * to each element regardless of this setting.
    */
   void setAllowsGroupOpacity(bool value);
 
@@ -233,6 +273,14 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   /**
    * Sets the list of layer styles applied to the layer.
+   * Note: Background-dependent layer styles (e.g., BackgroundBlurStyle) have the following
+   * limitations:
+   * 1. Layers that start a 3D Rendering Context (see preserve3D()) disable background styles for
+   *    the entire subtree rooted at that layer. The 3D Rendering Context uses a different rendering
+   *    strategy that has not yet fully adapted background layer drawing.
+   * 2. Layers with a 3D or projection transformation disable background styles for all descendant
+   *    layers (excluding the layer itself), because descendants cannot correctly obtain the
+   *    background.
    */
   void setLayerStyles(const std::vector<std::shared_ptr<LayerStyle>>& value);
 
@@ -577,17 +625,22 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   void drawDirectly(const DrawArgs& args, Canvas* canvas, float alpha);
 
-  void drawDirectly(const DrawArgs& args, Canvas* canvas, float alpha,
-                    const std::vector<LayerStyleExtraSourceType>& styleExtraSourceTypes);
-
   void drawContents(const DrawArgs& args, Canvas* canvas, float alpha,
                     const LayerStyleSource* layerStyleSource = nullptr,
-                    const Layer* stopChild = nullptr,
-                    const std::vector<LayerStyleExtraSourceType>& styleExtraSourceTypes = {});
+                    const Layer* stopChild = nullptr);
 
   bool drawChildren(const DrawArgs& args, Canvas* canvas, float alpha,
                     const Layer* stopChild = nullptr);
 
+  void drawByStarting3DContext(const DrawArgs& args, Canvas* canvas);
+
+  std::optional<DrawArgs> createChildArgs(const DrawArgs& args, Canvas* canvas, Layer* child,
+                                          bool skipBackground, int childIndex,
+                                          int lastBackgroundIndex);
+
+  void drawChild(const DrawArgs& args, Canvas* canvas, Layer* child, float alpha,
+                 const Matrix3D& transform3D, Render3DContext* context3D, bool started3DContext);
+
   float drawBackgroundLayers(const DrawArgs& args, Canvas* canvas);
 
   std::unique_ptr<LayerStyleSource> getLayerStyleSource(const DrawArgs& args, const Matrix& matrix,
@@ -598,7 +651,7 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   /**
    * Gets the background image of the minimum axis-aligned bounding box after drawing the layer
-   * subtree with the current layer as the root node.
+   * subtree with the current layer as the root node
    */
   std::shared_ptr<Image> getBoundsBackgroundImage(const DrawArgs& args, float contentScale,
                                                   Point* offset);
@@ -608,12 +661,8 @@ class Layer : public std::enable_shared_from_this<Layer> {
   void drawLayerStyles(const DrawArgs& args, Canvas* canvas, float alpha,
                        const LayerStyleSource* source, LayerStylePosition position);
 
-  void drawLayerStyles(const DrawArgs& args, Canvas* canvas, float alpha,
-                       const LayerStyleSource* source, LayerStylePosition position,
-                       const std::vector<LayerStyleExtraSourceType>& styleExtraSourceTypes);
-
   void drawBackgroundLayerStyles(const DrawArgs& args, Canvas* canvas, float alpha,
-                                 const Matrix3D& transform);
+                                 const Matrix3D& transform3D);
 
   bool getLayersUnderPointInternal(float x, float y, std::vector<std::shared_ptr<Layer>>* results);
 
@@ -657,27 +706,18 @@ class Layer : public std::enable_shared_from_this<Layer> {
                             const Matrix3D* transform3D,
                             const std::shared_ptr<MaskFilter>& maskFilter);
 
-  std::shared_ptr<Image> getContentImage(
-      const DrawArgs& args, const Matrix& contentMatrix, const std::optional<Rect>& clipBounds,
-      const std::vector<LayerStyleExtraSourceType>& extraSourceTypes, Matrix* imageMatrix);
+  std::shared_ptr<Image> getContentImage(const DrawArgs& args, const Matrix& contentMatrix,
+                                         const std::optional<Rect>& clipBounds,
+                                         Matrix* imageMatrix);
 
-  std::shared_ptr<Image> getPassThroughContentImage(
-      const DrawArgs& args, Canvas* canvas, const std::optional<Rect>& clipBounds,
-      const std::vector<LayerStyleExtraSourceType>& extraSourceTypes, Matrix* imageMatrix);
+  std::shared_ptr<Image> getPassThroughContentImage(const DrawArgs& args, Canvas* canvas,
+                                                    const std::optional<Rect>& clipBounds,
+                                                    Matrix* imageMatrix);
 
   std::optional<Rect> computeContentBounds(const std::optional<Rect>& clipBounds,
                                            bool excludeEffects);
 
-  /**
-   * Returns the equivalent transformation matrix adapted for a custom anchor point.
-   * The matrix is defined based on a local coordinate system, with the transformation anchor point
-   * being the origin of that coordinate system. This function returns an affine transformation
-   * matrix that produces the same visual effect when using any point within this coordinate system
-   * as the new origin and anchor point.
-   * @param matrix The original transformation matrix.
-   * @param anchor The specified anchor point.
-   */
-  Matrix3D anchorAdaptedMatrix(const Matrix3D& matrix, const Point& anchor) const;
+  bool canPreserve3D() const;
 
   void invalidateSubtree();
 
@@ -703,6 +743,7 @@ class Layer : public std::enable_shared_from_this<Layer> {
   float _alpha = 1.0f;
   // The actual transformation matrix that determines the geometric position of the layer
   Matrix3D _matrix3D = {};
+  bool _preserve3D = false;
   std::shared_ptr<Layer> _mask = nullptr;
   Layer* maskOwner = nullptr;
   std::unique_ptr<Rect> _scrollRect = nullptr;

include/tgfx/layers/filters/LayerFilter.h

@@ -53,8 +53,7 @@ class LayerFilter : public LayerProperty {
     BlurFilter,
     ColorMatrixFilter,
     DropShadowFilter,
-    InnerShadowFilter,
-    Transform3DFilter
+    InnerShadowFilter
   };
 
   virtual Type type() const {