@mlightcad/data-model 1.12.0 → 1.12.2

package/lib/misc/AcDbRenderingCache.d.ts

@@ -2,12 +2,77 @@ import { AcCmColor } from '@mlightcad/common';
 import { AcGeMatrix3d, AcGeVector3d } from '@mlightcad/geometry-engine';
 import { AcGiEntity, AcGiRenderer } from '@mlightcad/graphic-interface';
 import { AcDbBlockTableRecord } from '../database/AcDbBlockTableRecord';
+/**
+ * Optional timing counters for one cache-miss block build during
+ * {@link AcDbRenderingCache.draw}. Enable with
+ * {@link AcDbRenderingCache.profiling} = true.
+ */
+export interface AcDbRenderingCacheBlockMissProfile {
+    /** Block table record name (or `'(unnamed)'`). */
+    blockName: string;
+    /** Entity `worldDraw` + `group` time in ms (excludes compact). */
+    buildMs: number;
+    /** `compactForInstancing` time in ms. */
+    compactMs: number;
+    /** Time spent cloning the template in {@link AcDbRenderingCache.set}. */
+    setCloneMs: number;
+}
+/**
+ * Accumulated timing counters for {@link AcDbRenderingCache}.
+ * Only updated while {@link AcDbRenderingCache.profiling} is true.
+ */
+export interface AcDbRenderingCacheProfileStats {
+    /** Cache hit count (template already built). */
+    hits: number;
+    /** Cache miss count (template built on this call). */
+    misses: number;
+    /** Total time spent on hit path before apply/attribs (includes clone). */
+    hitMs: number;
+    /** Miss path: entity worldDraw + group, excluding compact. */
+    missBuildMs: number;
+    /** Miss path: compactForInstancing. */
+    missCompactMs: number;
+    /** Time spent in get() → fastDeepClone (hit clones). */
+    cloneMs: number;
+    /** Time spent in set() → fastDeepClone (store template). */
+    setCloneMs: number;
+    /** applyMatrix + attribute attach after template ready. */
+    applyMs: number;
+    /**
+     * Same counters as above but only for outermost `draw()` calls
+     * (excludes nested INSERT draws while building a parent template).
+     */
+    topLevel: {
+        /** Top-level cache hits. */
+        hits: number;
+        /** Top-level cache misses. */
+        misses: number;
+        /** Top-level hit-path time in ms. */
+        hitMs: number;
+        /** Top-level miss build time in ms. */
+        missBuildMs: number;
+        /** Top-level compact time in ms. */
+        missCompactMs: number;
+        /** Top-level hit-clone time in ms. */
+        cloneMs: number;
+        /** Top-level set-clone time in ms. */
+        setCloneMs: number;
+        /** Top-level apply/attribute time in ms. */
+        applyMs: number;
+    };
+    /** Per-block miss breakdown (all depths). */
+    blockMisses: AcDbRenderingCacheBlockMissProfile[];
+}
 /**
  * Internal class used to cache rendered results to avoid duplicated rendering.
  *
  * This class can be used to improve performance when rendering block references.
- * Because different colors will result in different materials, the block name and
- * color are used together to create the cache key.
+ * Blocks without ByBlock-colored entities share one color-independent template.
+ * Blocks that contain ByBlock entities still key by block name and color because
+ * different INSERT colors produce different materials.
+ *
+ * Templates are compacted (same-material leaves merged) before caching so each
+ * INSERT clones O(material) geometries instead of O(entity) geometries.
  *
  * @internal
  *
@@ -20,10 +85,30 @@ import { AcDbBlockTableRecord } from '../database/AcDbBlockTableRecord';
  * ```
  */
 export declare class AcDbRenderingCache {
-    /** Map of cached rendering results indexed by key */
+    /** Map of cached rendering results indexed by key. */
     private _blocks;
-    /** Singleton instance of the cache */
+    /** Singleton instance of the cache. */
     private static _instance?;
+    /**
+     * When true, {@link draw} / {@link get} / {@link set} accumulate
+     * {@link profileStats}. Off by default (zero overhead when false).
+     */
+    static profiling: boolean;
+    /**
+     * Mutable profile accumulator used while {@link profiling} is true.
+     */
+    private static _profileStats;
+    /** Nesting depth of {@link draw} while profiling (1 = outermost). */
+    private static _drawDepth;
+    /**
+     * Accumulated profile counters. Only updated while {@link profiling} is true.
+     */
+    static get profileStats(): Readonly<AcDbRenderingCacheProfileStats>;
+    /**
+     * Clears {@link profileStats} and draw nesting depth.
+     * Leaves {@link profiling} unchanged.
+     */
+    static resetProfile(): void;
     /**
      * Gets the singleton instance of the rendering cache.
      *
@@ -47,6 +132,9 @@ export declare class AcDbRenderingCache {
     /**
      * Creates a cache key by combining the block name and color.
      *
+     * Prefer {@link createCacheKey} when the block's ByBlock dependency is known,
+     * so color-independent blocks can share one template.
+     *
      * @param name - The block name
      * @param color - The resolved block color
      * @returns A unique key for the cache entry
@@ -59,9 +147,24 @@ export declare class AcDbRenderingCache {
      * ```
      */
     createKey(name: string, color: AcCmColor): string;
+    /**
+     * Creates a cache key, omitting color when the block has no ByBlock entities.
+     *
+     * Color-independent keys let INSERTs that differ only by layer (ByLayer
+     * traits remapped at instance time) share one compacted template.
+     *
+     * @param name - The block name
+     * @param color - The resolved INSERT color (used only when `hasByBlockColor`)
+     * @param hasByBlockColor - Whether any entity in the block uses ByBlock color
+     * @returns Cache key: `name` alone, or `name_color` when ByBlock entities exist
+     */
+    createCacheKey(name: string, color: AcCmColor, hasByBlockColor: boolean): string;
     /**
      * Stores rendering results of a block in the cache.
      *
+     * Deep-clones `group` so later mutations of the live instance cannot corrupt
+     * the cached template.
+     *
      * @param key - The key for the rendering results
      * @param group - The rendering results to store
      * @returns The stored rendering results (deep cloned)
@@ -75,8 +178,11 @@ export declare class AcDbRenderingCache {
     /**
      * Gets rendering results with the specified key.
      *
+     * Returns a deep clone so callers can transform the instance without
+     * mutating the cached template.
+     *
      * @param name - The key of the rendering results
-     * @returns The rendering results with the specified key, or undefined if not found
+     * @returns The cloned rendering results, or `undefined` if not found
      *
      * @example
      * ```typescript
@@ -102,7 +208,7 @@ export declare class AcDbRenderingCache {
      */
     has(name: string): boolean;
     /**
-     * Clears all cached rendering results.
+     * Clears all cached rendering results and disposes owned geometry.
      *
      * @example
      * ```typescript
@@ -111,6 +217,18 @@ export declare class AcDbRenderingCache {
      * ```
      */
     clear(): void;
+    /**
+     * Prebuilds color-independent block templates before entity flush.
+     *
+     * Skips layout blocks (`*Model_Space` / `*Paper_Space*`), empty blocks,
+     * anonymous `*U` blocks, and blocks that contain ByBlock-colored entities
+     * (those require the INSERT color and are built on demand).
+     *
+     * @param renderer - Renderer used to convert block entities
+     * @param blocks - Iterator over block table records
+     * @param progress - Optional progress callback `(built, total, blockName)`
+     */
+    prebuildAll(renderer: AcGiRenderer, blocks: Iterable<AcDbBlockTableRecord>, progress?: (built: number, total: number, blockName: string) => void | Promise<void>): Promise<void>;
     /**
      * Draws a block table record and optionally caches the result.
      *
@@ -120,9 +238,11 @@ export declare class AcDbRenderingCache {
      * @param renderer - The renderer to use for drawing
      * @param blockTableRecord - The block table record to draw
      * @param blockColor - The resolved color to use for rendering
+     * @param attributes - Attribute graphics to attach (WCS); converted to
+     *   block-local space when `transform` is provided
      * @param cache - Whether to cache the rendering result (default: true)
-     * @param transform - Optional transformation matrix to apply
-     * @param normal - Optional normal vector
+     * @param transform - Optional block-reference transformation matrix
+     * @param normal - Optional extrusion / normal vector
      * @returns The rendered entity
      *
      * @example
@@ -131,6 +251,7 @@ export declare class AcDbRenderingCache {
      *   renderer,
      *   blockRecord,
      *   new AcCmColor().setRGBValue(0xFF0000),
+     *   [],
      *   true,
      *   transform,
      *   normal
@@ -138,7 +259,37 @@ export declare class AcDbRenderingCache {
      * ```
      */
     draw(renderer: AcGiRenderer, blockTableRecord: AcDbBlockTableRecord, blockColor: AcCmColor, attributes?: AcGiEntity[], cache?: boolean, transform?: AcGeMatrix3d, normal?: AcGeVector3d): AcGiEntity | undefined;
+    /**
+     * Returns whether `block` should be excluded from {@link prebuildAll}.
+     *
+     * Skips layout blocks, anonymous `*U` blocks, blocks with ByBlock colors
+     * (key depends on INSERT color), and blocks with no visible entities.
+     *
+     * @param block - Block table record to evaluate.
+     * @returns `true` when the block should not be prebuilt.
+     */
+    private shouldSkipPrebuild;
+    /**
+     * Returns whether any visible entity in the block uses ByBlock color.
+     *
+     * @param blockTableRecord - Block whose entities are scanned.
+     * @returns `true` when at least one visible ByBlock-colored entity exists.
+     */
+    private blockHasByBlockColor;
+    /**
+     * Draws one visible entity and appends its graphic result to `results`.
+     *
+     * @param entity - Database entity to convert.
+     * @param results - Accumulator for graphic-interface entities.
+     * @param renderer - Renderer used for `worldDraw`.
+     */
     private addEntity;
+    /**
+     * Copies database identity/layer/visibility onto a graphic-interface entity.
+     *
+     * @param target - Graphic entity produced by `worldDraw`.
+     * @param source - Source database entity.
+     */
     private attachEntityInfo;
 }
 //# sourceMappingURL=AcDbRenderingCache.d.ts.map

package/lib/misc/AcDbRenderingCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcDbRenderingCache.d.ts","sourceRoot":"","sources":["../../src/misc/AcDbRenderingCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAGvE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB;IAC7B,qDAAqD;IACrD,OAAO,CAAC,OAAO,CAAyB;IACxC,sCAAsC;IACtC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAoB;IAE7C;;;;;;;;;OASG;IACH,MAAM,KAAK,QAAQ,uBAKlB;IAED;;;;;;;OAOG;;IAKH;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS;IAQxC;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAMlC;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM;IAQhB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM;IAIhB;;;;;;;;OAQG;IACH,KAAK;IAIL;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,IAAI,CACF,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAAE,oBAAoB,EACtC,UAAU,EAAE,SAAS,EACrB,UAAU,GAAE,UAAU,EAAO,EAC7B,KAAK,GAAE,OAAc,EACrB,SAAS,CAAC,EAAE,YAAY,EACxB,MAAM,CAAC,EAAE,YAAY;IAwEvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,gBAAgB;CAMzB"}
+{"version":3,"file":"AcDbRenderingCache.d.ts","sourceRoot":"","sources":["../../src/misc/AcDbRenderingCache.ts"],"names":[],"mappings":"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"}