ice-render 1.1.0 → 1.3.0

package/dist/types/graphic/ICEComponent.d.mts

@@ -42,6 +42,8 @@ declare abstract class ICEComponent extends ICEEventTarget {
     /** 可见性缓存（代际号 + 值）：见 `isEffectivelyVisible` 的说明。 */
     private __visEpoch;
     private __visValue;
+    /** 本帧是否因为子树不透明度过 ctx.globalAlpha（见 __renderCore / __resetLeakyCtxState）。 */
+    private __opacityApplied;
     /** 声明式渐变缓存：按描述对象引用判定，`refreshParams()` 里失效（setState 必然触发它）。 */
     private __gradCache;
     /**
@@ -294,6 +296,35 @@ declare abstract class ICEComponent extends ICEEventTarget {
      * 表现为「连线的箭头与标签在缓存位图里整块消失」——离屏缓存保真测试就是抓这个的。
      */
     protected applyActiveTransform(): void;
+    /**
+     * 是否存在开启 `clipChildren` 的祖先（热路径用，命中检测与离屏缓存的门控都要问它）。
+     * 顶层组件直接 O(1) 返回。
+     */
+    hasClippingAncestor(): boolean;
+    /**
+     * 有效不透明度 = 自身 `state.opacity` × 所有祖先的 `state.opacity`（默认 1）。
+     *
+     * 顶层组件直接返回（绝大多数组件没有祖先，热路径上不做遍历）；非法值按 1 处理。
+     */
+    private __effectiveOpacity;
+    /**
+     * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
+     *
+     * 命中检测用它实现「滚出可视区的子组件点不到」—— 与渲染时的裁剪语义保持一致。
+     */
+    isPointClippedOut(wx: number, wy: number): boolean;
+    /**
+     * 把「裁剪祖先」的盒子作为裁剪区应用到 ctx —— 在**设备空间**建立。
+     *
+     * 做法与脏矩形路径一致（见 CanvasRenderer 的局部重绘分支）：
+     * `setTransform(单位矩阵) → rect → clip → 复原本组件 CTM`。clip 记录在 ctx 的裁剪状态里，
+     * 之后组件自己 `setTransform` 不会清掉它；`restore()` 才移除。
+     *
+     * 祖先有旋转/缩放时按其世界 AABB 裁剪（保守，宁可多裁不可漏裁）。
+     *
+     * @returns 是否建立过裁剪（true 时调用方必须 `ctx.restore()`）
+     */
+    private __applyAncestorClips;
     /**
      * 把「世界 → 设备」矩阵应用到 ctx。
      * debug 包围盒的坐标本身就是世界坐标，不能套「本地 → 世界」的 composed 矩阵。

package/dist/types/graphic/ICEComponent.d.ts

@@ -42,6 +42,8 @@ declare abstract class ICEComponent extends ICEEventTarget {
     /** 可见性缓存（代际号 + 值）：见 `isEffectivelyVisible` 的说明。 */
     private __visEpoch;
     private __visValue;
+    /** 本帧是否因为子树不透明度过 ctx.globalAlpha（见 __renderCore / __resetLeakyCtxState）。 */
+    private __opacityApplied;
     /** 声明式渐变缓存：按描述对象引用判定，`refreshParams()` 里失效（setState 必然触发它）。 */
     private __gradCache;
     /**
@@ -294,6 +296,35 @@ declare abstract class ICEComponent extends ICEEventTarget {
      * 表现为「连线的箭头与标签在缓存位图里整块消失」——离屏缓存保真测试就是抓这个的。
      */
     protected applyActiveTransform(): void;
+    /**
+     * 是否存在开启 `clipChildren` 的祖先（热路径用，命中检测与离屏缓存的门控都要问它）。
+     * 顶层组件直接 O(1) 返回。
+     */
+    hasClippingAncestor(): boolean;
+    /**
+     * 有效不透明度 = 自身 `state.opacity` × 所有祖先的 `state.opacity`（默认 1）。
+     *
+     * 顶层组件直接返回（绝大多数组件没有祖先，热路径上不做遍历）；非法值按 1 处理。
+     */
+    private __effectiveOpacity;
+    /**
+     * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
+     *
+     * 命中检测用它实现「滚出可视区的子组件点不到」—— 与渲染时的裁剪语义保持一致。
+     */
+    isPointClippedOut(wx: number, wy: number): boolean;
+    /**
+     * 把「裁剪祖先」的盒子作为裁剪区应用到 ctx —— 在**设备空间**建立。
+     *
+     * 做法与脏矩形路径一致（见 CanvasRenderer 的局部重绘分支）：
+     * `setTransform(单位矩阵) → rect → clip → 复原本组件 CTM`。clip 记录在 ctx 的裁剪状态里，
+     * 之后组件自己 `setTransform` 不会清掉它；`restore()` 才移除。
+     *
+     * 祖先有旋转/缩放时按其世界 AABB 裁剪（保守，宁可多裁不可漏裁）。
+     *
+     * @returns 是否建立过裁剪（true 时调用方必须 `ctx.restore()`）
+     */
+    private __applyAncestorClips;
     /**
      * 把「世界 → 设备」矩阵应用到 ctx。
      * debug 包围盒的坐标本身就是世界坐标，不能套「本地 → 世界」的 composed 矩阵。

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-render",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "A canvas engine for interactive graphics.",
   "repository": {
     "type": "git",