react-native-tgfx 0.0.0 → 0.0.2-alpha.0

package/cpp/third_party/tgfx/src/layers/Layer.cpp

@@ -0,0 +1,2257 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2024 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.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#include "tgfx/layers/Layer.h"
+#include <algorithm>
+#include <atomic>
+#include <cmath>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include "compositing3d/Context3DCompositor.h"
+#include "compositing3d/Layer3DContext.h"
+#include "core/Matrix3DUtils.h"
+#include "core/images/TextureImage.h"
+#include "core/utils/Log.h"
+#include "core/utils/MathExtra.h"
+#include "core/utils/Types.h"
+#include "layers/BackgroundHandler.h"
+#include "layers/BackgroundSnapshotMap.h"
+#include "layers/BackgroundSource.h"
+#include "layers/DrawArgs.h"
+#include "layers/LayerStyleSource.h"
+#include "layers/MaskContext.h"
+#include "layers/OffscreenRenderer.h"
+#include "layers/OpaqueContext.h"
+#include "layers/RegionTransformer.h"
+#include "layers/RootLayer.h"
+#include "layers/SubtreeCache.h"
+#include "layers/contents/LayerContent.h"
+#include "tgfx/core/ColorSpace.h"
+#include "tgfx/core/PictureRecorder.h"
+#include "tgfx/core/Surface.h"
+#include "tgfx/layers/ShapeLayer.h"
+
+namespace tgfx {
+
+// The minimum size (longest edge) for subtree cache. This prevents creating excessively small
+// mipmap levels that would be inefficient to cache.
+static constexpr int SUBTREE_CACHE_MIN_SIZE = 32;
+static std::atomic_bool AllowsEdgeAntialiasing = true;
+static std::atomic_bool AllowsGroupOpacity = false;
+
+/**
+ * Clips the canvas using the scroll rect. If the sublayer's Matrix contains 3D transformations or
+ * projection transformations, because this matrix has been merged into the Canvas, it can be
+ * directly completed through the clipping rectangle. Otherwise, the canvas will not contain this
+ * matrix information, and clipping needs to be done by transforming the Path.
+ */
+static void ClipScrollRect(Canvas* canvas, const Rect* scrollRect, const Matrix3D* transform,
+                           bool antiAlias) {
+  if (scrollRect == nullptr) {
+    return;
+  }
+
+  if (transform != nullptr) {
+    Path path;
+    path.addRect(*scrollRect);
+    path.transform3D(*transform);
+    canvas->clipPath(path, antiAlias);
+  } else {
+    canvas->clipRect(*scrollRect, antiAlias);
+  }
+}
+
+struct MaskData {
+  Path clipPath = {};
+  std::shared_ptr<MaskFilter> maskFilter = nullptr;
+};
+
+// Computes which layers need to be marked dirty during children reordering.
+// Uses LIS (Longest Increasing Subsequence) algorithm to minimize dirty area
+// by identifying layers that maintain their relative order.
+static void ComputeDirtyNodesForReordering(const std::vector<Layer*>& retainedChildren,
+                                           const std::vector<size_t>& newPositions,
+                                           std::vector<Layer*>* nodesToMarkDirty) {
+  size_t n = retainedChildren.size();
+  if (n == 0) {
+    return;
+  }
+
+  std::vector<size_t> lis;
+  std::vector<size_t> predecessors(n, SIZE_MAX);
+  std::vector<size_t> lisIndices;
+
+  for (size_t i = 0; i < n; ++i) {
+    size_t pos = newPositions[i];
+    auto it = std::lower_bound(lis.begin(), lis.end(), pos);
+    size_t insertPos = static_cast<size_t>(it - lis.begin());
+
+    if (it == lis.end()) {
+      lis.push_back(pos);
+      lisIndices.push_back(i);
+    } else {
+      *it = pos;
+      lisIndices[insertPos] = i;
+    }
+
+    if (insertPos > 0) {
+      predecessors[i] = lisIndices[insertPos - 1];
+    }
+  }
+
+  std::vector<bool> inLIS(n, false);
+  if (!lisIndices.empty()) {
+    size_t current = lisIndices.back();
+    while (current != SIZE_MAX) {
+      inLIS[current] = true;
+      current = predecessors[current];
+    }
+  }
+
+  for (size_t i = 0; i < n; ++i) {
+    if (!inLIS[i]) {
+      nodesToMarkDirty->push_back(retainedChildren[i]);
+    }
+  }
+}
+
+static std::optional<Rect> GetClipBounds(const Canvas* canvas) {
+  if (canvas == nullptr) {
+    return std::nullopt;
+  }
+  const auto clipBound = canvas->getTotalClipBounds();
+  auto clipRect = Rect::MakeEmpty();
+  auto surface = canvas->getSurface();
+  if (!clipBound.has_value()) {
+    if (!surface) {
+      return std::nullopt;
+    }
+    clipRect = Rect::MakeWH(surface->width(), surface->height());
+  } else {
+    clipRect = *clipBound;
+    if (surface && !clipRect.intersect(Rect::MakeWH(surface->width(), surface->height()))) {
+      return Rect::MakeEmpty();
+    }
+  }
+  if (clipRect.isEmpty()) {
+    return Rect::MakeEmpty();
+  }
+  auto invert = Matrix::I();
+  auto viewMatrix = canvas->getMatrix();
+  if (!viewMatrix.invert(&invert)) {
+    return Rect::MakeEmpty();
+  }
+  clipRect = invert.mapRect(clipRect);
+  clipRect.roundOut();
+  return clipRect;
+}
+
+static int GetMipmapCacheLongEdge(int maxSize, float contentScale, const Rect& layerBounds) {
+  auto maxBoundsSize = std::max(layerBounds.width(), layerBounds.height());
+  auto scaleBoundsSize = FloatRoundToInt(maxBoundsSize * contentScale);
+  if (scaleBoundsSize > maxSize) {
+    return scaleBoundsSize;
+  }
+  if (SUBTREE_CACHE_MIN_SIZE >= maxSize) {
+    return maxSize;
+  }
+  auto targetSize = std::max(scaleBoundsSize, SUBTREE_CACHE_MIN_SIZE);
+  auto currentLongEdge = maxSize;
+  while ((currentLongEdge >> 1) >= targetSize) {
+    currentLongEdge >>= 1;
+  }
+  return currentLongEdge;
+}
+
+/**
+ * Creates a 3D rendering context for compositing layers with 3D transformations.
+ * @param bounds The bounding rectangle of the 3D context in DisplayList coordinates.
+ */
+static std::shared_ptr<Layer3DContext> Create3DContext(const DrawArgs& args, Canvas* canvas,
+                                                       const Rect& bounds) {
+  if (args.context == nullptr) {
+    DEBUG_ASSERT(false);
+    return nullptr;
+  }
+
+  // The processing area of the compositor is consistent with the actual effective drawing area.
+  auto clipBounds = GetClipBounds(canvas);
+
+  auto validRenderRect = bounds;
+  // The clip bounds may be slightly larger than the dirty region.
+  if (clipBounds.has_value() && !validRenderRect.intersect(*clipBounds)) {
+    return nullptr;
+  }
+  // validRenderRect is in DisplayList coordinate system. Apply canvas scale to adapt to pixel
+  // coordinates, avoiding excessive scaling when rendering to offscreen texture which would affect
+  // the final visual quality.
+  auto contentScale = canvas->getMatrix().getMaxScale();
+  if (contentScale <= 0.0f) {
+    return nullptr;
+  }
+  validRenderRect.scale(contentScale, contentScale);
+  validRenderRect.roundOut();
+  if (validRenderRect.isEmpty()) {
+    return nullptr;
+  }
+
+  bool opaqueMode = args.opaqueContext != nullptr;
+  return Layer3DContext::Make(opaqueMode, args.context, validRenderRect, contentScale,
+                              args.dstColorSpace);
+}
+
+bool Layer::DefaultAllowsEdgeAntialiasing() {
+  return AllowsEdgeAntialiasing;
+}
+
+void Layer::SetDefaultAllowsEdgeAntialiasing(bool value) {
+  AllowsEdgeAntialiasing = value;
+}
+
+bool Layer::DefaultAllowsGroupOpacity() {
+  return AllowsGroupOpacity;
+}
+
+void Layer::SetDefaultAllowsGroupOpacity(bool value) {
+  AllowsGroupOpacity = value;
+}
+
+std::shared_ptr<Layer> Layer::Make() {
+  return std::shared_ptr<Layer>(new Layer());
+}
+
+Layer::~Layer() {
+  for (const auto& filter : _filters) {
+    DEBUG_ASSERT(filter != nullptr);
+    filter->detachFromLayer(this);
+  }
+  for (const auto& layerStyle : _layerStyles) {
+    DEBUG_ASSERT(layerStyle != nullptr);
+    layerStyle->detachFromLayer(this);
+  }
+  if (_mask) {
+    _mask->maskOwner = nullptr;
+  }
+  removeChildren();
+  delete contentBounds;
+}
+
+Layer::Layer() {
+  memset(&bitFields, 0, sizeof(bitFields));
+  bitFields.visible = true;
+  bitFields.allowsEdgeAntialiasing = AllowsEdgeAntialiasing;
+  bitFields.allowsGroupOpacity = AllowsGroupOpacity;
+  bitFields.blendMode = static_cast<uint8_t>(BlendMode::SrcOver);
+  bitFields.passThroughBackground = true;
+  bitFields.matrix3DIsAffine = true;
+}
+
+void Layer::setAlpha(float value) {
+  if (_alpha == value) {
+    return;
+  }
+  _alpha = value;
+  invalidateTransform();
+}
+
+void Layer::setBlendMode(BlendMode value) {
+  uint8_t uValue = static_cast<uint8_t>(value);
+  if (bitFields.blendMode == uValue) {
+    return;
+  }
+  bitFields.blendMode = uValue;
+  invalidateTransform();
+}
+
+void Layer::setPassThroughBackground(bool value) {
+  if (bitFields.passThroughBackground == value) {
+    return;
+  }
+  bitFields.passThroughBackground = value;
+  invalidateTransform();
+}
+
+Point Layer::position() const {
+  if (bitFields.matrix3DIsAffine) {
+    return {_matrix3D.getRowColumn(0, 3), _matrix3D.getRowColumn(1, 3)};
+  }
+
+  auto result = matrix3D().mapPoint(Vec3(0, 0, 0));
+  return {result.x, result.y};
+}
+
+void Layer::setPosition(const Point& value) {
+  if (bitFields.matrix3DIsAffine) {
+    if (_matrix3D.getTranslateX() == value.x && _matrix3D.getTranslateY() == value.y) {
+      return;
+    }
+    _matrix3D.setRowColumn(0, 3, value.x);
+    _matrix3D.setRowColumn(1, 3, value.y);
+  } else {
+    auto curPos = _matrix3D.mapPoint(Vec3(0, 0, 0));
+    if (FloatNearlyEqual(curPos.x, value.x) && FloatNearlyEqual(curPos.y, value.y)) {
+      return;
+    }
+    _matrix3D.postTranslate(value.x - curPos.x, value.y - curPos.y, 0);
+  }
+  invalidateTransform();
+}
+
+Matrix Layer::matrix() const {
+  auto affineMatrix = Matrix::I();
+  if (!bitFields.matrix3DIsAffine) {
+    return Matrix::I();
+  }
+  affineMatrix.setAll(_matrix3D.getRowColumn(0, 0), _matrix3D.getRowColumn(0, 1),
+                      _matrix3D.getRowColumn(0, 3), _matrix3D.getRowColumn(1, 0),
+                      _matrix3D.getRowColumn(1, 1), _matrix3D.getRowColumn(1, 3));
+  return affineMatrix;
+}
+
+void Layer::setMatrix(const Matrix& value) {
+  const Matrix3D value3D(value);
+  if (value3D == _matrix3D) {
+    return;
+  }
+  _matrix3D = value3D;
+  bitFields.matrix3DIsAffine = true;
+  invalidateTransform();
+}
+
+void Layer::setMatrix3D(const Matrix3D& value) {
+  if (value == _matrix3D) {
+    return;
+  }
+  _matrix3D = value;
+  bitFields.matrix3DIsAffine = Matrix3DUtils::IsMatrix3DAffine(value);
+  invalidateTransform();
+}
+
+void Layer::setPreserve3D(bool value) {
+  if (_preserve3D == value) {
+    return;
+  }
+  _preserve3D = value;
+  // Changing preserve3D alters the meaning of the layer's transform, so invalidate it.
+  invalidateTransform();
+}
+
+void Layer::setVisible(bool value) {
+  if (bitFields.visible == value) {
+    return;
+  }
+  bitFields.visible = value;
+  invalidateTransform();
+}
+
+void Layer::setAllowsEdgeAntialiasing(bool value) {
+  if (bitFields.allowsEdgeAntialiasing == value) {
+    return;
+  }
+  bitFields.allowsEdgeAntialiasing = value;
+  invalidateTransform();
+}
+
+void Layer::setAllowsGroupOpacity(bool value) {
+  if (bitFields.allowsGroupOpacity == value) {
+    return;
+  }
+  bitFields.allowsGroupOpacity = value;
+  invalidateTransform();
+}
+
+void Layer::setFilters(const std::vector<std::shared_ptr<LayerFilter>>& value) {
+  if (_filters.size() == value.size() &&
+      std::equal(_filters.begin(), _filters.end(), value.begin())) {
+    return;
+  }
+  for (const auto& filter : _filters) {
+    DEBUG_ASSERT(filter != nullptr);
+    filter->detachFromLayer(this);
+  }
+  _filters.clear();
+  for (const auto& filter : value) {
+    if (filter == nullptr) {
+      continue;
+    }
+    filter->attachToLayer(this);
+    _filters.push_back(filter);
+  }
+  invalidateSubtree();
+  invalidateTransform();
+}
+
+void Layer::setMask(std::shared_ptr<Layer> value) {
+  if (value.get() == this) {
+    return;
+  }
+  if (_mask == value) {
+    return;
+  }
+  if (value && value->maskOwner) {
+    value->maskOwner->setMask(nullptr);
+    value->maskOwner = nullptr;
+  }
+  if (_mask) {
+    _mask->maskOwner = nullptr;
+    _mask->invalidateTransform();
+  }
+  _mask = std::move(value);
+  if (_mask) {
+    _mask->maskOwner = this;
+    _mask->invalidateTransform();
+  }
+  invalidateTransform();
+}
+
+void Layer::setMaskType(LayerMaskType value) {
+  uint8_t uValue = static_cast<uint8_t>(value);
+  if (bitFields.maskType == uValue) {
+    return;
+  }
+  bitFields.maskType = uValue;
+  if (_mask) {
+    invalidateTransform();
+  }
+}
+
+void Layer::setScrollRect(const Rect& rect) {
+  if ((_scrollRect && *_scrollRect == rect) || (!_scrollRect && rect.isEmpty())) {
+    return;
+  }
+  if (rect.isEmpty()) {
+    _scrollRect = nullptr;
+  } else {
+    _scrollRect = std::make_unique<Rect>(rect);
+  }
+  invalidateTransform();
+}
+
+Layer* Layer::root() const {
+  return _root;
+}
+
+void Layer::setLayerStyles(const std::vector<std::shared_ptr<LayerStyle>>& value) {
+  if (_layerStyles.size() == value.size() &&
+      std::equal(_layerStyles.begin(), _layerStyles.end(), value.begin())) {
+    return;
+  }
+  for (const auto& layerStyle : _layerStyles) {
+    DEBUG_ASSERT(layerStyle != nullptr);
+    layerStyle->detachFromLayer(this);
+  }
+  _layerStyles.clear();
+  for (const auto& layerStyle : value) {
+    if (layerStyle == nullptr) {
+      continue;
+    }
+    layerStyle->attachToLayer(this);
+    _layerStyles.push_back(layerStyle);
+  }
+  invalidateSubtree();
+  invalidateTransform();
+}
+
+bool Layer::addChild(std::shared_ptr<Layer> child) {
+  if (!child) {
+    return false;
+  }
+  auto index = _children.size();
+  if (child->_parent == this) {
+    index--;
+  }
+  return addChildAt(child, static_cast<int>(index));
+}
+
+bool Layer::addChildAt(std::shared_ptr<Layer> child, int index) {
+  if (!child) {
+    return false;
+  }
+  if (child.get() == this) {
+    LOGE("addChildAt() The child is the same as the parent.");
+    return false;
+  } else if (child->doContains(this)) {
+    LOGE("addChildAt() The child is already a parent of the parent.");
+    return false;
+  } else if (child->_root == child.get()) {
+    LOGE("A root layer cannot be added as a child to another layer.");
+    return false;
+  }
+  if (child->_parent == this) {
+    return setChildIndex(child, index);
+  }
+  child->removeFromParent();
+  _children.insert(_children.begin() + index, child);
+  child->_parent = this;
+  child->onAttachToRoot(_root);
+  child->invalidateTransform();
+  invalidateDescendents();
+  return true;
+}
+
+bool Layer::contains(std::shared_ptr<Layer> child) const {
+  return doContains(child.get());
+}
+
+std::shared_ptr<Layer> Layer::getChildByName(const std::string& name) {
+  for (const auto& child : _children) {
+    if (child->name() == name) {
+      return child;
+    }
+  }
+  return nullptr;
+}
+
+int Layer::getChildIndex(std::shared_ptr<Layer> child) const {
+  return doGetChildIndex(child.get());
+}
+
+std::vector<std::shared_ptr<Layer>> Layer::getLayersUnderPoint(float x, float y) {
+  std::vector<std::shared_ptr<Layer>> results;
+  getLayersUnderPointInternal(x, y, &results);
+  return results;
+}
+
+void Layer::removeFromParent() {
+  if (!_parent) {
+    return;
+  }
+  _parent->removeChildAt(_parent->doGetChildIndex(this));
+}
+
+std::shared_ptr<Layer> Layer::removeChildAt(int index) {
+  if (index < 0 || static_cast<size_t>(index) >= _children.size()) {
+    LOGE("The supplied index is out of bounds.");
+    return nullptr;
+  }
+  auto child = _children[static_cast<size_t>(index)];
+  child->_parent = nullptr;
+  child->onDetachFromRoot();
+  _children.erase(_children.begin() + index);
+  if (_root) {
+    _root->invalidateRect(child->renderBounds);
+    child->renderBounds = {};
+  }
+  invalidateDescendents();
+  return child;
+}
+
+void Layer::removeChildren(int beginIndex, int endIndex) {
+  if (_children.empty()) {
+    return;
+  }
+  if (beginIndex < 0 || static_cast<size_t>(beginIndex) >= _children.size()) {
+    LOGE("The supplied beginIndex is out of bounds.");
+    return;
+  }
+  if (endIndex < 0 || static_cast<size_t>(endIndex) >= _children.size()) {
+    endIndex = static_cast<int>(_children.size()) - 1;
+  }
+  for (int i = endIndex; i >= beginIndex; --i) {
+    removeChildAt(i);
+  }
+}
+
+bool Layer::setChildIndex(std::shared_ptr<Layer> child, int index) {
+  if (index < 0 || static_cast<size_t>(index) >= _children.size()) {
+    index = static_cast<int>(_children.size()) - 1;
+  }
+  auto oldIndex = getChildIndex(child);
+  if (oldIndex < 0) {
+    LOGE("The supplied layer must be a child layer of the caller.");
+    return false;
+  }
+  if (oldIndex == index) {
+    return true;
+  }
+  _children.erase(_children.begin() + oldIndex);
+  _children.insert(_children.begin() + index, child);
+  if (_root) {
+    // Immediately invalidate the old render bounds, as this may affect the background of the above
+    // layer styles.
+    _root->invalidateRect(child->renderBounds);
+    child->renderBounds = {};
+  }
+  child->invalidateTransform();
+  invalidateDescendents();
+  return true;
+}
+
+void Layer::setChildren(const std::vector<std::shared_ptr<Layer>>& children) {
+  std::vector<std::shared_ptr<Layer>> validChildren;
+  std::unordered_map<Layer*, size_t> newIndexMap;
+
+  for (const auto& child : children) {
+    if (child == nullptr || newIndexMap.find(child.get()) != newIndexMap.end()) {
+      continue;
+    }
+    if (child.get() == this) {
+      LOGE("setChildren() The child is the same as the parent.");
+      continue;
+    }
+    if (child->doContains(this)) {
+      LOGE("setChildren() The child is already a parent of the parent.");
+      continue;
+    }
+    if (child->_root == child.get()) {
+      LOGE("A root layer cannot be added as a child to another layer.");
+      continue;
+    }
+    newIndexMap[child.get()] = validChildren.size();
+    validChildren.push_back(child);
+  }
+
+  if (_children == validChildren) {
+    return;
+  }
+
+  auto oldChildren = _children;
+  std::vector<Layer*> nodesToMarkDirty;
+  std::vector<Layer*> retainedChildren;
+  std::vector<size_t> newPositions;
+  std::unordered_set<Layer*> oldChildrenSet;
+
+  for (const auto& child : oldChildren) {
+    auto* ptr = child.get();
+    oldChildrenSet.insert(ptr);
+    auto it = newIndexMap.find(ptr);
+    if (it == newIndexMap.end()) {
+      nodesToMarkDirty.push_back(ptr);
+      ptr->_parent = nullptr;
+      ptr->onDetachFromRoot();
+      if (_root) {
+        _root->invalidateRect(ptr->renderBounds);
+        ptr->renderBounds = {};
+      }
+    } else {
+      retainedChildren.push_back(ptr);
+      newPositions.push_back(it->second);
+    }
+  }
+
+  ComputeDirtyNodesForReordering(retainedChildren, newPositions, &nodesToMarkDirty);
+
+  std::vector<Layer*> addedChildren;
+  for (const auto& child : validChildren) {
+    if (oldChildrenSet.find(child.get()) == oldChildrenSet.end()) {
+      child->removeFromParent();
+      addedChildren.push_back(child.get());
+    }
+  }
+
+  _children = std::move(validChildren);
+
+  for (auto* child : addedChildren) {
+    nodesToMarkDirty.push_back(child);
+    child->_parent = this;
+    child->onAttachToRoot(_root);
+  }
+
+  for (auto* dirtyNode : nodesToMarkDirty) {
+    dirtyNode->invalidateTransform();
+  }
+
+  invalidateDescendents();
+}
+
+bool Layer::replaceChild(std::shared_ptr<Layer> oldChild, std::shared_ptr<Layer> newChild) {
+  auto index = getChildIndex(oldChild);
+  if (index < 0) {
+    LOGE("The supplied layer must be a child layer of the caller.");
+    return false;
+  }
+  if (!addChildAt(newChild, index)) {
+    return false;
+  }
+  oldChild->removeFromParent();
+  invalidateDescendents();
+  return true;
+}
+
+Rect Layer::getBounds(const Layer* targetCoordinateSpace, bool computeTightBounds) {
+  auto matrix = getRelativeMatrix3D(targetCoordinateSpace);
+  return getBoundsInternal(matrix, computeTightBounds);
+}
+
+Rect Layer::getBoundsInternal(const Matrix3D& coordinateMatrix, bool computeTightBounds) {
+  // Non-leaf nodes in a 3D rendering context layer tree must preserve the 3D state of their
+  // sublayers, and cannot reuse the localBounds cache that has been flattened to the layer's local
+  // coordinate system.
+  if (computeTightBounds || bitFields.dirtyDescendents || canPreserve3D()) {
+    return computeBounds(coordinateMatrix, computeTightBounds);
+  }
+  if (!localBounds) {
+    localBounds = std::make_unique<Rect>(computeBounds(Matrix3D::I(), computeTightBounds));
+  }
+  return coordinateMatrix.mapRect(*localBounds);
+}
+
+static Rect ComputeContentBounds(const LayerContent& content, const Rect& contentBounds,
+                                 const Matrix3D& coordinateMatrix, bool applyMatrixAtEnd,
+                                 bool computeTightBounds) {
+  auto contentMatrix = applyMatrixAtEnd ? Matrix3D::I() : coordinateMatrix;
+  if (!computeTightBounds) {
+    return contentMatrix.mapRect(contentBounds);
+  }
+
+  if (Matrix3DUtils::IsMatrix3DAffine(contentMatrix)) {
+    return content.getTightBounds(Matrix3DUtils::GetMayLossyAffineMatrix(contentMatrix));
+  }
+  auto bounds = content.getTightBounds(Matrix::I());
+  return contentMatrix.mapRect(bounds);
+}
+
+Rect Layer::computeBounds(const Matrix3D& coordinateMatrix, bool computeTightBounds,
+                          bool excludeEffects) {
+  auto canPreserve3D = this->canPreserve3D();
+  bool hasEffects = !excludeEffects && (!_layerStyles.empty() || !_filters.empty());
+  // When preserving 3D, the matrix must be passed down to preserve 3D state.
+  // Otherwise, when has effects, compute in local coordinates first, then apply matrix at end.
+  bool isAffine = Matrix3DUtils::IsMatrix3DAffine(coordinateMatrix);
+  bool applyMatrixAtEnd = !canPreserve3D && (hasEffects || !isAffine);
+
+  Rect bounds = {};
+  if (auto content = getContent()) {
+    auto contentBounds = content->getBounds();
+    bool behindCamera =
+        !isAffine && Matrix3DUtils::IsRectBehindCamera(contentBounds, coordinateMatrix);
+    if (!behindCamera) {
+      auto computedBounds = ComputeContentBounds(*content, contentBounds, coordinateMatrix,
+                                                 applyMatrixAtEnd, computeTightBounds);
+      bounds.join(computedBounds);
+    }
+  }
+
+  for (const auto& child : _children) {
+    // Alpha does not need to be checked; alpha == 0 is still valid.
+    if (!child->visible() || child->maskOwner) {
+      continue;
+    }
+    auto childMatrix = child->getMatrixWithScrollRect();
+    if (!canPreserve3D) {
+      childMatrix.setRow(2, {0, 0, 1, 0});
+    }
+    childMatrix.postConcat(applyMatrixAtEnd ? Matrix3D::I() : coordinateMatrix);
+    auto childBounds = child->getBoundsInternal(childMatrix, computeTightBounds);
+    if (child->_scrollRect) {
+      auto relativeScrollRect = childMatrix.mapRect(*child->_scrollRect);
+      if (!childBounds.intersect(relativeScrollRect)) {
+        continue;
+      }
+    }
+    if (child->hasValidMask()) {
+      auto maskRelativeMatrix = child->_mask->getRelativeMatrix3D(child.get());
+      maskRelativeMatrix.postConcat(childMatrix);
+      auto maskBounds = child->_mask->getBoundsInternal(maskRelativeMatrix, computeTightBounds);
+      if (!childBounds.intersect(maskBounds)) {
+        continue;
+      }
+    }
+    bounds.join(childBounds);
+  }
+
+  if (hasEffects) {
+    // Filters and styles disable 3D context ability, so this block is unreachable for 3D context.
+    DEBUG_ASSERT(!canPreserve3D);
+    auto layerBounds = bounds;
+    for (auto& layerStyle : _layerStyles) {
+      DEBUG_ASSERT(layerStyle != nullptr);
+      auto styleBounds = layerStyle->filterBounds(layerBounds, 1.0f);
+      bounds.join(styleBounds);
+    }
+    for (auto& filter : _filters) {
+      DEBUG_ASSERT(filter != nullptr);
+      bounds = filter->filterBounds(bounds, 1.0f);
+    }
+  }
+
+  if (applyMatrixAtEnd) {
+    if (!isAffine && Matrix3DUtils::IsRectBehindCamera(bounds, coordinateMatrix)) {
+      return {};
+    }
+    bounds = coordinateMatrix.mapRect(bounds);
+  }
+  return bounds;
+}
+
+Point Layer::globalToLocal(const Point& globalPoint) const {
+  auto matrix = getGlobalMatrix().asMatrix();
+  Matrix inversedMatrix;
+  if (!matrix.invert(&inversedMatrix)) {
+    DEBUG_ASSERT(false);
+    return Point::Make(0, 0);
+  }
+  Point result = globalPoint;
+  inversedMatrix.mapPoints(&result, 1);
+  return result;
+}
+
+Point Layer::localToGlobal(const Point& localPoint) const {
+  auto globalMatrix = getGlobalMatrix();
+  auto result = globalMatrix.mapPoint({localPoint.x, localPoint.y, 0});
+  return {result.x, result.y};
+}
+
+Matrix Layer::getRelativeMatrix(const Layer* target) const {
+  return getRelativeMatrix3D(target).asMatrix();
+}
+
+Matrix3D Layer::getRelativeMatrix3D(const Layer* target) const {
+  if (target == nullptr || target == this) {
+    return {};
+  }
+  auto targetMatrix = target->getGlobalMatrix();
+  Matrix3D targetInverseMatrix = {};
+  if (!targetMatrix.invert(&targetInverseMatrix)) {
+    return {};
+  }
+  Matrix3D matrix = getGlobalMatrix();
+  matrix.postConcat(targetInverseMatrix);
+  return matrix;
+}
+
+bool Layer::hitTestPoint(float x, float y, bool shapeHitTest) {
+  if (auto content = getContent()) {
+    Point localPoint = globalToLocal(Point::Make(x, y));
+    if (shapeHitTest) {
+      if (content->hitTestPoint(localPoint.x, localPoint.y)) {
+        return true;
+      }
+    } else {
+      if (content->getBounds().contains(localPoint.x, localPoint.y)) {
+        return true;
+      }
+    }
+  }
+
+  for (const auto& childLayer : _children) {
+    // Alpha does not need to be checked; alpha == 0 is still valid.
+    if (!childLayer->visible() || childLayer->maskOwner) {
+      continue;
+    }
+
+    if (nullptr != childLayer->_scrollRect) {
+      auto pointInChildSpace = childLayer->globalToLocal(Point::Make(x, y));
+      if (!childLayer->_scrollRect->contains(pointInChildSpace.x, pointInChildSpace.y)) {
+        continue;
+      }
+    }
+
+    if (nullptr != childLayer->_mask) {
+      if (!childLayer->_mask->hitTestPoint(x, y, shapeHitTest)) {
+        continue;
+      }
+    }
+
+    if (childLayer->hitTestPoint(x, y, shapeHitTest)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+static Rect GetClippedBounds(const Rect& bounds, const Canvas* canvas) {
+  DEBUG_ASSERT(canvas != nullptr);
+  auto clippedBounds = bounds;
+  auto clipRect = GetClipBounds(canvas);
+  if (!clipRect.has_value()) {
+    return clippedBounds;
+  }
+  if (!clippedBounds.intersect(*clipRect)) {
+    return Rect::MakeEmpty();
+  }
+  clippedBounds.roundOut();
+  return clippedBounds;
+}
+
+void Layer::draw(Canvas* canvas, float alpha, BlendMode blendMode) {
+  if (canvas == nullptr || alpha <= 0) {
+    return;
+  }
+
+  auto surface = canvas->getSurface();
+  DrawArgs args = {};
+  Context* context = nullptr;
+
+  auto bounds = getBounds();
+  auto clippedBounds = GetClippedBounds(bounds, canvas);
+  if (clippedBounds.isEmpty()) {
+    return;
+  }
+  auto localToGlobalMatrix = getGlobalMatrix();
+  auto globalToLocalMatrix = Matrix3D::I();
+  bool canInvert = localToGlobalMatrix.invert(&globalToLocalMatrix);
+
+  Rect renderRect = {};
+  std::vector<Rect> renderRectsVec = {};
+  if (_root && canInvert) {
+    _root->updateRenderBounds();
+    renderRect = localToGlobalMatrix.mapRect(clippedBounds);
+    renderRectsVec = {renderRect};
+    args.renderRects = &renderRectsVec;
+  }
+
+  if (surface) {
+    args.dstColorSpace = surface->colorSpace();
+    context = surface->getContext();
+    if (!(surface->renderFlags() & RenderFlags::DisableCache)) {
+      args.context = context;
+    }
+  }
+
+  // Capture pass — only when this layer or descendants have Background-sourced styles. Disabled
+  // in 3D subtrees. Requires a GPU context; on picture-canvas paths the capture is skipped and
+  // the consumer falls back to on-the-fly synthesis (signalled by passing a null snapshot map).
+  BackgroundSnapshotMap snapshotMap = {};
+  BackgroundSnapshotMap* snapshotsPtr = nullptr;
+  bool needBackground = canInvert && !canPreserve3D() && hasBackgroundStyle();
+  if (needBackground && context != nullptr) {
+    auto rectForDraw = maxBackgroundOutset > 0.0f ? clippedBounds : bounds;
+    Matrix backgroundMatrix = canvas->getMatrix();
+    Rect drawRect = backgroundMatrix.mapRect(rectForDraw);
+    if (_root != nullptr) {
+      // Capture replays from _root, so bgCanvas accumulates globalMatrix when reaching this
+      // layer. But Layer::draw() itself paints via drawLayer without concatenating globalMatrix,
+      // so the device position is just outerCanvas * self-local. Compose the viewMatrix as
+      // outerCanvas * invert(globalMatrix) so that surfaceMatrix * globalMatrix collapses back
+      // to outerCanvas, aligning capture and consume in the same device-pixel space.
+      // drawRect stays at outerCanvas.mapRect(rectForDraw) (the device-pixel layer rect)
+      // computed above, since BackgroundSource uses it to size the surface.
+      backgroundMatrix.preConcat(globalToLocalMatrix.asMatrix());
+    }
+    if (auto bgSource = createBackgroundSource(context, drawRect, backgroundMatrix,
+                                               rectForDraw == bounds, args.dstColorSpace)) {
+      // Replay from _root so ancestor matrices apply; orphan layers replay from themselves.
+      // The capture rect is in the captureRoot's local coordinate space: world (root-local) when
+      // rooted, or this layer's local bounds when orphan.
+      Layer* captureRoot = _root ? _root : this;
+      Rect captureRect = _root ? renderRect : clippedBounds;
+      BackgroundCapturer::Run(captureRoot, args, std::move(bgSource), &snapshotMap, {captureRect});
+      snapshotsPtr = &snapshotMap;
+    }
+  }
+
+  // Consume pass — normal render. NoOp when there's no background style so stray ones silently
+  // skip (same as contour / 3D subtrees). A null snapshot map signals the picture-canvas path,
+  // which makes the consumer synthesize backdrops on the fly via PictureRecorder.
+  AutoCanvasRestore autoRestore(canvas);
+  BackgroundConsumer consumer(snapshotsPtr);
+  BackgroundHandler* handler =
+      needBackground ? static_cast<BackgroundHandler*>(&consumer) : BackgroundHandler::NoOp();
+  DrawArgs drawArgs = args;
+  drawArgs.backgroundHandler = handler;
+  // Check if the current layer needs to start a 3D context. Since Layer::draw is called directly
+  // without going through a parent layer's drawChildren, 3D context handling must be done here.
+  if (canPreserve3D()) {
+    drawByStarting3DContext(drawArgs, canvas, getMatrixWithScrollRect(), &Layer::drawLayer, alpha);
+  } else {
+    drawLayer(drawArgs, canvas, alpha, blendMode);
+  }
+}
+
+void Layer::invalidateContent() {
+  if (bitFields.dirtyContent) {
+    return;
+  }
+  bitFields.dirtyContent = true;
+  bitFields.dirtyContentBounds = true;
+  invalidateDescendents();
+}
+
+void Layer::invalidateTransform() {
+  if (bitFields.dirtyTransform) {
+    return;
+  }
+  bitFields.dirtyTransform = true;
+  invalidate();
+}
+
+void Layer::invalidateDescendents() {
+  if (bitFields.dirtyDescendents) {
+    return;
+  }
+  bitFields.dirtyDescendents = true;
+  invalidateSubtree();
+  invalidate();
+}
+
+void Layer::invalidate() {
+  if (_parent) {
+    _parent->invalidateDescendents();
+  }
+  if (maskOwner) {
+    maskOwner->invalidateTransform();
+  }
+}
+
+void Layer::onUpdateContent(LayerRecorder*) {
+}
+
+void Layer::attachProperty(LayerProperty* property) {
+  if (property) {
+    property->attachToLayer(this);
+  }
+}
+
+void Layer::detachProperty(LayerProperty* property) {
+  if (property) {
+    property->detachFromLayer(this);
+  }
+}
+
+std::optional<StyledShape> Layer::onGetContentShape() {
+  auto* content = getContent();
+  if (content == nullptr) {
+    return std::nullopt;
+  }
+  auto bounds = content->getTightBounds(Matrix::I());
+  if (bounds.isEmpty()) {
+    return std::nullopt;
+  }
+  Path path = {};
+  path.addRect(bounds);
+  return StyledShape::Make(Shape::MakeFrom(path), StyledShapeType::Fill, 0, StrokeAlign::Center);
+}
+
+void Layer::onAttachToRoot(RootLayer* rootLayer) {
+  _root = rootLayer;
+  for (auto& child : _children) {
+    child->onAttachToRoot(rootLayer);
+  }
+}
+
+void Layer::onDetachFromRoot() {
+  _root = nullptr;
+  for (auto& child : _children) {
+    child->onDetachFromRoot();
+  }
+}
+
+int Layer::doGetChildIndex(const Layer* child) const {
+  int index = 0;
+  for (auto& layer : _children) {
+    if (layer.get() == child) {
+      return index;
+    }
+    index++;
+  }
+  return -1;
+}
+
+bool Layer::doContains(const Layer* child) const {
+  auto target = child;
+  while (target) {
+    if (target == this) {
+      return true;
+    }
+    target = target->_parent;
+  }
+  return false;
+}
+
+Matrix3D Layer::getGlobalMatrix() const {
+  // The global matrix transforms the layer's local coordinate space to the coordinate space of its
+  // top-level parent layer. This means the top-level parent layer's own matrix is not included in
+  // the global matrix.
+  Matrix3D matrix = {};
+  auto layer = this;
+  while (layer->_parent) {
+    // Check if the child layer is within a 3D rendering context. If not, adapt the matrix to
+    // ensure the z-component of layer rect vertex coordinates remains unchanged, so the child layer
+    // is projected onto the current layer first, then the accumulated matrix transformation is
+    // applied. If within, directly concatenate the child layer matrix to preserve its 3D state.
+    if (!layer->canPreserve3D()) {
+      matrix.setRow(2, {0, 0, 1, 0});
+    }
+    matrix.postConcat(layer->getMatrixWithScrollRect());
+    layer = layer->_parent;
+  }
+  return matrix;
+}
+
+Matrix3D Layer::getMatrixWithScrollRect() const {
+  auto matrix = _matrix3D;
+  if (_scrollRect) {
+    matrix.preTranslate(-_scrollRect->left, -_scrollRect->top, 0);
+  }
+  return matrix;
+}
+
+LayerContent* Layer::getContent() {
+  if (bitFields.dirtyContent) {
+    LayerRecorder recorder = {};
+    onUpdateContent(&recorder);
+    layerContent = recorder.finishRecording();
+    bitFields.dirtyContent = false;
+  }
+  return layerContent.get();
+}
+
+std::shared_ptr<Image> Layer::applyFilters(std::shared_ptr<Image> image, float contentScale,
+                                           const Rect& contentBounds, Point* offset) {
+  if (!image || _filters.empty()) {
+    return image;
+  }
+  // Each filter may shift the output image origin by filterOffset. Subsequent filters receive an
+  // image in the shifted coordinate system, so contentBounds must be translated by -filterOffset
+  // before being passed to the next filter, otherwise geometry-anchored filters would sample in a
+  // stale coordinate system.
+  Rect currentContentBounds = contentBounds;
+  for (const auto& layerFilter : _filters) {
+    DEBUG_ASSERT(layerFilter != nullptr);
+    Point filterOffset = {};
+    image = layerFilter->filterImage(std::move(image), contentScale, currentContentBounds,
+                                     &filterOffset);
+    if (!image) {
+      return nullptr;
+    }
+    if (offset) {
+      offset->offset(filterOffset.x, filterOffset.y);
+    }
+    currentContentBounds.offset(-filterOffset.x, -filterOffset.y);
+  }
+  return image;
+}
+
+Rect Layer::mapContentBoundsToImage(float scale, const Rect& imageBounds) {
+  auto layerBounds = computeBounds(Matrix3D::I(), false, /*excludeEffects=*/true);
+  return Rect::MakeXYWH(layerBounds.left * scale - imageBounds.left,
+                        layerBounds.top * scale - imageBounds.top, layerBounds.width() * scale,
+                        layerBounds.height() * scale);
+}
+
+Rect Layer::mapOutputBoundsToInput(const Rect& srcRect, float contentScale) {
+  auto bounds = srcRect;
+  for (auto it = _filters.rbegin(); it != _filters.rend(); ++it) {
+    DEBUG_ASSERT(*it != nullptr);
+    bounds = (*it)->filterBounds(bounds, contentScale, MapDirection::Reverse);
+  }
+  return bounds;
+}
+
+bool Layer::drawLayer(const DrawArgs& args, Canvas* canvas, float alpha, BlendMode blendMode) {
+  DEBUG_ASSERT(canvas != nullptr);
+  auto contentScale = canvas->getMatrix().getMaxScale();
+  if (FloatNearlyZero(contentScale)) {
+    return true;
+  }
+  if (args.renderRects != nullptr && !args.renderRects->empty() && !renderBounds.isEmpty()) {
+    bool anyHit = false;
+    for (const auto& rect : *args.renderRects) {
+      if (Rect::Intersects(rect, renderBounds)) {
+        anyHit = true;
+        break;
+      }
+    }
+    if (!anyHit) {
+      return true;
+    }
+  }
+  std::shared_ptr<MaskFilter> maskFilter = nullptr;
+  if (!prepareMask(args, canvas, &maskFilter)) {
+    return true;
+  }
+  bool needsMaskFilter = maskFilter != nullptr;
+  if (canUseSubtreeCache(args, blendMode) &&
+      drawWithSubtreeCache(args, canvas, alpha, blendMode, maskFilter)) {
+    return true;
+  }
+
+  // For non-leaf layers in a 3D rendering context layer tree, direct rendering is always used.
+  // Offscreen constraints (filters, styles, masks) are already checked by the parent layer at call
+  // site. Group opacity, blend mode, and passThroughBackground have lower priority than enabling
+  // 3D rendering context and are ignored during drawing.
+  bool needsOffscreen = false;
+  if (!canPreserve3D()) {
+    needsOffscreen = blendMode != BlendMode::SrcOver || !bitFields.passThroughBackground ||
+                     (alpha < 1.0f && bitFields.allowsGroupOpacity) ||
+                     (!_filters.empty() && !args.excludeEffects) || needsMaskFilter;
+  }
+  if (needsOffscreen) {
+    // Content and children are rendered together in an offscreen buffer.
+    drawOffscreen(args, canvas, alpha, blendMode, maskFilter);
+  } else {
+    // Content and children are rendered independently.
+    drawDirectly(args, canvas, alpha);
+  }
+  return true;
+}
+
+bool Layer::prepareMask(const DrawArgs& args, Canvas* canvas,
+                        std::shared_ptr<MaskFilter>* maskFilter) {
+  if (!hasValidMask()) {
+    return true;
+  }
+  auto clipBounds = GetClipBounds(canvas);
+  auto contentScale = canvas->getMatrix().getMaxScale();
+  auto maskData = getMaskData(args, contentScale, clipBounds);
+  if (maskData.maskFilter == nullptr) {
+    if (maskData.clipPath.isEmpty() && !maskData.clipPath.isInverseFillType()) {
+      return false;
+    }
+    canvas->clipPath(maskData.clipPath, _mask->bitFields.allowsEdgeAntialiasing);
+    return true;
+  }
+  if (maskFilter) {
+    *maskFilter = maskData.maskFilter;
+  }
+  return true;
+}
+
+std::shared_ptr<Picture> Layer::getMaskPicture(const DrawArgs& args, bool isContourMode,
+                                               float scale, const Matrix3D& relativeMatrix3D) {
+  // Note: Does not use layerClipBounds here. Using clipBounds may cause PathOp errors when
+  // extracting maskPath from the picture, resulting in incorrect clip regions.
+  DrawArgs maskArgs = args;
+  maskArgs.excludeEffects |= isContourMode;
+  maskArgs.backgroundHandler = BackgroundHandler::NoOp();
+  auto maskCanPreserve3D = _mask->canPreserve3D();
+  // When mask enables 3D context, the full 3D relative matrix is handled by the 3D context.
+  // Otherwise, use the 2D projection of the relative matrix on canvas.
+  auto canvasMatrix = relativeMatrix3D.asMatrix();
+  if (isContourMode) {
+    OpaqueContext opaqueContext;
+    auto* contourCanvas = opaqueContext.beginRecording();
+    contourCanvas->scale(scale, scale);
+    maskArgs.opaqueContext = &opaqueContext;
+    if (maskCanPreserve3D) {
+      _mask->drawByStarting3DContext(maskArgs, contourCanvas, relativeMatrix3D, &Layer::drawContour,
+                                     _mask->_alpha);
+    } else {
+      contourCanvas->concat(canvasMatrix);
+      _mask->drawContour(maskArgs, contourCanvas, _mask->_alpha, BlendMode::SrcOver);
+    }
+    return opaqueContext.finishRecordingAsPicture();
+  }
+  PictureRecorder recorder = {};
+  auto* recordingCanvas = recorder.beginRecording();
+  recordingCanvas->scale(scale, scale);
+  if (maskCanPreserve3D) {
+    _mask->drawByStarting3DContext(maskArgs, recordingCanvas, relativeMatrix3D, &Layer::drawLayer,
+                                   _mask->_alpha);
+  } else {
+    recordingCanvas->concat(canvasMatrix);
+    _mask->drawLayer(maskArgs, recordingCanvas, _mask->_alpha, BlendMode::SrcOver);
+  }
+  return recorder.finishRecordingAsPicture();
+}
+
+MaskData Layer::getMaskData(const DrawArgs& args, float scale,
+                            const std::optional<Rect>& layerClipBounds) {
+  DEBUG_ASSERT(_mask != nullptr);
+  DEBUG_ASSERT(args.render3DContext == nullptr);
+  auto maskType = static_cast<LayerMaskType>(bitFields.maskType);
+  auto isContourMode = maskType == LayerMaskType::Contour;
+
+  auto relativeMatrix3D = _mask->getRelativeMatrix3D(this);
+  auto maskPicture = getMaskPicture(args, isContourMode, scale, relativeMatrix3D);
+  if (maskPicture == nullptr) {
+    return {};
+  }
+
+  bool needLuminance = maskType == LayerMaskType::Luminance;
+  if (!needLuminance) {
+    Path maskPath = {};
+    if (MaskContext::GetMaskPath(maskPicture, &maskPath)) {
+      maskPath.transform(Matrix::MakeScale(1.0f / scale, 1.0f / scale));
+      return {std::move(maskPath), nullptr};
+    }
+  }
+
+  Rect maskBounds = maskPicture->getBounds();
+  if (layerClipBounds.has_value()) {
+    auto scaledClipBounds = *layerClipBounds;
+    scaledClipBounds.scale(scale, scale);
+    if (!maskBounds.intersect(scaledClipBounds)) {
+      return {};
+    }
+  }
+  Point maskImageOffset = {};
+  auto maskContentImage =
+      ToImageWithOffset(std::move(maskPicture), &maskImageOffset, &maskBounds, args.dstColorSpace);
+  if (maskContentImage == nullptr) {
+    return {};
+  }
+  if (needLuminance) {
+    maskContentImage =
+        maskContentImage->makeWithFilter(ImageFilter::ColorFilter(ColorFilter::Luma()));
+  }
+  auto maskMatrix = Matrix::MakeScale(1.0f / scale, 1.0f / scale);
+  maskMatrix.preTranslate(maskImageOffset.x, maskImageOffset.y);
+
+  auto shader = Shader::MakeImageShader(maskContentImage, TileMode::Decal, TileMode::Decal);
+  if (shader) {
+    shader = shader->makeWithMatrix(maskMatrix);
+  }
+  return {{}, MaskFilter::MakeShader(shader)};
+}
+
+std::shared_ptr<Image> Layer::getContentContourImage(const DrawArgs& args, float contentScale,
+                                                     Point* offset, bool* contourMatchesContent) {
+  if (FloatNearlyZero(contentScale)) {
+    return nullptr;
+  }
+  bool allMatch = true;
+  OpaqueContext opaqueContext;
+  auto* contourCanvas = opaqueContext.beginRecording();
+  contourCanvas->scale(contentScale, contentScale);
+  auto contourArgs = args;
+  contourArgs.opaqueContext = &opaqueContext;
+  // Contour recording is an intermediate artifact — skip background capture / consume.
+  contourArgs.backgroundHandler = BackgroundHandler::NoOp();
+  // Detach from any active 3D rendering context: the contour image we are about to record is the
+  // merged self + descendants outline used as a layerStyle / mask source, not a node within the
+  // 3D BSP. Without this clear, drawContourInternal's "skip children when rasterizing a
+  // preserve3D middle node" guard would prune descendants and produce an incomplete contour.
+  contourArgs.render3DContext = nullptr;
+  if (!drawContourInternal(contourArgs, contourCanvas, true)) {
+    allMatch = false;
+  }
+  auto picture = opaqueContext.finishRecordingAsPicture();
+  auto imageOffset = Point::Zero();
+  auto image = ToImageWithOffset(std::move(picture), &imageOffset, nullptr, args.dstColorSpace);
+  if (offset) {
+    *offset = imageOffset;
+  }
+  if (contourMatchesContent) {
+    *contourMatchesContent = allMatch;
+  }
+  return image;
+}
+
+bool Layer::shouldPassThroughBackground(BlendMode blendMode) const {
+  // Pass-through background is only possible when:
+  // 1. The feature is enabled
+  if (!bitFields.passThroughBackground) {
+    return false;
+  }
+
+  // 2. Subtree has blend modes that need background information
+  if (!bitFields.hasBlendMode) {
+    return false;
+  }
+
+  // 3. No offscreen rendering is required
+  // (Offscreen rendering happens when: non-SrcOver blend mode OR has filters)
+  if (blendMode != BlendMode::SrcOver || !_filters.empty()) {
+    return false;
+  }
+
+  // 4. Layer does not start or extend a 3D context
+  // (When starting or extending a 3D context, child layers need to maintain independent 3D states,
+  // so pass-through background is not supported)
+  if (canPreserve3D()) {
+    return false;
+  }
+
+  return true;
+}
+
+bool Layer::canUseSubtreeCache(const DrawArgs& args, BlendMode blendMode) {
+  if (canPreserve3D()) {
+    return false;
+  }
+  if (args.excludeEffects) {
+    return false;
+  }
+  if (args.subtreeCacheMaxSize <= 0) {
+    return false;
+  }
+  if (subtreeCache) {
+    if (subtreeCache->maxSize() != args.subtreeCacheMaxSize) {
+      subtreeCache = std::make_unique<SubtreeCache>(args.subtreeCacheMaxSize);
+    }
+    return true;
+  }
+  if (shouldPassThroughBackground(blendMode) || hasBackgroundStyle()) {
+    return false;
+  }
+  if (!bitFields.staticSubtree) {
+    return false;
+  }
+  // Skip caching for leaf nodes with basic shapes (Rect, RRect) that have no filters or layer
+  // styles, as they can be efficiently merged during rendering.
+  if (_children.empty() && _layerStyles.empty() && _filters.empty()) {
+    auto content = getContent();
+    if (content == nullptr) {
+      return false;
+    }
+    auto contentType = Types::Get(content);
+    if (contentType == Types::LayerContentType::Rect ||
+        contentType == Types::LayerContentType::RRect) {
+      return false;
+    }
+  }
+  subtreeCache = std::make_unique<SubtreeCache>(args.subtreeCacheMaxSize);
+  return true;
+}
+
+std::shared_ptr<Image> Layer::createSubtreeCacheImage(const DrawArgs& args, float contentScale,
+                                                      const Rect& layerBounds,
+                                                      Matrix* drawingMatrix) {
+  DEBUG_ASSERT(drawingMatrix != nullptr);
+  if (FloatNearlyZero(contentScale)) {
+    return nullptr;
+  }
+
+  auto drawArgs = args;
+  drawArgs.renderFlags |= RenderFlags::DisableCache;
+  drawArgs.renderRects = nullptr;
+  // Cache content should be rendered to a regular texture, not to 3D compositor.
+  drawArgs.render3DContext = nullptr;
+  drawArgs.backgroundHandler = BackgroundHandler::NoOp();
+
+  auto pictureBounds = layerBounds;
+  pictureBounds.scale(contentScale, contentScale);
+  if (!_filters.empty()) {
+    auto reverseBounds = mapOutputBoundsToInput(pictureBounds, contentScale);
+    pictureBounds.intersect(reverseBounds);
+  }
+  PictureRecorder recorder = {};
+  auto* recordingCanvas = recorder.beginRecording();
+  recordingCanvas->scale(contentScale, contentScale);
+  drawDirectly(drawArgs, recordingCanvas, 1.0f);
+  auto picture = recorder.finishRecordingAsPicture();
+  if (!picture) {
+    return nullptr;
+  }
+
+  Point offset = {};
+  auto image =
+      ToImageWithOffset(std::move(picture), &offset, &pictureBounds, args.dstColorSpace, false);
+  if (image == nullptr) {
+    return nullptr;
+  }
+
+  if (!_filters.empty()) {
+    Point filterOffset = {};
+    auto contentBounds = mapContentBoundsToImage(contentScale, pictureBounds);
+    contentBounds.offset(-(contentBounds.left + pictureBounds.left),
+                         -(contentBounds.top + pictureBounds.top));
+    image = applyFilters(std::move(image), contentScale, contentBounds, &filterOffset);
+    offset += filterOffset;
+  }
+
+  drawingMatrix->setScale(1.0f / contentScale, 1.0f / contentScale);
+  drawingMatrix->preTranslate(offset.x, offset.y);
+
+  return image->makeTextureImage(args.context);
+}
+
+SubtreeCache* Layer::getValidSubtreeCache(const DrawArgs& args, int longEdge,
+                                          const Rect& layerBounds) {
+  if (subtreeCache->hasCache(args.context, longEdge)) {
+    return subtreeCache.get();
+  }
+  if (args.renderFlags & RenderFlags::DisableCache || longEdge > args.subtreeCacheMaxSize) {
+    return nullptr;
+  }
+  auto maxBoundsSize = std::max(layerBounds.width(), layerBounds.height());
+  if (FloatNearlyZero(maxBoundsSize)) {
+    return nullptr;
+  }
+  auto cacheScale = static_cast<float>(longEdge) / maxBoundsSize;
+  auto imageMatrix = Matrix::I();
+  auto image = createSubtreeCacheImage(args, cacheScale, layerBounds, &imageMatrix);
+  if (image == nullptr) {
+    return nullptr;
+  }
+  auto textureProxy = std::static_pointer_cast<TextureImage>(image)->getTextureProxy();
+  subtreeCache->addCache(args.context, longEdge, textureProxy, imageMatrix, args.dstColorSpace);
+  return subtreeCache.get();
+}
+
+bool Layer::drawWithSubtreeCache(const DrawArgs& args, Canvas* canvas, float alpha,
+                                 BlendMode blendMode,
+                                 const std::shared_ptr<MaskFilter>& maskFilter) {
+  // Non-leaf nodes in 3D rendering context layer tree have caching disabled.
+  DEBUG_ASSERT(!canPreserve3D());
+  auto layerBounds = getBounds();
+  auto contentScale = canvas->getMatrix().getMaxScale();
+  auto longEdge = GetMipmapCacheLongEdge(args.subtreeCacheMaxSize, contentScale, layerBounds);
+  auto cache = getValidSubtreeCache(args, longEdge, layerBounds);
+  if (cache == nullptr) {
+    return false;
+  }
+  Paint paint = {};
+  if (maskFilter) {
+    paint.setMaskFilter(maskFilter);
+  }
+  paint.setAntiAlias(bitFields.allowsEdgeAntialiasing);
+  paint.setAlpha(alpha);
+  paint.setBlendMode(blendMode);
+  cache->draw(args.context, longEdge, canvas, paint);
+  return true;
+}
+
+void Layer::drawOffscreen(const DrawArgs& args, Canvas* canvas, float alpha, BlendMode blendMode,
+                          const std::shared_ptr<MaskFilter>& maskFilter) {
+  // preserve3D layers never require offscreen rendering; their effects (filters, group opacity,
+  // mask filter, non-SrcOver blend) are intentionally not supported because each preserve3D
+  // middle node is rasterized as a flat quad before BSP compositing. Non-preserve3D leaves may
+  // still invoke this path inside a 3D context — that's fine, render3DContext is irrelevant here.
+  DEBUG_ASSERT(!canPreserve3D());
+
+  auto clipBounds = GetClipBounds(canvas);
+  auto result = OffscreenResult{};
+
+  if (shouldPassThroughBackground(blendMode) && canvas->getSurface()) {
+    result = OffscreenRenderer::RenderPassThrough(this, args, canvas, clipBounds);
+  } else {
+    result = OffscreenRenderer::RenderContent(this, args, canvas->getMatrix(), clipBounds);
+  }
+
+  auto invertImageMatrix = Matrix::I();
+  if (result.isEmpty() || !result.imageMatrix.invert(&invertImageMatrix)) {
+    return;
+  }
+
+  Paint paint = {};
+  paint.setAntiAlias(false);
+  paint.setAlpha(alpha);
+  paint.setBlendMode(blendMode);
+
+  if (maskFilter) {
+    paint.setMaskFilter(maskFilter->makeWithMatrix(invertImageMatrix));
+  }
+
+  canvas->concat(result.imageMatrix);
+  auto filterMode =
+      !args.excludeEffects && !_filters.empty() ? FilterMode::Linear : FilterMode::Nearest;
+  auto sampling = SamplingOptions{filterMode, MipmapMode::None};
+  canvas->drawImage(result.image, 0.f, 0.f, sampling, &paint);
+}
+
+std::optional<Rect> Layer::computeContentBounds(const std::optional<Rect>& clipBounds,
+                                                bool excludeEffects) {
+  auto inputBounds = getBounds();
+  if (clipBounds.has_value()) {
+    auto mappedClipBounds = *clipBounds;
+    if (!excludeEffects && !_filters.empty()) {
+      mappedClipBounds = mapOutputBoundsToInput(mappedClipBounds, 1.0f);
+    }
+    if (!inputBounds.intersect(mappedClipBounds)) {
+      return std::nullopt;
+    }
+  }
+  inputBounds.roundOut();
+  return inputBounds;
+}
+
+void Layer::drawDirectly(const DrawArgs& args, Canvas* canvas, float alpha) {
+  // Capture and consume passes share the same per-layer LayerStyleSource via the active handler,
+  // so the content/contour intermediate renders happen once per frame instead of twice.
+  const LayerStyleSource* sourcePtr = nullptr;
+  if (args.backgroundHandler != nullptr) {
+    sourcePtr = args.backgroundHandler->getCachedLayerStyleSource(this);
+  }
+  std::unique_ptr<LayerStyleSource> ownedSource;
+  if (sourcePtr == nullptr) {
+    ownedSource = getLayerStyleSource(args, canvas->getMatrix());
+    if (ownedSource != nullptr && args.backgroundHandler != nullptr &&
+        args.backgroundHandler->canCacheLayerStyleSource(this)) {
+      sourcePtr = args.backgroundHandler->cacheLayerStyleSource(this, std::move(ownedSource));
+    }
+    if (sourcePtr == nullptr) {
+      sourcePtr = ownedSource.get();
+    }
+  }
+  drawContents(args, canvas, alpha, sourcePtr);
+}
+
+void Layer::drawContents(const DrawArgs& args, Canvas* canvas, float alpha,
+                         const LayerStyleSource* layerStyleSource, const Layer* stopChild) {
+  if (layerStyleSource) {
+    drawLayerStyles(args, canvas, alpha, layerStyleSource, LayerStylePosition::Below);
+  }
+  auto content = getContent();
+  bool hasForeground = false;
+  if (content) {
+    hasForeground = content->drawDefault(canvas, alpha, bitFields.allowsEdgeAntialiasing);
+  }
+  if (!drawChildren(args, canvas, alpha, stopChild)) {
+    return;
+  }
+  if (stopChild != nullptr) {
+    // Background-walk path: skip Above styles and foreground for this layer; the caller is only
+    // interested in the portion that contributes to the synthesized backdrop.
+    return;
+  }
+  if (layerStyleSource) {
+    drawLayerStyles(args, canvas, alpha, layerStyleSource, LayerStylePosition::Above);
+  }
+  if (hasForeground) {
+    content->drawForeground(canvas, alpha, bitFields.allowsEdgeAntialiasing);
+  }
+}
+
+bool Layer::drawContour(const DrawArgs& args, Canvas* canvas, float, BlendMode) {
+  return drawContourInternal(args, canvas, false);
+}
+
+bool Layer::drawContourInternal(const DrawArgs& args, Canvas* canvas, bool contentOnly) {
+  auto* opaqueContext = args.opaqueContext;
+  // Check if this layer is completely covered by opaque bounds
+  auto bounds = getBounds();
+  auto globalBounds = canvas->getMatrix().mapRect(bounds);
+  if (opaqueContext && opaqueContext->containsOpaqueBounds(globalBounds)) {
+    return true;
+  }
+
+  // Check effects for child layers (not contentOnly)
+  bool allMatch = true;
+  if (!contentOnly && !args.excludeEffects && (!_filters.empty() || !_layerStyles.empty())) {
+    allMatch = false;
+  }
+
+  // Apply mask for child layers (not contentOnly)
+  std::shared_ptr<MaskFilter> maskFilter = nullptr;
+  if (!contentOnly && hasValidMask()) {
+    auto contentScale = canvas->getMatrix().getMaxScale();
+    auto clipBounds = GetClipBounds(canvas);
+    auto maskData = getMaskData(args, contentScale, clipBounds);
+    if (maskData.maskFilter == nullptr) {
+      if (maskData.clipPath.isEmpty() && !maskData.clipPath.isInverseFillType()) {
+        return allMatch;
+      }
+      canvas->clipPath(maskData.clipPath, _mask->bitFields.allowsEdgeAntialiasing);
+    } else {
+      maskFilter = maskData.maskFilter;
+    }
+  }
+
+  // Handle offscreen rendering for mask filter
+  if (maskFilter) {
+    auto contentScale = canvas->getMatrix().getMaxScale();
+    auto offset = Point::Zero();
+    bool contourMatchesContent = true;
+    auto image = getContentContourImage(args, contentScale, &offset, &contourMatchesContent);
+    if (image == nullptr) {
+      return allMatch;
+    }
+    if (!contourMatchesContent) {
+      allMatch = false;
+    }
+    auto imageMatrix = Matrix::MakeScale(1.0f / contentScale, 1.0f / contentScale);
+    imageMatrix.preTranslate(offset.x, offset.y);
+    auto invertImageMatrix = Matrix::I();
+    if (imageMatrix.invert(&invertImageMatrix)) {
+      Paint paint = {};
+      paint.setMaskFilter(maskFilter->makeWithMatrix(invertImageMatrix));
+      AutoCanvasRestore restore(canvas);
+      canvas->concat(imageMatrix);
+      canvas->drawImage(std::move(image), 0, 0, &paint);
+    }
+    return allMatch;
+  }
+
+  // Draw content's contour
+  auto content = getContent();
+  if (content) {
+    if (!content->contourEqualsOpaqueContent()) {
+      allMatch = false;
+    }
+    content->drawContour(canvas, bitFields.allowsEdgeAntialiasing);
+  }
+
+  // 3D middle node: descendants are independently registered with the active Layer3DContext, so
+  // we must not recurse into them here. Same gate as drawChildren below.
+  if (canPreserve3D() && args.render3DContext != nullptr) {
+    return allMatch;
+  }
+
+  // Draw children's contour directly (not using drawChildren to avoid background logic)
+  for (auto& child : _children) {
+    if (child->maskOwner || !child->visible() || child->_alpha <= 0) {
+      continue;
+    }
+    if (!drawChild(args, canvas, child.get(), 1.0f, &Layer::drawContour)) {
+      allMatch = false;
+    }
+  }
+  return allMatch;
+}
+
+bool Layer::drawChildren(const DrawArgs& args, Canvas* canvas, float alpha,
+                         const Layer* stopChild) {
+  // 3D middle node: descendants are independently registered with the active Layer3DContext and
+  // composited via BSP. Do not recurse here, otherwise we would double-draw them.
+  if (canPreserve3D() && args.render3DContext != nullptr) {
+    return true;
+  }
+  auto childCount = static_cast<int>(_children.size());
+  int maxIndex = childCount - 1;
+  if (args.backgroundHandler != nullptr) {
+    int lastCaptureIndex = args.backgroundHandler->lastCaptureChildIndex(this);
+    if (lastCaptureIndex < 0) {
+      return true;
+    }
+    if (lastCaptureIndex < maxIndex) {
+      maxIndex = lastCaptureIndex;
+    }
+  }
+  for (int i = 0; i <= maxIndex; ++i) {
+    auto& child = _children[static_cast<size_t>(i)];
+    if (stopChild != nullptr && child.get() == stopChild) {
+      // Background-walk truncation: the caller only wants prior siblings of stopChild.
+      break;
+    }
+    if (child->maskOwner || !child->visible() || child->_alpha <= 0) {
+      continue;
+    }
+    if (args.backgroundHandler != nullptr && i < maxIndex) {
+      args.backgroundHandler->beginForceDrawChildren();
+      drawChild(args, canvas, child.get(), alpha, &Layer::drawLayer);
+      args.backgroundHandler->endForceDrawChildren();
+    } else {
+      drawChild(args, canvas, child.get(), alpha, &Layer::drawLayer);
+    }
+  }
+  return true;
+}
+
+void Layer::drawByStarting3DContext(const DrawArgs& args, Canvas* canvas, const Matrix3D& matrix3D,
+                                    LayerDrawFunc drawFunc, float alpha) {
+  DEBUG_ASSERT(canPreserve3D());
+  // args.render3DContext may be non-null when this preserve3D layer is nested inside a
+  // non-preserve3D leaf that is being rasterized in an outer 3D context. The nested context is
+  // independent from the outer one — it builds and composites on its own surface.
+
+  const auto bounds = getBoundsInternal(matrix3D, false);
+  const auto newContext = Create3DContext(args, canvas, bounds);
+  if (newContext == nullptr) {
+    return;
+  }
+
+  newContext->addLayer(this, matrix3D, alpha, drawFunc);
+  newContext->finishAndDrawTo(args, canvas);
+}
+
+bool Layer::drawChild(const DrawArgs& args, Canvas* canvas, Layer* child, float alpha,
+                      LayerDrawFunc drawFunc) {
+  // 2D → 3D switch: hand off to drawByStarting3DContext, which expands the 3D subtree internally.
+  if (child->canPreserve3D()) {
+    auto matrix3D = child->getMatrixWithScrollRect();
+    child->drawByStarting3DContext(args, canvas, matrix3D, drawFunc, child->_alpha * alpha);
+    return true;
+  }
+
+  AutoCanvasRestore autoRestore(canvas);
+  canvas->concat(child->getMatrixWithScrollRect().asMatrix());
+  ClipScrollRect(canvas, child->_scrollRect.get(), nullptr,
+                 child->bitFields.allowsEdgeAntialiasing);
+  auto blendMode = static_cast<BlendMode>(child->bitFields.blendMode);
+  return (child->*drawFunc)(args, canvas, child->_alpha * alpha, blendMode);
+}
+
+std::unique_ptr<LayerStyleSource> Layer::getLayerStyleSource(const DrawArgs& args,
+                                                             const Matrix& matrix) {
+  if (_layerStyles.empty() || args.excludeEffects) {
+    return nullptr;
+  }
+  auto contentScale = matrix.getMaxScale();
+  if (FloatNearlyZero(contentScale)) {
+    return nullptr;
+  }
+
+  // Collect which excludeChildEffects values need content and/or contour.
+  bool needContent[2] = {false, false};
+  bool needContour[2] = {false, false};
+  for (const auto& layerStyle : _layerStyles) {
+    auto index = static_cast<int>(layerStyle->excludeChildEffects());
+    needContent[index] = true;
+    if (layerStyle->extraSourceType() == LayerStyleExtraSourceType::Contour) {
+      needContour[index] = true;
+    }
+  }
+
+  auto source = std::make_unique<LayerStyleSource>();
+  source->contentScale = contentScale;
+
+  DrawArgs drawArgs = args;
+  drawArgs.render3DContext = nullptr;
+  // Layer style source content is an intermediate artifact — skip background capture / consume.
+  drawArgs.backgroundHandler = BackgroundHandler::NoOp();
+
+  for (int i = 0; i < 2; i++) {
+    if (!needContent[i] && !needContour[i]) {
+      continue;
+    }
+    drawArgs.excludeEffects = static_cast<bool>(i);
+    auto group = std::make_unique<LayerStyleSourceGroup>();
+
+    bool allContourMatch = false;
+    if (needContour[i]) {
+      LayerStyleSourceEntry contourEntry = {};
+      contourEntry.image =
+          getContentContourImage(drawArgs, contentScale, &contourEntry.offset, &allContourMatch);
+      if (contourEntry.image == nullptr) {
+        return nullptr;
+      }
+      if (allContourMatch) {
+        group->content = contourEntry;
+        needContent[i] = false;
+      }
+      group->contour = std::move(contourEntry);
+    }
+
+    if (needContent[i]) {
+      OpaqueContext opaqueContext;
+      auto* contourCanvas = opaqueContext.beginRecording();
+      contourCanvas->scale(contentScale, contentScale);
+      drawContents(drawArgs, contourCanvas, 1.0f);
+      auto picture = opaqueContext.finishRecordingAsPicture();
+      group->content.image = ToImageWithOffset(std::move(picture), &group->content.offset, nullptr,
+                                               args.dstColorSpace);
+      if (group->content.image == nullptr) {
+        return nullptr;
+      }
+    }
+
+    source->groups[i] = std::move(group);
+  }
+
+  if (needContour[0] || needContour[1]) {
+    // TODO: The contour shape should have the same semantics as the contour image,
+    // covering the entire subtree content. Contour should be encapsulated as a composite
+    // class that records Picture data containing draw instructions, with a new interface
+    // to parse Shape from the Picture data. This ensures the Image and Shape inside
+    // Contour have consistent semantics. The layer's clip region should also be stored
+    // within Contour.
+    source->contentShape = getContentShape();
+  }
+
+  return source;
+}
+
+void Layer::drawLayerStyles(const DrawArgs& args, Canvas* canvas, float alpha,
+                            const LayerStyleSource* source, LayerStylePosition position) {
+  DEBUG_ASSERT(source != nullptr && !FloatNearlyZero(source->contentScale));
+  for (const auto& layerStyle : _layerStyles) {
+    DEBUG_ASSERT(layerStyle != nullptr);
+    if (layerStyle->position() != position) {
+      continue;
+    }
+    if (layerStyle->extraSourceType() == LayerStyleExtraSourceType::Background) {
+      BackgroundHandler::DispatchOrSkip(args, canvas, this, alpha, layerStyle.get(), source);
+      continue;
+    }
+    drawLayerStyleDefault(args, canvas, alpha, layerStyle.get(), source);
+  }
+}
+
+float Layer::drawBackgroundLayers(const DrawArgs& args, Canvas* canvas) {
+  if (!_parent) {
+    return _alpha;
+  }
+  // Bottom-up recursion grounds at the root, then unwinds painting in this order per frame:
+  // parent's background -> parent's Below styles -> parent content -> siblings of `this` that
+  // come before `this`. The current frame's `this` is the parent's stopChild, so siblings at or
+  // after `this` are skipped.
+  auto currentAlpha = _parent->drawBackgroundLayers(args, canvas);
+  auto parentSource = _parent->getLayerStyleSource(args, canvas->getMatrix());
+  _parent->drawContents(args, canvas, currentAlpha, parentSource.get(), this);
+  canvas->concat(getMatrixWithScrollRect().asMatrix());
+  if (_scrollRect) {
+    canvas->clipRect(*_scrollRect, bitFields.allowsEdgeAntialiasing);
+  }
+  return currentAlpha * _alpha;
+}
+
+std::shared_ptr<Image> Layer::synthesizeBackgroundImage(const DrawArgs& args, float contentScale,
+                                                        Point* offset) {
+  if (FloatNearlyZero(contentScale)) {
+    return nullptr;
+  }
+  auto bounds = getBounds();
+  bounds.scale(contentScale, contentScale);
+  bounds.roundOut();
+  if (bounds.isEmpty()) {
+    return nullptr;
+  }
+  auto localToGlobalMatrix = getGlobalMatrix().asMatrix();
+  Matrix globalToLocalMatrix = Matrix::I();
+  if (!localToGlobalMatrix.invert(&globalToLocalMatrix)) {
+    return nullptr;
+  }
+
+  PictureRecorder recorder = {};
+  auto* recordingCanvas = recorder.beginRecording();
+  recordingCanvas->scale(contentScale, contentScale);
+  recordingCanvas->concat(globalToLocalMatrix);
+
+  // Sub-walk must not re-enter the consumer's fallback (which would recurse forever on layers
+  // with their own background-sourced styles up the chain). Hand it a NoOp handler instead — that
+  // also short-circuits Below style dispatch for backdrop styles encountered along the way, which
+  // matches the semantics of drawing pure backdrop content.
+  DrawArgs subArgs = args;
+  subArgs.backgroundHandler = BackgroundHandler::NoOp();
+  subArgs.excludeEffects = false;
+
+  auto currentAlpha = drawBackgroundLayers(subArgs, recordingCanvas);
+  auto belowSource = getLayerStyleSource(subArgs, recordingCanvas->getMatrix());
+  if (belowSource) {
+    drawLayerStyles(subArgs, recordingCanvas, currentAlpha, belowSource.get(),
+                    LayerStylePosition::Below);
+  }
+
+  auto picture = recorder.finishRecordingAsPicture();
+  if (picture == nullptr) {
+    return nullptr;
+  }
+  return ToImageWithOffset(std::move(picture), offset, &bounds, args.dstColorSpace);
+}
+
+void Layer::drawLayerStyleDefault(const DrawArgs& /*args*/, Canvas* canvas, float alpha,
+                                  LayerStyle* layerStyle, const LayerStyleSource* source) {
+  DEBUG_ASSERT(source != nullptr && !FloatNearlyZero(source->contentScale));
+  DEBUG_ASSERT(layerStyle->extraSourceType() != LayerStyleExtraSourceType::Background);
+  auto groupIndex = static_cast<int>(layerStyle->excludeChildEffects());
+  auto* group = source->groups[groupIndex].get();
+  if (group == nullptr) {
+    return;
+  }
+
+  auto& contentEntry = group->content;
+  // Apply the content transform matrix to canvas so that rendering happens at the final scale,
+  // avoiding blurry results that would come from baking contentScale into a picture recording.
+  AutoCanvasRestore restoreCanvas(canvas);
+  auto matrix = Matrix::MakeScale(1.f / source->contentScale, 1.f / source->contentScale);
+  matrix.preTranslate(contentEntry.offset.x, contentEntry.offset.y);
+  canvas->concat(matrix);
+  LayerStyleInput styleInput = {};
+  styleInput.content = contentEntry.image;
+  styleInput.contentOffset = contentEntry.offset;
+  styleInput.contentScale = source->contentScale;
+  if (layerStyle->extraSourceType() == LayerStyleExtraSourceType::Contour) {
+    auto contourImage = group->contour.has_value() ? group->contour->image : nullptr;
+    auto contourOffset =
+        contourImage ? group->contour->offset - contentEntry.offset : Point::Zero();
+    // contour shape may be nullopt when the layer has no simple vector content (e.g. a group
+    // layer with only children).
+    styleInput.extraSource = std::make_shared<ContourInputSource>(
+        std::move(contourImage), contourOffset, source->contentShape);
+  }
+  layerStyle->draw(canvas, styleInput, alpha);
+}
+
+bool Layer::getLayersUnderPointInternal(float x, float y,
+                                        std::vector<std::shared_ptr<Layer>>* results) {
+  bool hasLayerUnderPoint = false;
+  for (auto item = _children.rbegin(); item != _children.rend(); ++item) {
+    const auto& childLayer = *item;
+    if (!childLayer->visible()) {
+      continue;
+    }
+
+    if (nullptr != childLayer->_scrollRect) {
+      auto pointInChildSpace = childLayer->globalToLocal(Point::Make(x, y));
+      if (!childLayer->_scrollRect->contains(pointInChildSpace.x, pointInChildSpace.y)) {
+        continue;
+      }
+    }
+
+    if (nullptr != childLayer->_mask) {
+      if (!childLayer->_mask->hitTestPoint(x, y)) {
+        continue;
+      }
+    }
+
+    if (childLayer->getLayersUnderPointInternal(x, y, results)) {
+      hasLayerUnderPoint = true;
+    }
+  }
+
+  if (hasLayerUnderPoint) {
+    results->push_back(shared_from_this());
+  } else {
+    auto content = getContent();
+    if (nullptr != content) {
+      auto layerBoundsRect = content->getBounds();
+      auto localPoint = globalToLocal(Point::Make(x, y));
+      if (layerBoundsRect.contains(localPoint.x, localPoint.y)) {
+        results->push_back(shared_from_this());
+        hasLayerUnderPoint = true;
+      }
+    }
+  }
+
+  return hasLayerUnderPoint;
+}
+
+bool Layer::hasValidMask() const {
+  return _mask && _mask->root() == root() && _mask->bitFields.visible;
+}
+
+void Layer::updateRenderBounds(std::shared_ptr<RegionTransformer> transformer, bool forceDirty) {
+  if (!forceDirty && !bitFields.dirtyDescendents) {
+    if (maxBackgroundOutset > 0 || bitFields.hasBlendMode) {
+      propagateLayerState();
+      if (_root->hasDirtyRegions()) {
+        checkBackgroundStyles(transformer);
+      }
+    }
+    return;
+  }
+  maxBackgroundOutset = 0;
+  minBackgroundOutset = std::numeric_limits<float>::max();
+  auto contentScale = 1.0f;
+  if (!_layerStyles.empty() || !_filters.empty()) {
+    // Filters and styles interrupt 3D rendering context, so non-root layers inside 3D rendering
+    // context can ignore parent filters and styles when calculating dirty regions.
+    DEBUG_ASSERT(!canPreserve3D());
+    if (transformer) {
+      contentScale = transformer->getMaxScale();
+    }
+    transformer = RegionTransformer::MakeFromFilters(_filters, 1.0f, std::move(transformer));
+    transformer = RegionTransformer::MakeFromStyles(_layerStyles, 1.0f, std::move(transformer));
+  }
+  // Snapshot the root dirty list before touching this layer's own content or descending into
+  // children. Only rects that existed before this layer's subtree ran contribute to this layer's
+  // background-blur sampling input; anything produced below (this layer's own content or its
+  // descendants) paints above the blur result and must not participate in blur dirty expansion.
+  // The snapshot costs O(MAX_DIRTY_REGIONS) = O(1) per blur-capable layer.
+  std::vector<Rect> backgroundSourceRects = {};
+  for (const auto& style : _layerStyles) {
+    if (style && style->extraSourceType() == LayerStyleExtraSourceType::Background) {
+      backgroundSourceRects = _root->currentDirtyRects();
+      break;
+    }
+  }
+  auto content = getContent();
+  if (bitFields.dirtyContentBounds || (forceDirty && content)) {
+    if (contentBounds) {
+      _root->invalidateRect(*contentBounds);
+    } else {
+      contentBounds = new Rect();
+    }
+    if (content) {
+      *contentBounds = content->getBounds();
+      if (transformer) {
+        transformer->transform(contentBounds);
+      }
+      _root->invalidateRect(*contentBounds);
+    } else {
+      contentBounds->setEmpty();
+    }
+    bitFields.dirtyContentBounds = false;
+  }
+  if (contentBounds) {
+    renderBounds = *contentBounds;
+  } else {
+    renderBounds.setEmpty();
+  }
+  for (auto& child : _children) {
+    if (!child->bitFields.visible || child->_alpha <= 0) {
+      if (child->bitFields.dirtyTransform) {
+        _root->invalidateRect(child->renderBounds);
+        child->renderBounds = {};
+      }
+      child->bitFields.dirtyTransform = false;
+      continue;
+    }
+    auto childMatrix = child->getMatrixWithScrollRect();
+    std::shared_ptr<RegionTransformer> childTransformer = nullptr;
+    if (canPreserve3D() || child->canPreserve3D()) {
+      // Child is inside a 3D rendering context - allow combining matrices.
+      childTransformer = RegionTransformer::MakeFromMatrix3D(childMatrix, transformer, true);
+    } else {
+      // Child is outside 3D context - project to 2D plane.
+      childTransformer = RegionTransformer::MakeFromMatrix(childMatrix.asMatrix(), transformer);
+    }
+    std::optional<Rect> clipRect = std::nullopt;
+    if (child->_scrollRect) {
+      clipRect = *child->_scrollRect;
+    }
+    if (child->hasValidMask()) {
+      auto maskBounds = child->_mask->getBounds(child.get());
+      if (clipRect.has_value()) {
+        if (!clipRect->intersect(maskBounds)) {
+          if (child->bitFields.dirtyTransform) {
+            _root->invalidateRect(child->renderBounds);
+            child->renderBounds = {};
+          }
+          child->bitFields.dirtyTransform = false;
+          continue;
+        }
+      } else {
+        clipRect = maskBounds;
+      }
+    }
+    if (clipRect.has_value()) {
+      childTransformer = RegionTransformer::MakeFromClip(*clipRect, std::move(childTransformer));
+    }
+    auto childForceDirty = forceDirty || child->bitFields.dirtyTransform;
+    child->updateRenderBounds(std::move(childTransformer), childForceDirty);
+    child->bitFields.dirtyTransform = false;
+    if (!child->maskOwner) {
+      renderBounds.join(child->renderBounds);
+    }
+  }
+  auto backOutset = 0.f;
+  if (!renderBounds.isEmpty()) {
+    for (auto& style : _layerStyles) {
+      DEBUG_ASSERT(style != nullptr);
+      if (style->extraSourceType() != LayerStyleExtraSourceType::Background) {
+        continue;
+      }
+      auto outset = style->filterBackground(Rect::MakeEmpty(), contentScale);
+      backOutset = std::max(backOutset, outset.right);
+      backOutset = std::max(backOutset, outset.bottom);
+    }
+    // When a layer has both background styles and filters, the outer filter needs to sample
+    // beyond the background content area. Expand the background outset to include the filter's
+    // sampling range. Use Reverse direction to calculate required input bounds.
+    if (backOutset > 0 && !_filters.empty()) {
+      auto baseBounds = mapOutputBoundsToInput(Rect::MakeEmpty(), contentScale);
+      if (!baseBounds.isEmpty()) {
+        auto maxOutset =
+            std::max({-baseBounds.left, -baseBounds.top, baseBounds.right, baseBounds.bottom});
+        backOutset += maxOutset;
+      }
+    }
+  }
+  if (backOutset > 0) {
+    maxBackgroundOutset = std::max(backOutset, maxBackgroundOutset);
+    minBackgroundOutset = std::min(backOutset, minBackgroundOutset);
+    updateBackgroundBounds(contentScale, backgroundSourceRects);
+  }
+  if (bitFields.blendMode != static_cast<uint8_t>(BlendMode::SrcOver) ||
+      (content && content->hasBlendMode())) {
+    bitFields.hasBlendMode = true;
+  }
+  propagateLayerState();
+  bitFields.dirtyDescendents = false;
+}
+
+void Layer::checkBackgroundStyles(std::shared_ptr<RegionTransformer> transformer) {
+  for (auto& child : _children) {
+    if (child->maxBackgroundOutset <= 0 || !child->bitFields.visible || child->_alpha <= 0) {
+      continue;
+    }
+    auto childMatrix = child->getMatrixWithScrollRect();
+    auto childTransformer = RegionTransformer::MakeFromMatrix(childMatrix.asMatrix(), transformer);
+    child->checkBackgroundStyles(childTransformer);
+  }
+  // Fast path: this layer's subtree did not change, so every current dirty rect originates from
+  // outside this subtree and is a legitimate blur input candidate. Passing the live list is safe
+  // because invalidateBackground collects all expanded rects locally before re-appending them.
+  updateBackgroundBounds(transformer ? transformer->getMaxScale() : 1.0f,
+                         _root->currentDirtyRects());
+}
+
+void Layer::updateBackgroundBounds(float contentScale, const std::vector<Rect>& sourceRects) {
+  for (auto& style : _layerStyles) {
+    DEBUG_ASSERT(style != nullptr);
+    if (style->extraSourceType() == LayerStyleExtraSourceType::Background) {
+      _root->invalidateBackground(renderBounds, style.get(), contentScale, sourceRects);
+    }
+  }
+  if (bitFields.hasBlendMode) {
+    _root->invalidateBackground(renderBounds, nullptr, contentScale, sourceRects);
+  }
+}
+
+void Layer::propagateLayerState() {
+  auto layer = _parent;
+  while (layer) {
+    bool change = false;
+    if (layer->maxBackgroundOutset < maxBackgroundOutset) {
+      layer->maxBackgroundOutset = maxBackgroundOutset;
+      change = true;
+    }
+    if (layer->minBackgroundOutset > minBackgroundOutset) {
+      layer->minBackgroundOutset = minBackgroundOutset;
+      change = true;
+    }
+    // Only propagate hasBlendMode if this layer actually has a blend mode
+    if (bitFields.hasBlendMode && !layer->bitFields.hasBlendMode) {
+      layer->bitFields.hasBlendMode = true;
+      change = true;
+    }
+    if (!change) {
+      break;
+    }
+    layer = layer->_parent;
+  }
+}
+
+bool Layer::hasBackgroundStyle() {
+  if (!bitFields.dirtyDescendents) {
+    return maxBackgroundOutset > 0;
+  }
+  for (const auto& style : _layerStyles) {
+    DEBUG_ASSERT(style != nullptr);
+    if (style->extraSourceType() == LayerStyleExtraSourceType::Background) {
+      return true;
+    }
+  }
+  return hasDescendantBackgroundStyle();
+}
+
+bool Layer::hasDescendantBackgroundStyle() {
+  for (const auto& child : _children) {
+    if (child->hasBackgroundStyle()) {
+      return true;
+    }
+  }
+  return false;
+}
+
+std::shared_ptr<BackgroundSource> Layer::createBackgroundSource(
+    Context* context, const Rect& drawRect, const Matrix& viewMatrix, bool fullLayer,
+    std::shared_ptr<ColorSpace> colorSpace) const {
+  if (fullLayer) {
+    return BackgroundSource::Make(context, drawRect, 0, 0, viewMatrix, colorSpace);
+  }
+  if (maxBackgroundOutset <= 0.0f) {
+    return nullptr;
+  }
+  auto scale = viewMatrix.getMaxScale();
+  return BackgroundSource::Make(context, drawRect, maxBackgroundOutset * scale,
+                                minBackgroundOutset * scale, viewMatrix, colorSpace);
+}
+
+bool Layer::canPreserve3D() const {
+  return _preserve3D && _filters.empty() && _layerStyles.empty() && !hasValidMask() &&
+         _scrollRect == nullptr;
+}
+
+void Layer::invalidateSubtree() {
+  bitFields.staticSubtree = false;
+  subtreeCache = nullptr;
+  localBounds = nullptr;
+}
+
+void Layer::updateStaticSubtreeFlags() {
+  if (bitFields.staticSubtree) {
+    return;
+  }
+  bitFields.staticSubtree = true;
+  for (const auto& child : _children) {
+    child->updateStaticSubtreeFlags();
+  }
+}
+
+std::optional<StyledShape> Layer::getContentShape() {
+  return onGetContentShape();
+}
+
+}  // namespace tgfx