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

include/tgfx/core/Image.h

@@ -384,5 +384,6 @@ class Image {
   friend class ImageShader;
   friend class Types;
   friend class Transform3DImageFilter;
+  friend class Context3DCompositor;
 };
 }  // namespace tgfx

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.
    */
@@ -257,6 +269,13 @@ class Matrix3D {
    */
   Vec3 mapVec3(const Vec3& v) 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;
+
   /**
    * Returns true if the matrix is an identity matrix.
    */
@@ -293,11 +312,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 +322,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();
   }

include/tgfx/gpu/RenderPass.h

@@ -196,9 +196,35 @@ class RenderPassDescriptor {
                                 LoadAction loadAction = LoadAction::DontCare,
                                 StoreAction storeAction = StoreAction::Store,
                                 PMColor clearValue = PMColor::Transparent(),
-                                std::shared_ptr<Texture> resolveTexture = nullptr) {
-    colorAttachments.emplace_back(std::move(texture), loadAction, storeAction, clearValue,
+                                std::shared_ptr<Texture> resolveTexture = nullptr)
+      : RenderPassDescriptor(std::move(texture), nullptr, loadAction, storeAction, clearValue,
+                             std::move(resolveTexture)) {
+  }
+
+  /**
+   * A convenience constructor that initializes a RenderPassDescriptor with a single color attachment
+   * and an optional depthstencil attachment.
+   * @param clorTexture The texture to render to.
+   * @param depthStencilTexture The depth-stencil texture to render to, or nullptr if not using
+   * depth-stencil.
+   * @param loadAction The action to perform at the start of the render pass.
+   * @param storeAction The action to perform at the end of the render pass.
+   * @param clearValue The color value to clear the attachment with if the load action is
+   * LoadAction::Clear.
+   * @param resolveTexture The texture to resolve the color attachment into. This is used for
+   * multisampled textures. If this is nullptr, the color attachment will not be resolved.
+   */
+  RenderPassDescriptor(std::shared_ptr<Texture> clorTexture,
+                       std::shared_ptr<Texture> depthStencilTexture,
+                       LoadAction loadAction = LoadAction::DontCare,
+                       StoreAction storeAction = StoreAction::Store,
+                       PMColor clearValue = PMColor::Transparent(),
+                       std::shared_ptr<Texture> resolveTexture = nullptr) {
+    colorAttachments.emplace_back(std::move(clorTexture), loadAction, storeAction, clearValue,
                                   std::move(resolveTexture));
+    if (depthStencilTexture != nullptr) {
+      depthStencilAttachment = DepthStencilAttachment(std::move(depthStencilTexture));
+    }
   }
 
   /**

include/tgfx/layers/Layer.h

@@ -21,6 +21,7 @@
 #include <memory>
 #include <optional>
 #include <unordered_set>
+#include "TransformStyle.h"
 #include "tgfx/core/BlendMode.h"
 #include "tgfx/core/Canvas.h"
 #include "tgfx/core/Matrix.h"
@@ -177,6 +178,44 @@ class Layer : public std::enable_shared_from_this<Layer> {
    */
   void setMatrix3D(const Matrix3D& value);
 
+  /**
+   * Returns the transform style of the layer. The default value is TransformStyle::Flat.
+   * TransformStyle defines the drawing behavior of child layers containing 3D transformations.
+   * The Flat type projects 3D child layers directly onto their parent layer, and all child layers
+   * are drawn in the order they were added. This means that later-added opaque child layers will
+   * completely cover earlier-added child layers. The Preserve3D type preserves the 3D state of child
+   * layers.
+   * If a layer's TransformStyle is Preserve3D and its parent layer is Flat, this layer establishes
+   * a 3D Rendering Context. If the parent layer is Preserve3D, this layer inherits the parent's 3D
+   * Rendering Context and passes it to its child layers.
+   * All child layers within a 3D Rendering Context share the coordinate space of the layer that
+   * established the context. Within this context, all layers apply depth occlusion based on their
+   * actual positions: opaque pixels in layers closer to the observer will occlude pixels in layers
+   * farther from the observer at the same position (same xy coordinates).
+   *
+   * Note: TransformStyle::Preserve3D does not support some features. When the following conditions
+   * are met, even if the layer is set to TransformStyle::Preserve3D, its drawing behavior will be
+   * TransformStyle::Flat:
+   * The prerequisite for these features to take effect is that child layers need to be projected
+   * into the local coordinate system of the current layer.
+   * 1. layerstyles is not empty
+   * The following features require the entire layer subtree of the root node to be packaged and
+   * drawn, and then the corresponding effects are applied.
+   * 2. Blend mode is set to any value other than BlendMode::SrcOver
+   * 3. passThroughBackground = false
+   * 4. allowsGroupOpacity = true
+   * 5. shouldRasterize = true
+   * 6. mask is not empty
+   */
+  TransformStyle transformStyle() const {
+    return _transformStyle;
+  }
+
+  /**
+   * Sets the transform style of the layer.
+   */
+  void setTransformStyle(TransformStyle style);
+
   /**
    * Returns whether the layer is visible. The default value is true.
    */
@@ -573,7 +612,10 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   void invalidate();
 
-  Rect getBounds(const Matrix3D& matrix, bool computeTightBounds);
+  /**
+   * Returns the content bounds of the layer, excluding child layers.
+   */
+  Rect getContentBounds();
 
   Rect getBoundsInternal(const Matrix3D& coordinateMatrix, bool computeTightBounds);
 
@@ -604,20 +646,28 @@ class Layer : public std::enable_shared_from_this<Layer> {
                          const Matrix3D* transform = nullptr);
 
   void drawOffscreen(const DrawArgs& args, Canvas* canvas, float alpha, BlendMode blendMode,
-                     const Matrix3D* transform);
+                     const Matrix3D* transform, bool excludeChildren = false);
 
   void drawDirectly(const DrawArgs& args, Canvas* canvas, float alpha);
 
   void drawDirectly(const DrawArgs& args, Canvas* canvas, float alpha,
-                    const std::unordered_set<LayerStyleExtraSourceType>& styleExtraSourceTypes);
+                    const std::unordered_set<LayerStyleExtraSourceType>& styleExtraSourceTypes,
+                    bool excludeChildren);
 
-  void drawContents(
-      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,
+                               BlendMode blendMode, const Matrix3D* transform);
+
+  void drawIn3DContext(const DrawArgs& args, Canvas* canvas, float alpha, BlendMode blendMode,
+                       const Matrix3D* transform);
+
+  void drawContents(const DrawArgs& args, Canvas* canvas, float alpha,
+                    const LayerStyleSource* layerStyleSource = nullptr,
+                    const Layer* stopChild = nullptr,
+                    const std::unordered_set<LayerStyleExtraSourceType>& styleExtraSourceTypes = {},
+                    bool excludeChildren = false);
 
   bool drawChildren(const DrawArgs& args, Canvas* canvas, float alpha,
-                    const Layer* stopChild = nullptr);
+                    const Layer* stopChild = nullptr, const Matrix3D* transform = nullptr);
 
   float drawBackgroundLayers(const DrawArgs& args, Canvas* canvas);
 
@@ -655,8 +705,25 @@ class Layer : public std::enable_shared_from_this<Layer> {
 
   bool hasValidMask() const;
 
+  /**
+   * Updates the rendering bounds.
+   * When calculating rendering bounds for layers outside a 3D context, matrix transformations can
+   * be applied progressively from child layers to parent layers. However, layers inside a 3D
+   * context need to preserve their 3D state. This approach would lose depth information for these
+   * layers.
+   * They need to calculate rendering bounds based on the overall matrix state of the 3D context
+   * and the relative matrix of the layer itself to the layer that established the context.
+   * @param transformer The region transformer to be applied to the current layer.
+   * @param context3DTransformer The overall transformer of the 3D context to which the current
+   * layer belongs when it is inside a 3D context. This parameter cannot be null when the layer is
+   * inside a 3D context.
+   * @param context3DTransform The relative matrix of the current layer to the layer that
+   * established the 3D context when the current layer is inside a 3D context. This parameter
+   * cannot be null when the layer is inside a 3D context.
+   */
   void updateRenderBounds(std::shared_ptr<RegionTransformer> transformer = nullptr,
-                          bool forceDirty = false);
+                          std::shared_ptr<RegionTransformer> context3DTransformer = nullptr,
+                          const Matrix3D* context3DTransform = nullptr, bool forceDirty = false);
 
   void checkBackgroundStyles(std::shared_ptr<RegionTransformer> transformer);
 
@@ -679,7 +746,8 @@ class Layer : public std::enable_shared_from_this<Layer> {
   std::shared_ptr<Image> getContentImage(const DrawArgs& args, float contentScale,
                                          const std::shared_ptr<Image>& passThroughImage,
                                          const Matrix& passThroughImageMatrix,
-                                         std::optional<Rect> clipBounds, Matrix* imageMatrix);
+                                         std::optional<Rect> clipBounds, Matrix* imageMatrix,
+                                         bool excludeChildren);
 
   /**
    * Returns the equivalent transformation matrix adapted for a custom anchor point.
@@ -692,6 +760,17 @@ class Layer : public std::enable_shared_from_this<Layer> {
    */
   Matrix3D anchorAdaptedMatrix(const Matrix3D& matrix, const Point& anchor) const;
 
+  /**
+   * Calculates the 3D context depth matrix for the layer.
+   * This matrix maps the depth of all sublayers within the 3D render context rooted at this layer
+   * from [maxDepth, minDepth] to the [-1, 1] range.
+   */
+  Matrix3D calculate3DContextDepthMatrix();
+
+  bool canExtend3DContext() const;
+
+  bool in3DContext() const;
+
   struct {
     bool dirtyContent : 1;        // layer's content needs updating
     bool dirtyContentBounds : 1;  // layer's content bounds needs updating
@@ -712,6 +791,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 = {};
+  TransformStyle _transformStyle = TransformStyle::Flat;
   std::shared_ptr<Layer> _mask = nullptr;
   Layer* maskOwner = nullptr;
   std::unique_ptr<Rect> _scrollRect = nullptr;

include/tgfx/layers/TransformStyle.h

@@ -0,0 +1,40 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2025 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+namespace tgfx {
+/**
+ * Defines the transform style of a layer.
+ */
+enum class TransformStyle {
+  /**
+   * Does not preserve the 3D state of sublayers. Sublayers with 3D transformations are directly
+   * projected onto the current layer plane. In this mode, later added layers will cover earlier
+   * added layers.
+   */
+  Flat,
+
+  /**
+   * Preserves the 3D state of sublayers. In this mode, interacting sublayers will be occluded based
+   * on the actual depth of pixels, meaning opaque pixels closer to the observer will cover those
+   * farther away.
+   */
+  Preserve3D
+};
+}  // namespace tgfx