ldr 0.13.0 → 0.15.0

package/dist/render.d.ts

@@ -70,25 +70,21 @@ export declare function computeCulling(insts: Inst[], H: any): {
     }[];
     underHidden: boolean[];
 };
-export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, color: (c: string) => THREE.Color, mark: (k: string) => void): {
-    root: THREE.Group;
-    stats: any;
-    setCull: (studs: boolean, under: boolean) => void;
-    setSide: (front: boolean) => void;
-    setEdges: (v: boolean) => void;
-    setCond: (v: boolean) => void;
-    setLod: (on: boolean) => void;
-    setStep: (s: number | null, mask?: ArrayLike<number | boolean> | null) => {
-        studsTotal: number;
-        studsHidden: number;
-        undersTotal: number;
-        undersHidden: number;
-    };
-    box: THREE.Box3;
-    texturesReady: Promise<void>;
-};
 /**
  * Builds (and caches on the pack) the shared BufferGeometries `buildLdrScene` will use, in time slices of about `sliceMs` that yield
  * to the event loop, until done or `stop()` returns true. Lets the main thread do this useful work while the load worker culls.
  */
+/** Drive buildLdrSceneGen to completion without yielding (same as pre-Round-33 sync build). */
+export declare function buildLdrScene(insts: Inst[], pack: Pack, P: LdrParams, color: (c: string) => THREE.Color, mark: (k: string) => void): any;
+export type BuildLdrSceneAsyncOptions = {
+    /** Soft cap on contiguous main-thread work between yields (ms). Default 8. */
+    sliceMs?: number;
+    /** Called after each yield while the live root already holds finished batches (paint for TTFP). */
+    onSlice?: (root: THREE.Object3D) => void | Promise<void>;
+};
+/**
+ * Same scene as buildLdrScene, but yields to the event loop about every sliceMs so the main thread stays responsive
+ * and onSlice can render partial geometry for a fast time-to-first-pixel. Meshes are added to root as they are built.
+ */
+export declare function buildLdrSceneAsync(insts: Inst[], pack: Pack, P: LdrParams, color: (c: string) => THREE.Color, mark: (k: string) => void, opts?: BuildLdrSceneAsyncOptions): Promise<any>;
 export declare function warmPackGeometry(pack: Pack, stop?: () => boolean, sliceMs?: number): Promise<void>;

package/dist/scene.d.ts

@@ -51,6 +51,10 @@ export interface LdrObjectOptions {
     /** LOD: skip undersides that can't be seen: while the camera is behind every bottom face of a cluster's (same-orientation) parts and
      *  studs are under 4 px, or where the body is drawn as its closed bounding box. Default true. */
     lodUnder?: boolean;
+    /** Progressive build (createLdrObjectAsync / loadModel): soft cap on contiguous main-thread work between yields, ms. Default 8. */
+    sliceMs?: number;
+    /** Progressive build: called after each yield; the live object already holds finished batches — render for TTFP. */
+    onSlice?: () => void | Promise<void>;
 }
 export interface LdrStats {
     instances: number;
@@ -61,6 +65,10 @@ export interface LdrStats {
     undersTotal: number;
     undersHidden: number;
     buildMs: number;
+    /** Progressive build: longest contiguous main-thread slice (ms). */
+    longestSliceMs?: number;
+    /** Progressive build: number of yields during scene construction. */
+    buildYields?: number;
     /** Conditional-line batches (draw calls) created; 0 for packs without conditional lines. */
     condBatches?: number;
     /** Textured batches (one per part x texture) and distinct textures; 0 for packs without textures. */
@@ -87,6 +95,8 @@ export interface LdrObject {
     texturesReady: Promise<void>;
     /** Toggle conditional lines (only visible while edges are on). */
     setConditionalLines(on: boolean): void;
+    /** Without steps, an object built with culling on drops the hidden instances' buffers; turning that culling off rebuilds the object
+     *  (like a fresh `createLdrObject`, ~build time) so they can be drawn. Turning it back on afterwards is instant. */
     setCulling(studs: boolean, undersides: boolean): void;
     setSide(side: "front" | "double"): void;
     /** Turn distance LOD on/off (off = full detail and edges everywhere). Only has an effect if the object was built with `lod` (default). */
@@ -95,8 +105,18 @@ export interface LdrObject {
     getBox(target?: THREE.Box3): THREE.Box3;
     dispose(): void;
 }
+/**
+ * Build a three.js object for a flattened model using a parts pack.
+ * Instances whose part is not in the pack are skipped and listed in `stats.missing`.
+ */
 /**
  * Build a three.js object for a flattened model using a parts pack.
  * Instances whose part is not in the pack are skipped and listed in `stats.missing`.
  */
 export declare function createLdrObject(instances: PartInstance[], pack: Pack, options?: LdrObjectOptions): LdrObject;
+/**
+ * Progressive/async variant of `createLdrObject`: yields about every `sliceMs` (default 8) so the main thread stays responsive.
+ * Meshes land on `object` as batches finish; pass `onSlice` to render for a fast time-to-first-pixel.
+ * Final visuals and stats match the sync path (same generator).
+ */
+export declare function createLdrObjectAsync(instances: PartInstance[], pack: Pack, options?: LdrObjectOptions): Promise<LdrObject>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldr",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "High-performance LEGO (LDraw) rendering for three.js: instanced parts packs, hidden stud/tube culling, low-detail studs, indexed edges, build steps.",
   "license": "MIT",
   "author": "Evan Bacon",