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

package/cpp/third_party/tgfx/include/tgfx/gpu/webgpu/WebGPUWindow.h

@@ -0,0 +1,55 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  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 "tgfx/gpu/Window.h"
+#include "tgfx/gpu/webgpu/WebGPUDevice.h"
+
+namespace tgfx {
+
+class WebGPUWindow : public Window {
+ public:
+  /**
+   * Creates a new window from an HTML canvas element selector with the specified device.
+   * @param canvasSelector The CSS selector for the HTML canvas element (e.g., "#myCanvas").
+   * @param device An optional WebGPUDevice. If nullptr, a default device is created automatically.
+   */
+  static std::shared_ptr<WebGPUWindow> MakeFrom(const std::string& canvasSelector,
+                                                std::shared_ptr<WebGPUDevice> device = nullptr);
+
+  ~WebGPUWindow() override;
+
+ protected:
+  std::shared_ptr<RenderTargetProxy> onCreateRenderTarget(Context* context) override;
+  void onPresent(Context* context) override;
+
+ private:
+  WebGPUWindow(std::shared_ptr<Device> device, void* surface, int width, int height,
+               const std::string& canvasSelector);
+
+  std::string _canvasSelector;
+  void* _surface = nullptr;
+  int _width = 0;
+  int _height = 0;
+  int _configuredWidth = 0;
+  int _configuredHeight = 0;
+  std::shared_ptr<RenderTargetProxy> drawableProxy = nullptr;
+};
+
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/layers/DisplayList.h

@@ -0,0 +1,407 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  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.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <deque>
+#include <unordered_map>
+#include "tgfx/core/Surface.h"
+#include "tgfx/layers/Layer.h"
+
+namespace tgfx {
+class RootLayer;
+class Tile;
+class TileCache;
+class DrawTask;
+struct BackgroundSnapshotMap;
+
+/**
+ * RenderMode defines the different modes of rendering a DisplayList.
+ */
+enum class RenderMode {
+  /**
+   * Direct rendering mode. In this mode, the display list is rendered directly to the target
+   * surface without any caching or optimization.
+   */
+  Direct,
+
+  /**
+   * Partial rendering mode. In this mode, only the dirty regions of the display list are rendered
+   * to the target surface. This can improve performance when only a small part of the display list
+   * changes. However, enabling partial rendering may cause some blending issues, since all layers
+   * are first drawn onto a cached surface before being composited onto the target surface. Partial
+   * rendering also requires extra memory (equal to the size of the target surface) to cache the
+   * previous frame. This is the default rendering mode.
+   */
+  Partial,
+
+  /**
+   * Tiled rendering mode. In this mode, the display list is split into tiles, and each tile is
+   * cached separately. This improves performance by redrawing only the parts of the display list
+   * that have changed, and also enables efficient scrolling and zooming using contentOffset and
+   * zoomScale. Only the portions of tiles that overlap dirty regions are redrawn, not the entire
+   * tile. Whenever possible, adjacent tiles are combined into a single draw call to reduce the
+   * total number of draw calls. Performance is similar to partial rendering when the viewport isn’t
+   * zoomed or scrolled, though tiled rendering uses a bit more memory. However, for zooming and
+   * scrolling, tiled rendering is much more efficient than partial rendering.
+   */
+  Tiled
+};
+
+/**
+ * TileUpdateMode defines how missing tiles are produced in tiled rendering mode when the
+ * zoomScale changes or when the viewport scrolls into uncached regions.
+ */
+enum class TileUpdateMode {
+  /**
+   * Missing tiles are rasterized at the current zoomScale within the same frame. Cached tiles
+   * from other zoom scales are never reused. This produces the highest visual fidelity but may
+   * cause frame drops during heavy zoom or pan. This is the default mode.
+   */
+  Immediate,
+
+  /**
+   * For each missing tile, the display list first tries to reuse a cached tile from another
+   * zoom scale as a temporary fallback (producing brief zoom blur). When no such cache is
+   * available, the tile is rasterized at the current zoomScale within the same frame to keep
+   * the result correct. Use this mode when you want a smoother visual transition during zoom
+   * while still guaranteeing visible content on every frame.
+   */
+  Smooth,
+
+  /**
+   * The number of tiles rasterized per frame is capped by setMaxTilesRefinedPerFrame(). Tiles
+   * beyond the cap are filled with cached content from other zoom scales, or with the background
+   * color when no fallback is available. This keeps the frame rate stable during heavy zoom or
+   * pan at the cost of longer-lasting blur or background-colored regions.
+   */
+  Fast
+};
+
+/**
+ * DisplayList represents a collection of layers can be drawn to a Surface. Note: All layers in the
+ * display list are not thread-safe and should only be accessed from a single thread.
+ */
+class DisplayList {
+ public:
+  DisplayList();
+
+  virtual ~DisplayList();
+
+  /**
+   * Returns the root layer of the display list. Note: The root layer cannot be added to another
+   * layer. Therefore, properties like alpha, blendMode, position, matrix, visibility, scrollRect,
+   * and mask have no effect on the root layer since it will never have a parent.
+   */
+  Layer* root() const;
+
+  /**
+   * Returns the current scale factor applied to the layer tree. This factor determines how much the
+   * layer tree is scaled during rendering. Adjusting the zoomScale to scale the layer tree is more
+   * efficient than applying a matrix directly, as it avoids invalidating the layer tree's internal
+   * caches. The default value is 1.0f.
+   */
+  float zoomScale() const;
+
+  /**
+   * Sets the scale factor for the layer tree. This factor determines how much the layer tree is
+   * scaled during rendering. Adjusting the zoomScale to scale the layer tree is more efficient than
+   * applying a matrix directly, as it avoids invalidating the layer tree's internal caches. The
+   * default value is 1.0f.
+   */
+  void setZoomScale(float zoomScale);
+
+  /**
+   * Returns the integer multiplier used for zoom scale precision. This value determines the
+   * smallest step by which the zoom scale can change. For example, a precision of 100 means the
+   * zoom scale can be adjusted in increments of 0.01 (1/100). Internally, the zoom scale is stored
+   * as an integer. The precision is used to convert the zoom scale to an integer as follows:
+   * - When zooming in (scale >= 1.0), the scale is multiplied by the precision.
+   * - When zooming out (scale < 1.0), the reciprocal of the scale is multiplied by the precision.
+   * The default precision is 1000, allowing zoom scale adjustments in steps of 0.001f.
+   */
+  int zoomScalePrecision() const {
+    return _zoomScalePrecision;
+  }
+
+  /**
+   * Sets the integer multiplier used for zoom scale precision.
+   */
+  void setZoomScalePrecision(int precision);
+
+  /**
+   * Returns the current content offset of the layer tree after applying the zoomScale. This offset
+   * determines how far the origin of the layer tree is shifted relative to the surface's origin.
+   * Adjusting the contentOffset to move the layer tree is more efficient than applying a matrix
+   * directly, as it avoids invalidating the layer tree's internal caches. The default value is
+   * (0, 0).
+   */
+  const Point& contentOffset() const {
+    return _contentOffset;
+  }
+
+  /**
+   * Sets the content offset of the layer tree after applying the zoomScale. This offset determines
+   * how far the origin of the layer tree is shifted relative to the surface's origin. Adjusting the
+   * contentOffset to move the layer tree is more efficient than applying a matrix directly, as it
+   * avoids invalidating the layer tree's internal caches. The default value is (0, 0).
+   * Note: The provided values are rounded to the nearest integer pixels internally to ensure
+   * pixel-perfect alignment across different rendering modes.
+   */
+  void setContentOffset(float offsetX, float offsetY);
+
+  /**
+   * Returns the current render mode of the display list. The render mode determines how the display
+   * list is rendered to the target surface. The default render mode is RenderMode::Partial.
+   */
+  RenderMode renderMode() const {
+    return _renderMode;
+  }
+
+  /**
+   * Sets the render mode of the display list. The render mode determines how the display list is
+   * rendered to the target surface. The default render mode is RenderMode::Partial.
+   */
+  void setRenderMode(RenderMode renderMode);
+
+  /**
+   * Returns the tile size used in tiled rendering mode. This setting is ignored in other render
+   * modes. It specifies the width and height of each tile when rendering the display list in tiled
+   * mode. The tile size must be between 16 and 2048 pixels and should be a power of two. The
+   * default is 256 pixels.
+   */
+  int tileSize() const {
+    return _tileSize;
+  }
+
+  /**
+   * Sets the size of the tiles used in tiled rendering mode.
+   */
+  void setTileSize(int tileSize);
+
+  /**
+   * Returns the maximum number of tiles that can be created in tiled rendering mode. This setting
+   * is ignored in other render modes. Allowing more tiles can improve performance, especially when
+   * zooming. If the specified count is less than the minimum required for tiled rendering, it will
+   * be automatically increased to meet the minimum. The minimum value is calculated based on the
+   * tile size and viewport size, ensuring the visible area is always fully covered, even if the
+   * viewport is offset by half a tile. For example, with a tile size of 256 pixels and a viewport
+   * of 512x512 pixels, the minimum tile count is 9 (2 tiles in each direction plus 1 for offset).
+   * The minimum tile count is sufficient for scrolling without zooming. If you plan to zoom
+   * frequently, you should set a higher maximum tile count to avoid performance issues. The default
+   * value is 0, which means the minimum tile count will be used based on the viewport size and tile
+   * size.
+   */
+  int maxTileCount() const {
+    return _maxTileCount;
+  }
+
+  /**
+   * Sets the maximum number of tiles that can be created in tiled rendering mode.
+   */
+  void setMaxTileCount(int count);
+
+  /**
+   * Returns the current tile update mode. This setting only applies in tiled rendering mode and
+   * controls how missing tiles are produced when the zoomScale changes. The default is
+   * TileUpdateMode::Immediate.
+   */
+  TileUpdateMode tileUpdateMode() const {
+    return _tileUpdateMode;
+  }
+
+  /**
+   * Sets the tile update mode used in tiled rendering mode.
+   */
+  void setTileUpdateMode(TileUpdateMode mode) {
+    _tileUpdateMode = mode;
+  }
+
+  /**
+   * Returns the per-frame budget for rasterizing missing tiles. This setting only applies in
+   * tiled rendering mode and is ignored when tileUpdateMode() is TileUpdateMode::Immediate. In
+   * TileUpdateMode::Smooth, once the budget is exhausted, tiles that have a cached fallback at
+   * another zoom scale will display the fallback instead of being rasterized; tiles without any
+   * fallback are still rasterized in the same frame to keep the result correct, so the actual
+   * tiles drawn per frame may exceed this limit. In TileUpdateMode::Fast, the budget is a hard
+   * cap: tiles beyond it fall back to cached content from other zoom scales, or are filled with
+   * the background color when no fallback is available. Higher values fill the screen faster
+   * during zoom and pan at the cost of per-frame GPU load; lower values prioritize stable frame
+   * rate.
+   */
+  int maxTilesRefinedPerFrame() const {
+    return _maxTilesRefinedPerFrame;
+  }
+
+  /**
+   * Sets the maximum number of tiles processed per frame in tiled rendering mode.
+   */
+  void setMaxTilesRefinedPerFrame(int count) {
+    _maxTilesRefinedPerFrame = count;
+  }
+
+  /**
+   * Returns the background color of the display list. The background is an infinite rectangle that
+   * covers the entire display area and is drawn using the SrcOver blend mode during rendering.
+   * It is only drawn in the DisplayList::render() path, not when calling Layer::draw() directly.
+   * The default value is transparent.
+   */
+  Color backgroundColor() const {
+    return _backgroundColor;
+  }
+
+  /**
+   * Sets the background color of the display list.
+   */
+  void setBackgroundColor(const Color& color);
+
+  /**
+   * Returns the maximum cache size (longest edge in pixels) for subtree caching. Default is 0
+   * (disabled).
+   *
+   * When enabled, starting from the root layer, any static subtree (where neither the layer nor
+   * its descendants have modified properties) whose rendered longest edge is smaller than maxSize
+   * will be cached as a texture. The cache uses a mipmap-style scaling strategy, snapping to
+   * power-of-2 fractions of maxSize (e.g., maxSize, maxSize/2, maxSize/4, ...) to minimize memory
+   * waste. Once a subtree is cached, subsequent renders skip child traversal entirely, greatly
+   * improving rendering performance. This optimization is particularly effective in zoom-out
+   * scenarios where dense graphics are packed into a smaller screen area.
+   */
+  int subtreeCacheMaxSize() const {
+    return _subtreeCacheMaxSize;
+  }
+
+  /**
+   * Sets the maximum cache size (longest edge in pixels) for subtree caching. Default is 0 (disabled).
+   */
+  void setSubtreeCacheMaxSize(int maxSize);
+
+  /**
+   * Sets whether to show dirty regions during rendering. When enabled, the dirty regions will be
+   * highlighted in the rendered output. This is useful for debugging to visualize which parts of
+   * the display list are being updated. The default value is false.
+   */
+  void showDirtyRegions(bool show);
+
+  /**
+   * Returns true if the content of the display list has changed since the last rendering. This can
+   * be used to determine if the display list needs to be re-rendered.
+   */
+  bool hasContentChanged() const;
+
+  /**
+   * Renders the display list onto the given surface.
+   * @param surface The surface to render the display list on.
+   * @param autoClear If true, the surface will be cleared before rendering the display list.
+   * Otherwise, the display list will be rendered over the existing content.
+   */
+  void render(Surface* surface, bool autoClear = true);
+
+ private:
+  std::shared_ptr<RootLayer> _root = nullptr;
+  Color _backgroundColor = Color::Transparent();
+  int64_t _zoomScaleInt = 1000;
+  int _zoomScalePrecision = 1000;
+  Point _contentOffset = {};
+  RenderMode _renderMode = RenderMode::Partial;
+  int _tileSize = 256;
+  int _maxTileCount = 0;
+  TileUpdateMode _tileUpdateMode = TileUpdateMode::Immediate;
+  int _maxTilesRefinedPerFrame = 5;
+  int _subtreeCacheMaxSize = 0;
+  bool _showDirtyRegions = false;
+  bool _hasContentChanged = false;
+  bool hasZoomBlurTiles = false;
+  int64_t lastZoomScaleInt = 1000;
+  Point lastContentOffset = {};
+  Point mousePosition = {};
+  int totalTileCount = 0;
+  std::vector<std::shared_ptr<Surface>> surfaceCaches = {};
+  std::unordered_map<int64_t, TileCache*> tileCaches = {};
+  std::vector<std::shared_ptr<Tile>> emptyTiles = {};
+  std::deque<std::vector<Rect>> lastDirtyRegions = {};
+
+  std::vector<Rect> renderDirect(Surface* surface, bool autoClear) const;
+
+  std::vector<Rect> renderPartial(Surface* surface, bool autoClear,
+                                  const std::vector<Rect>& dirtyRegions);
+
+  std::vector<Rect> renderTiled(Surface* surface, bool autoClear,
+                                const std::vector<Rect>& dirtyRegions);
+
+  void checkTileCount(Surface* renderSurface);
+
+  std::vector<DrawTask> invalidateTileCaches(const std::vector<Rect>& dirtyRegions);
+
+  void invalidateCurrentTileCache(const TileCache* tileCache, const std::vector<Rect>& dirtyRegions,
+                                  std::vector<DrawTask>* tileTasks) const;
+
+  void recycleCurrentTileTasks(const std::vector<DrawTask>& tileTasks);
+
+  std::vector<DrawTask> collectScreenTasks(const Surface* surface, bool hasDirtyRegions,
+                                           bool autoClear, std::vector<DrawTask>* tileTasks,
+                                           std::vector<Rect>* skippedRects,
+                                           std::vector<DrawTask>* throttleScreenTasks);
+
+  std::vector<std::pair<float, TileCache*>> getSortedTileCaches() const;
+
+  std::vector<std::pair<float, TileCache*>> getFallbackTileCaches(
+      const std::vector<std::pair<float, TileCache*>>& sortedCaches) const;
+
+  std::vector<DrawTask> getFallbackDrawTasks(
+      int tileX, int tileY, const std::vector<std::pair<float, TileCache*>>& fallbackCaches) const;
+
+  std::vector<DrawTask> getThrottleFallbackTasks(
+      int tileX, int tileY, const std::vector<std::pair<float, TileCache*>>& fallbackCaches) const;
+
+  std::vector<std::shared_ptr<Tile>> getFreeTiles(
+      const Surface* renderSurface, size_t tileCount,
+      const std::vector<std::pair<float, TileCache*>>& sortedCaches);
+
+  std::vector<std::shared_ptr<Tile>> createContinuousTiles(const Surface* renderSurface,
+                                                           int requestCountX, int requestCountY);
+
+  bool createEmptyTiles(const Surface* renderSurface);
+
+  int nextSurfaceTileCount(Context* context) const;
+
+  int getMaxTileCountPerAtlas(Context* context) const;
+
+  void drawTileTask(const DrawTask& task, BackgroundSnapshotMap* snapshots) const;
+
+  void drawScreenTasks(std::vector<DrawTask> screenTasks, std::vector<Rect> skippedRects,
+                       Surface* surface, bool autoClear) const;
+
+  void drawThrottleScreenTasks(std::vector<DrawTask> throttleScreenTasks, Surface* surface,
+                               bool autoClear) const;
+
+  void renderDirtyRegions(Canvas* canvas, std::vector<Rect> dirtyRegions);
+
+  Matrix getViewMatrix() const;
+
+  void resetCaches();
+
+  void drawRootLayer(Surface* surface, const Rect& drawRect, const Matrix& viewMatrix,
+                     bool autoClear, BackgroundSnapshotMap* snapshots) const;
+
+  std::unique_ptr<BackgroundSnapshotMap> captureBackgrounds(
+      Surface* surface, const std::vector<Rect>& renderRects) const;
+
+  void updateMousePosition();
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/layers/ImageLayer.h

@@ -0,0 +1,74 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  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.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include "tgfx/core/Image.h"
+#include "tgfx/layers/Layer.h"
+
+namespace tgfx {
+/**
+ * ImageLayer represents a layer that displays an image.
+ */
+class ImageLayer : public Layer {
+ public:
+  /**
+   * Creates a new image layer.
+   */
+  static std::shared_ptr<ImageLayer> Make();
+
+  LayerType type() const override {
+    return LayerType::Image;
+  }
+
+  /**
+   * Returns the sampling options used to draw the image. The default value is
+   * SamplingOptions(FilterMode::Linear, MipmapMode::Linear).
+   */
+  SamplingOptions sampling() const {
+    return _sampling;
+  }
+
+  /**
+   * Sets the sampling options used to display the image.
+   */
+  void setSampling(const SamplingOptions& value);
+
+  /**
+   * Returns the image displayed by this layer.
+   */
+  std::shared_ptr<Image> image() const {
+    return _image;
+  }
+
+  /**
+   * Sets the image displayed by this layer.
+   */
+  void setImage(std::shared_ptr<Image> value);
+
+ protected:
+  ImageLayer() : _sampling(FilterMode::Linear, MipmapMode::Linear) {
+  }
+
+  void onUpdateContent(LayerRecorder* recorder) override;
+
+ private:
+  SamplingOptions _sampling;
+  std::shared_ptr<Image> _image = nullptr;
+};
+}  // namespace tgfx