ice-render 1.0.7 → 1.2.0

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

@@ -26,6 +26,14 @@ declare abstract class ICEComponent extends ICEEventTarget {
     parentNode: any;
     protected static instanceCounter: number;
     protected __dirty: boolean;
+    /**
+     * 本组件是否**已经真正绘制过一次**（`__renderCore` 走完了 doRender 才会置真）。
+     *
+     * 存在的意义：`dirty` 同时承担两个语义 —— 「本帧要重绘」和「几何缓存（`ICEPath.createPathObject`）
+     * 是否有效」。后者只在 doRender 里以 `if (this.dirty)` 的形式被消费，因此**从未渲染过的组件
+     * 一旦被置干净，它的路径缓存就永远不会被建立**，首次上屏是空的（见 `__applyDirty`）。
+     */
+    protected __everRendered: boolean;
     private __localBoxScratch;
     /** 本渲染通道的「本地 → 设备」CTM（主画布通道 = 视口·composed；离屏位图通道 = base·composed）。 */
     private __activeCtm;
@@ -286,6 +294,29 @@ declare abstract class ICEComponent extends ICEEventTarget {
      * 表现为「连线的箭头与标签在缓存位图里整块消失」——离屏缓存保真测试就是抓这个的。
      */
     protected applyActiveTransform(): void;
+    /**
+     * 是否存在开启 `clipChildren` 的祖先（热路径用，命中检测与离屏缓存的门控都要问它）。
+     * 顶层组件直接 O(1) 返回。
+     */
+    hasClippingAncestor(): boolean;
+    /**
+     * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
+     *
+     * 命中检测用它实现「滚出可视区的子组件点不到」—— 与渲染时的裁剪语义保持一致。
+     */
+    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 矩阵。
@@ -335,6 +366,17 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected __afterStateMerge(sizeChanged: boolean): void;
     set dirty(flag: boolean);
     get dirty(): boolean;
+    /**
+     * 按 `markDirty` 语义更新脏标记。
+     *
+     * `markDirty = false` 的含义是「这次操作**不要**主动把组件标记为要重绘」（批量挂载时的性能优化），
+     * 而**不是**「把它强制置干净」：对从未绘制过的组件置干净会让几何缓存永不建立，首次上屏画不出
+     * 自身的路径（`ICEPath.doRender` 只在 dirty 时调用 `createPathObject`）。
+     *
+     * 例：`UIButton` 构造函数里 `addChild(this.label, false)` 会把自己置干净，导致按钮的圆角矩形
+     * 背景/边框在首帧是空路径 —— 页面上表现为「白底白字、完全看不见的按钮」。
+     */
+    protected __applyDirty(markDirty: boolean): void;
     set paramsDirty(flag: boolean);
     get paramsDirty(): boolean;
     /**

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

@@ -26,6 +26,14 @@ declare abstract class ICEComponent extends ICEEventTarget {
     parentNode: any;
     protected static instanceCounter: number;
     protected __dirty: boolean;
+    /**
+     * 本组件是否**已经真正绘制过一次**（`__renderCore` 走完了 doRender 才会置真）。
+     *
+     * 存在的意义：`dirty` 同时承担两个语义 —— 「本帧要重绘」和「几何缓存（`ICEPath.createPathObject`）
+     * 是否有效」。后者只在 doRender 里以 `if (this.dirty)` 的形式被消费，因此**从未渲染过的组件
+     * 一旦被置干净，它的路径缓存就永远不会被建立**，首次上屏是空的（见 `__applyDirty`）。
+     */
+    protected __everRendered: boolean;
     private __localBoxScratch;
     /** 本渲染通道的「本地 → 设备」CTM（主画布通道 = 视口·composed；离屏位图通道 = base·composed）。 */
     private __activeCtm;
@@ -286,6 +294,29 @@ declare abstract class ICEComponent extends ICEEventTarget {
      * 表现为「连线的箭头与标签在缓存位图里整块消失」——离屏缓存保真测试就是抓这个的。
      */
     protected applyActiveTransform(): void;
+    /**
+     * 是否存在开启 `clipChildren` 的祖先（热路径用，命中检测与离屏缓存的门控都要问它）。
+     * 顶层组件直接 O(1) 返回。
+     */
+    hasClippingAncestor(): boolean;
+    /**
+     * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
+     *
+     * 命中检测用它实现「滚出可视区的子组件点不到」—— 与渲染时的裁剪语义保持一致。
+     */
+    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 矩阵。
@@ -335,6 +366,17 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected __afterStateMerge(sizeChanged: boolean): void;
     set dirty(flag: boolean);
     get dirty(): boolean;
+    /**
+     * 按 `markDirty` 语义更新脏标记。
+     *
+     * `markDirty = false` 的含义是「这次操作**不要**主动把组件标记为要重绘」（批量挂载时的性能优化），
+     * 而**不是**「把它强制置干净」：对从未绘制过的组件置干净会让几何缓存永不建立，首次上屏画不出
+     * 自身的路径（`ICEPath.doRender` 只在 dirty 时调用 `createPathObject`）。
+     *
+     * 例：`UIButton` 构造函数里 `addChild(this.label, false)` 会把自己置干净，导致按钮的圆角矩形
+     * 背景/边框在首帧是空路径 —— 页面上表现为「白底白字、完全看不见的按钮」。
+     */
+    protected __applyDirty(markDirty: boolean): void;
     set paramsDirty(flag: boolean);
     get paramsDirty(): boolean;
     /**

package/package.json

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