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

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

@@ -0,0 +1,363 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2026 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 "BackgroundHandler.h"
+#include "core/utils/Log.h"
+#include "core/utils/MathExtra.h"
+#include "layers/BackgroundSnapshotMap.h"
+#include "layers/BackgroundSource.h"
+#include "layers/DrawArgs.h"
+#include "layers/LayerStyleSource.h"
+#include "tgfx/core/Image.h"
+#include "tgfx/core/PictureRecorder.h"
+#include "tgfx/core/Surface.h"
+#include "tgfx/layers/Layer.h"
+#include "tgfx/layers/layerstyles/LayerStyle.h"
+
+namespace tgfx {
+
+namespace {
+
+// A handler that does nothing for background-sourced styles. Used for intermediate artifacts and
+// 3D / contour paths where background styles must not produce output.
+class NoOpImpl : public BackgroundHandler {
+ public:
+  void drawBackgroundStyle(const DrawArgs& /*args*/, Canvas* /*canvas*/, Layer* /*layer*/,
+                           float /*alpha*/, LayerStyle* /*style*/,
+                           const LayerStyleSource* /*source*/) override {
+  }
+};
+
+// Copy the slice of bgImage this layer consumes into a private surface, so the recorded picture
+// references the copy rather than bgImage. bgImage IS bgSource->surface's cachedImage; holding a
+// reference to it during capture would trigger Surface::aboutToDraw's copy-on-write path on every
+// subsequent write to bgCanvas — a full RT reallocation plus blit that dominates GPU submit time.
+// Returns nullptr on failure (no context, over-budget, or non-invertible matrix).
+std::shared_ptr<Image> MakeDetachedBgCopy(Context* context, const std::shared_ptr<Image>& bgImage,
+                                          const Matrix& bgPixelToLocal, const Rect& layerBounds,
+                                          Point* offset, std::shared_ptr<ColorSpace> colorSpace) {
+  Matrix localToBgPixel = Matrix::I();
+  if (!bgPixelToLocal.invert(&localToBgPixel)) {
+    return nullptr;
+  }
+  auto bgPixelBounds = layerBounds;
+  localToBgPixel.mapRect(&bgPixelBounds);
+  if (!bgPixelBounds.intersect(Rect::MakeWH(bgImage->width(), bgImage->height()))) {
+    return nullptr;
+  }
+  bgPixelBounds.roundOut();
+  auto width = FloatCeilToInt(bgPixelBounds.width());
+  auto height = FloatCeilToInt(bgPixelBounds.height());
+  if (width <= 0 || height <= 0) {
+    return nullptr;
+  }
+  auto surface = Surface::Make(context, width, height, false, 1, false, 0, std::move(colorSpace));
+  if (surface == nullptr) {
+    return nullptr;
+  }
+  auto* canvas = surface->getCanvas();
+  canvas->translate(-bgPixelBounds.left, -bgPixelBounds.top);
+  canvas->drawImage(bgImage);
+  if (offset != nullptr) {
+    *offset = {bgPixelBounds.left, bgPixelBounds.top};
+  }
+  return surface->makeImageSnapshot();
+}
+
+// Intersects the sub background's rect with parentArgs.renderRects to produce a narrowed cull
+// list for the offscreen's child draw pass. If parentArgs.renderRects is null/empty (no cull),
+// falls back to the full bgRect.
+void NarrowRenderRects(const DrawArgs& parentArgs, const Rect& bgRect,
+                       std::vector<Rect>* outRects) {
+  if (parentArgs.renderRects != nullptr && !parentArgs.renderRects->empty()) {
+    for (const auto& r : *parentArgs.renderRects) {
+      auto clipped = r;
+      if (clipped.intersect(bgRect)) {
+        outRects->push_back(clipped);
+      }
+    }
+  } else {
+    outRects->push_back(bgRect);
+  }
+}
+
+// Builds the world-space rect and localToWorld matrix for a sub source nested under bgSource.
+// Returns false if bgSource is missing.
+bool ComputeSubGeometry(BackgroundSource* parentSource, const Rect& localBounds,
+                        const Matrix& contentMatrix, Matrix* localToWorld, Rect* worldBounds) {
+  if (parentSource == nullptr) {
+    return false;
+  }
+  *localToWorld = parentSource->surfaceToWorldMatrix();
+  localToWorld->preConcat(contentMatrix);
+  *worldBounds = localToWorld->mapRect(localBounds);
+  worldBounds->roundOut();
+  return true;
+}
+
+}  // namespace
+
+BackgroundHandler* BackgroundHandler::NoOp() {
+  static NoOpImpl instance;
+  return &instance;
+}
+
+void BackgroundHandler::DispatchOrSkip(const DrawArgs& args, Canvas* canvas, Layer* layer,
+                                       float alpha, LayerStyle* style,
+                                       const LayerStyleSource* source) {
+  auto* handler = args.backgroundHandler ? args.backgroundHandler : BackgroundHandler::NoOp();
+  handler->drawBackgroundStyle(args, canvas, layer, alpha, style, source);
+}
+
+int BackgroundHandler::lastCaptureChildIndex(const Layer* parent) const {
+  return static_cast<int>(parent->children().size()) - 1;
+}
+
+int BackgroundCapturer::lastCaptureChildIndex(const Layer* parent) const {
+  if (isForcedCapture()) {
+    return static_cast<int>(parent->children().size()) - 1;
+  }
+  const auto& children = parent->children();
+  for (int i = static_cast<int>(children.size()) - 1; i >= 0; --i) {
+    if (children[static_cast<size_t>(i)]->hasBackgroundStyle()) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+bool BackgroundCapturer::needsSurface(Layer* layer) const {
+  return layer != nullptr && layer->hasDescendantBackgroundStyle();
+}
+
+std::unique_ptr<BackgroundCapturer> BackgroundCapturer::buildSubCapturer(
+    const DrawArgs& parentArgs, std::shared_ptr<BackgroundSource> subSource) const {
+  if (subSource == nullptr) {
+    return nullptr;
+  }
+  auto subRect = subSource->getBackgroundRect();
+  auto clone = std::make_unique<BackgroundCapturer>(snapshots, std::move(subSource));
+  NarrowRenderRects(parentArgs, subRect, &clone->_renderRects);
+  // Forced-capture state must propagate so pass-through subtrees still feed the parent bgSource.
+  if (isForcedCapture()) {
+    clone->beginForceDrawChildren();
+  }
+  return clone;
+}
+
+std::unique_ptr<BackgroundHandler> BackgroundCapturer::createSubHandler(
+    Surface* surface, const DrawArgs& parentArgs, const Rect& localBounds,
+    const Matrix& localToWorld, const Matrix& localToSurface) const {
+  Matrix toWorld = Matrix::I();
+  Rect worldBounds = Rect::MakeEmpty();
+  if (!ComputeSubGeometry(bgSource.get(), localBounds, localToWorld, &toWorld, &worldBounds)) {
+    DEBUG_ASSERT(false);
+    return nullptr;
+  }
+  auto subSource = bgSource->createFromSurface(surface, worldBounds, toWorld, localToSurface);
+  DEBUG_ASSERT(subSource != nullptr);
+  return buildSubCapturer(parentArgs, std::move(subSource));
+}
+
+void BackgroundCapturer::drawBackgroundStyle(const DrawArgs& args, Canvas* canvas, Layer* layer,
+                                             float /*alpha*/, LayerStyle* style,
+                                             const LayerStyleSource* source) {
+  if (snapshots == nullptr || bgSource == nullptr || source == nullptr || canvas == nullptr) {
+    return;
+  }
+  auto surfaceScale = bgSource->surfaceScale();
+  auto contentScale = source->contentScale;
+  auto localToWorld = bgSource->surfaceToWorldMatrix();
+  localToWorld.preConcat(canvas->getMatrix());
+  if (!FloatNearlyZero(surfaceScale) && surfaceScale != 1.0f) {
+    contentScale /= surfaceScale;
+  }
+  if (FloatNearlyZero(contentScale)) {
+    return;
+  }
+  auto layerBounds = layer->getBounds();
+  auto bounds = layerBounds;
+  bounds.scale(contentScale, contentScale);
+  bounds.roundOut();
+  // Use the runtime canvas chain (capture canvas matrix · bgSource->surfaceToWorldMatrix) so
+  // capture and consume share the same frame of reference. Do NOT use getGlobalMatrix(): it walks
+  // the static layer tree with per-step z-flattening and diverges from the runtime concat chain
+  // when multiple non-preserve3D perspective matrices stack up.
+  Matrix worldToLocal = Matrix::I();
+  if (!localToWorld.invert(&worldToLocal)) {
+    return;
+  }
+  auto bgImage = bgSource->getBackgroundImage();
+  if (bgImage == nullptr) {
+    return;
+  }
+  Matrix bgPixelToLocal = worldToLocal;
+  bgPixelToLocal.preConcat(bgSource->backgroundMatrix());
+  Point smallBgOffset = {};
+  auto smallBgImage = MakeDetachedBgCopy(args.context, bgImage, bgPixelToLocal, layerBounds,
+                                         &smallBgOffset, args.dstColorSpace);
+  PictureRecorder recorder = {};
+  auto* recording = recorder.beginRecording();
+  recording->scale(contentScale, contentScale);
+  recording->concat(worldToLocal);
+  recording->concat(bgSource->backgroundMatrix());
+  if (smallBgImage != nullptr) {
+    recording->translate(smallBgOffset.x, smallBgOffset.y);
+    recording->drawImage(std::move(smallBgImage));
+  } else {
+    // Fallback when detached copy is unavailable; original path may trigger COW.
+    recording->drawImage(bgImage);
+  }
+  auto picture = recorder.finishRecordingAsPicture();
+  if (picture == nullptr) {
+    return;
+  }
+  Point offset = {};
+  auto image = ToImageWithOffset(std::move(picture), &offset, &bounds, args.dstColorSpace);
+  if (image == nullptr) {
+    return;
+  }
+  snapshots->snapshots[BackgroundSnapshotKey{layer, style}].push_back(
+      BackgroundSnapshotEntry{std::move(image), offset});
+}
+
+const LayerStyleSource* BackgroundCapturer::getCachedLayerStyleSource(Layer* layer) const {
+  if (snapshots == nullptr) {
+    return nullptr;
+  }
+  auto it = snapshots->layerStyleSources.find(layer);
+  if (it == snapshots->layerStyleSources.end()) {
+    return nullptr;
+  }
+  return it->second.get();
+}
+
+bool BackgroundCapturer::canCacheLayerStyleSource(Layer* /*layer*/) const {
+  // When the bg source was down-sampled (extreme blur outset), capture and consume run at
+  // different densities, so a cached source built in capture cannot be reused in consume.
+  return snapshots != nullptr && (bgSource == nullptr || bgSource->surfaceScale() == 1.0f);
+}
+
+const LayerStyleSource* BackgroundCapturer::cacheLayerStyleSource(
+    Layer* layer, std::unique_ptr<LayerStyleSource> source) {
+  DEBUG_ASSERT(canCacheLayerStyleSource(layer));
+  if (source == nullptr) {
+    return nullptr;
+  }
+  // Wrap each picture-backed image as Rasterized so the first draw uploads a GPU texture and the
+  // second pass reuses it instead of replaying the picture. makeRasterized() on an already-
+  // rasterized image is a no-op, so wrapping content/contour independently still hits one cache.
+  for (auto& group : source->groups) {
+    if (group == nullptr) {
+      continue;
+    }
+    if (group->content.image != nullptr) {
+      group->content.image = group->content.image->makeRasterized();
+    }
+    if (group->contour.has_value() && group->contour->image != nullptr) {
+      group->contour->image = group->contour->image->makeRasterized();
+    }
+  }
+  auto* raw = source.get();
+  snapshots->layerStyleSources.emplace(layer, std::move(source));
+  return raw;
+}
+
+const LayerStyleSource* BackgroundConsumer::getCachedLayerStyleSource(Layer* layer) const {
+  if (snapshots == nullptr) {
+    return nullptr;
+  }
+  auto it = snapshots->layerStyleSources.find(layer);
+  if (it == snapshots->layerStyleSources.end()) {
+    return nullptr;
+  }
+  return it->second.get();
+}
+
+void BackgroundConsumer::drawBackgroundStyle(const DrawArgs& args, Canvas* canvas, Layer* layer,
+                                             float alpha, LayerStyle* style,
+                                             const LayerStyleSource* source) {
+  if (source == nullptr || FloatNearlyZero(source->contentScale)) {
+    return;
+  }
+  auto groupIndex = static_cast<int>(style->excludeChildEffects());
+  auto* group = source->groups[groupIndex].get();
+  if (group == nullptr) {
+    return;
+  }
+  const auto& contentEntry = group->content;
+  std::shared_ptr<Image> bgImage = nullptr;
+  Point bgOffset = {};
+  if (snapshots != nullptr) {
+    BackgroundSnapshotKey key{layer, style};
+    auto it = snapshots->snapshots.find(key);
+    if (it == snapshots->snapshots.end()) {
+      // Surface path: the map is authoritative, so a miss is a capture-side coverage bug.
+      // Silently skip rather than masking the bug with on-the-fly synthesis.
+      return;
+    }
+    auto& cursor = readCursors[key];
+    DEBUG_ASSERT(cursor < it->second.size() && "capture/consume push-pop count mismatch");
+    if (cursor >= it->second.size()) {
+      return;
+    }
+    auto& entry = it->second[cursor++];
+    bgImage = entry.image;
+    bgOffset = entry.offset;
+  } else {
+    // Picture-canvas path: capture was skipped because there is no GPU context. Synthesize the
+    // backdrop on the fly by walking ancestors and prior siblings via PictureRecorder.
+    bgImage = layer->synthesizeBackgroundImage(args, source->contentScale, &bgOffset);
+    if (bgImage == nullptr) {
+      return;
+    }
+  }
+  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);
+  auto backgroundOffset = bgOffset - contentEntry.offset;
+  LayerStyleInput styleInput = {};
+  styleInput.content = contentEntry.image;
+  styleInput.contentOffset = contentEntry.offset;
+  styleInput.contentScale = source->contentScale;
+  styleInput.extraSource = std::make_shared<StyleInputSource>(std::move(bgImage), backgroundOffset);
+  style->draw(canvas, styleInput, alpha);
+}
+
+void BackgroundCapturer::Run(Layer* captureRoot, const DrawArgs& baseArgs,
+                             std::shared_ptr<BackgroundSource> bgSource,
+                             BackgroundSnapshotMap* snapshots,
+                             const std::vector<Rect>& renderRects) {
+  DEBUG_ASSERT(captureRoot != nullptr);
+  DEBUG_ASSERT(bgSource != nullptr);
+  DEBUG_ASSERT(snapshots != nullptr);
+  if (renderRects.empty()) {
+    return;
+  }
+
+  auto* bgCanvas = bgSource->getCanvas();
+  BackgroundCapturer capturer(snapshots, std::move(bgSource));
+  AutoCanvasRestore autoRestore(bgCanvas);
+  DrawArgs captureArgs = baseArgs;
+  captureArgs.backgroundHandler = &capturer;
+  captureArgs.renderRects = &renderRects;
+  captureRoot->drawLayer(captureArgs, bgCanvas, 1.0f, BlendMode::SrcOver);
+}
+
+}  // namespace tgfx

package/cpp/third_party/tgfx/src/layers/BackgroundHandler.h

@@ -0,0 +1,217 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2026 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
+
+#include <memory>
+#include <unordered_map>
+#include <vector>
+#include "layers/BackgroundSnapshotMap.h"
+#include "tgfx/core/Matrix.h"
+#include "tgfx/core/Rect.h"
+
+namespace tgfx {
+
+class BackgroundCapturer;
+class BackgroundSource;
+class Canvas;
+class DrawArgs;
+class Layer;
+class LayerStyle;
+class Surface;
+struct LayerStyleSource;
+
+/**
+ * Strategy for rendering Background-sourced LayerStyles.
+ *   - BackgroundCapturer: samples the bg surface into a snapshot map during the capture pass.
+ *   - BackgroundConsumer: blits matched snapshots back during the consume pass.
+ *   - NoOp: skips Background-sourced styles (intermediate artifacts, 3D subtrees).
+ * The active handler lives on DrawArgs::backgroundHandler.
+ */
+class BackgroundHandler {
+ public:
+  virtual ~BackgroundHandler() = default;
+
+  static BackgroundHandler* NoOp();
+
+  // Dispatches a background-sourced style through args.backgroundHandler, or NoOp if null.
+  static void DispatchOrSkip(const DrawArgs& args, Canvas* canvas, Layer* layer, float alpha,
+                             LayerStyle* style, const LayerStyleSource* source);
+
+  virtual void drawBackgroundStyle(const DrawArgs& args, Canvas* canvas, Layer* layer, float alpha,
+                                   LayerStyle* style, const LayerStyleSource* source) = 0;
+
+  // Returns this handler as a BackgroundCapturer pointer, or nullptr if it is not one.
+  // Replaces isCapturer() + static_cast with a single type-safe query that the compiler enforces.
+  virtual BackgroundCapturer* asCapturer() {
+    return nullptr;
+  }
+
+  // Returns true when descendants of `layer` should render onto a real Surface so a sub
+  // background source can sample them back. Capturer returns true only when `layer` actually has
+  // descendant background-sourced styles AND a GPU context is available; Consumer / NoOp always
+  // return false.
+  virtual bool needsSurface(Layer* /*layer*/) const {
+    return false;
+  }
+
+  // Builds a sub-handler bound to a Surface-backed sub bg source. `localToWorld` maps the
+  // layer's local space to root device; `localToSurface` maps it to the sub surface's pixels.
+  // Returns nullptr when the parent handler does not need rebinding for this offscreen subtree
+  // (e.g. Consumer, which is canvas-matrix independent), letting the caller keep the parent.
+  virtual std::unique_ptr<BackgroundHandler> createSubHandler(
+      Surface* /*surface*/, const DrawArgs& /*parentArgs*/, const Rect& /*localBounds*/,
+      const Matrix& /*localToWorld*/, const Matrix& /*localToSurface*/) const {
+    return nullptr;
+  }
+
+  // Returns the narrowed renderRects this sub-handler should use, or nullptr when the caller
+  // should keep the parent's renderRects. Only meaningful on handlers produced by
+  // createSubHandler; the base class default returns nullptr.
+  virtual const std::vector<Rect>* renderRects() const {
+    return nullptr;
+  }
+
+  // Returns the index of the last child in parent's children list that should be traversed
+  // during the capture pass, or -1 if no children need traversal. BackgroundCapturer overrides
+  // this to skip children after the last one with background styles.
+  virtual int lastCaptureChildIndex(const Layer* /*parent*/) const;
+
+  // Returns a previously cached LayerStyleSource for the given layer, or nullptr if none. Capture
+  // and consume passes walk the same tree, so the source built in capture is reused in consume —
+  // avoiding redundant content/contour image renders. Default implementation returns nullptr so
+  // NoOp handlers don't engage caching.
+  virtual const LayerStyleSource* getCachedLayerStyleSource(Layer* /*layer*/) const {
+    return nullptr;
+  }
+
+  // Whether this handler will cache a LayerStyleSource for `layer`. Used by Layer::drawDirectly
+  // to decide if `cacheLayerStyleSource` should be called.
+  virtual bool canCacheLayerStyleSource(Layer* /*layer*/) const {
+    return false;
+  }
+
+  // Takes ownership of `source` and caches it under `layer`, returning the raw pointer to the
+  // cached entry. Precondition: canCacheLayerStyleSource(layer) returned true.
+  virtual const LayerStyleSource* cacheLayerStyleSource(
+      Layer* /*layer*/, std::unique_ptr<LayerStyleSource> /*source*/) {
+    return nullptr;
+  }
+
+  // During the capture pass, a subtree that sits before a later bg-style sibling must draw all
+  // descendants so their content appears on the bg source surface. drawChildren wraps each such
+  // child draw in begin/endForceDrawChildren. Non-capturing handlers default to no-ops, so
+  // callers can invoke these unconditionally.
+  virtual void beginForceDrawChildren() {
+  }
+  virtual void endForceDrawChildren() {
+  }
+};
+
+class BackgroundCapturer : public BackgroundHandler {
+ public:
+  BackgroundCapturer(BackgroundSnapshotMap* snapshots, std::shared_ptr<BackgroundSource> source)
+      : snapshots(snapshots), bgSource(std::move(source)) {
+  }
+
+  void drawBackgroundStyle(const DrawArgs& args, Canvas* canvas, Layer* layer, float alpha,
+                           LayerStyle* style, const LayerStyleSource* source) override;
+
+  BackgroundCapturer* asCapturer() override {
+    return this;
+  }
+
+  bool needsSurface(Layer* layer) const override;
+
+  std::unique_ptr<BackgroundHandler> createSubHandler(Surface* surface, const DrawArgs& parentArgs,
+                                                      const Rect& localBounds,
+                                                      const Matrix& localToWorld,
+                                                      const Matrix& localToSurface) const override;
+
+  const std::vector<Rect>* renderRects() const override {
+    return _renderRects.empty() ? nullptr : &_renderRects;
+  }
+
+  int lastCaptureChildIndex(const Layer* parent) const override;
+
+  const LayerStyleSource* getCachedLayerStyleSource(Layer* layer) const override;
+
+  bool canCacheLayerStyleSource(Layer* layer) const override;
+
+  const LayerStyleSource* cacheLayerStyleSource(Layer* layer,
+                                                std::unique_ptr<LayerStyleSource> source) override;
+
+  void beginForceDrawChildren() override {
+    ++_forcedCaptureDepth;
+  }
+  void endForceDrawChildren() override {
+    --_forcedCaptureDepth;
+  }
+
+  // Runs a capture pass: replays captureRoot onto bgSource's canvas, populating snapshots. The
+  // replay walks the tree exactly once with renderRects set to the pre-outset world-space dirty
+  // rects. drawLayer culls each layer whose renderBounds does not intersect any of these rects.
+  static void Run(Layer* captureRoot, const DrawArgs& baseArgs,
+                  std::shared_ptr<BackgroundSource> bgSource, BackgroundSnapshotMap* snapshots,
+                  const std::vector<Rect>& renderRects);
+
+  // Exposes the snapshot map this capturer writes into, so per-fragment Sub3DCapturers spawned
+  // by 3D subtrees can append their composed-backdrop entries to the same map under the same
+  // (Layer, LayerStyle) keys that the consume pass will read back.
+  BackgroundSnapshotMap* snapshotMap() const {
+    return snapshots;
+  }
+
+ private:
+  bool isForcedCapture() const {
+    return _forcedCaptureDepth > 0;
+  }
+
+  std::unique_ptr<BackgroundCapturer> buildSubCapturer(
+      const DrawArgs& parentArgs, std::shared_ptr<BackgroundSource> subSource) const;
+
+  BackgroundSnapshotMap* snapshots = nullptr;
+  std::shared_ptr<BackgroundSource> bgSource = nullptr;
+  std::vector<Rect> _renderRects;
+  int _forcedCaptureDepth = 0;
+};
+
+class BackgroundConsumer : public BackgroundHandler {
+ public:
+  // A null snapshots pointer means the capture pass was skipped (picture-canvas path, no GPU
+  // context). In that case the consumer synthesizes backdrops on the fly via
+  // Layer::synthesizeBackgroundImage. When snapshots is non-null (surface path) the map is
+  // authoritative — a miss there indicates a capture-side coverage bug, so we silently skip
+  // rather than masking it with synthesis.
+  explicit BackgroundConsumer(BackgroundSnapshotMap* snapshots) : snapshots(snapshots) {
+  }
+
+  void drawBackgroundStyle(const DrawArgs& args, Canvas* canvas, Layer* layer, float alpha,
+                           LayerStyle* style, const LayerStyleSource* source) override;
+
+  const LayerStyleSource* getCachedLayerStyleSource(Layer* layer) const override;
+
+ private:
+  BackgroundSnapshotMap* snapshots = nullptr;
+  // Per-consumer read cursors: each (Layer, LayerStyle) entry list is consumed in dispatch order
+  // through this map, so a shared snapshot map can be consumed by multiple consumers (e.g. one
+  // per tile in tiled rendering) without cursors interfering.
+  std::unordered_map<BackgroundSnapshotKey, std::size_t, BackgroundSnapshotKeyHash> readCursors;
+};
+
+}  // namespace tgfx

package/cpp/third_party/tgfx/src/layers/BackgroundSnapshotMap.h

@@ -0,0 +1,102 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2026 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
+
+#include <memory>
+#include <unordered_map>
+#include "layers/LayerStyleSource.h"
+#include "tgfx/core/Image.h"
+#include "tgfx/core/Point.h"
+
+namespace tgfx {
+
+class Layer;
+class LayerStyle;
+
+/**
+ * A snapshot of the background image and its offset captured during the capture pass for a
+ * specific (Layer, LayerStyle) pair. Consumed during the consume pass by LayerStyle::draw via
+ * LayerStyleInput::extraSource.
+ */
+struct BackgroundSnapshotEntry {
+  std::shared_ptr<Image> image = nullptr;
+  Point offset = Point::Zero();
+};
+
+/**
+ * Identifies which background snapshot belongs to which layer style. Layer* and LayerStyle* are
+ * raw pointers; both are owned by shared_ptr in the layer tree and the map is built and consumed
+ * within a single render invocation, so the keys are valid for the map's entire lifetime.
+ */
+struct BackgroundSnapshotKey {
+  Layer* layer = nullptr;
+  LayerStyle* style = nullptr;
+
+  bool operator==(const BackgroundSnapshotKey& other) const {
+    return layer == other.layer && style == other.style;
+  }
+};
+
+struct BackgroundSnapshotKeyHash {
+  std::size_t operator()(const BackgroundSnapshotKey& key) const noexcept {
+    auto h1 = std::hash<const void*>{}(key.layer);
+    auto h2 = std::hash<const void*>{}(key.style);
+    // boost::hash_combine style mix: avoids the trivial collisions of h1 ^ (h2 << 1) when the
+    // two pointers share low bits (common for pool-allocated objects). Pick a platform-sized
+    // golden ratio so 32-bit builds do not warn about a 64-bit literal narrowing into size_t.
+    constexpr std::size_t GoldenRatio = sizeof(std::size_t) >= 8
+                                            ? static_cast<std::size_t>(0x9e3779b97f4a7c15ULL)
+                                            : static_cast<std::size_t>(0x9e3779b9UL);
+    return h1 ^ (h2 + GoldenRatio + (h1 << 6) + (h1 >> 2));
+  }
+};
+
+/**
+ * Carries background snapshots from the capture pass to the consume pass. Each (Layer, LayerStyle)
+ * key maps to a vector (not a single entry), since the same pair can be dispatched more than once
+ * within one render — e.g. a BackgroundBlur layer that gets split into multiple fragments by a
+ * 3D subtree's BSP. Capture pushes entries in dispatch order; consume reads them in the same
+ * order through a cursor that lives on BackgroundConsumer (per-consumer state), so that the same
+ * shared snapshot map can be consumed multiple times — once per tile in tiled rendering, or twice
+ * when partial-cache and on-screen passes share a cache. Normal 2D paths only ever push and read a
+ * single entry, which is equivalent to the previous single-value behaviour.
+ *
+ * Also caches LayerStyleSource per layer: capture and consume passes walk the same tree, so
+ * each layer's content/contour images are identical between passes. Building the source once in
+ * capture and reusing it in consume avoids redundant intermediate renders. LayerStyleSource is
+ * not list-ised because, even when a layer is split into multiple fragments, the source is
+ * built at most once and read N times — list semantics would offer no value here.
+ *
+ * Consumers (BackgroundConsumer) read the snapshots vector through their own readCursors state
+ * (per-consumer, stored on the consumer itself), not through the map. This is why callers that
+ * only need to hand a snapshot map to a consumer can pass a const pointer to the map while the
+ * consumer still advances its non-const cursor — the cursor is not on the map. It also explains
+ * why some call sites (e.g. DisplayList::drawTileTask) pass BackgroundSnapshotMap* as non-const
+ * despite not writing snapshots: the consumer's cursor state is co-located with the consumer,
+ * not the map, but the consumer is constructed with a mutable pointer so it can read the vector
+ * contents through a non-const path.
+ */
+struct BackgroundSnapshotMap {
+  std::unordered_map<BackgroundSnapshotKey, std::vector<BackgroundSnapshotEntry>,
+                     BackgroundSnapshotKeyHash>
+      snapshots = {};
+  std::unordered_map<Layer*, std::unique_ptr<LayerStyleSource>> layerStyleSources = {};
+};
+
+}  // namespace tgfx