@tissuumaps/render 0.1.0-beta.1 → 0.1.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @tissuumaps/render
 
+## 0.1.0-beta.3
+
+### Minor Changes
+
+- [#306](https://github.com/TissUUmaps/TissUUmaps/pull/306) [`2603f6f`](https://github.com/TissUUmaps/TissUUmaps/commit/2603f6f2c48748c07d2ead3413fc95f4c1745675) Thanks [@jwindhager](https://github.com/jwindhager)! - Points, shapes, labels and images are each drawn as soon as their own data is ready, so a slow or failing object no longer holds back the other objects of its kind ([#269](https://github.com/TissUUmaps/TissUUmaps/issues/269)). The WebGL renderers' `synchronize` takes an `onChange` callback, which is called whenever a rendered object has been added, updated or dropped, and no longer resolves to whether anything changed.
+
+- [#290](https://github.com/TissUUmaps/TissUUmaps/pull/290) [`cd0c14e`](https://github.com/TissUUmaps/TissUUmaps/commit/cd0c14e27ccb02645ab37d1da4c829ff3e56e0c2) Thanks [@cavenel](https://github.com/cavenel)! - `OpenSeadragonContext` applies `osOptions.viewerOptions.showNavigator` live, without rebuilding the viewer.
+
+### Patch Changes
+
+- [#307](https://github.com/TissUUmaps/TissUUmaps/pull/307) [`16e181e`](https://github.com/TissUUmaps/TissUUmaps/commit/16e181efd919f11a54b259c7e96231b724e628dd) Thanks [@jwindhager](https://github.com/jwindhager)! - Documentation links point to the new TissUUmaps website at https://tissuumaps.github.io/: the app's Docs link, and the packages' READMEs and homepages.
+- Updated dependencies [[`75433b7`](https://github.com/TissUUmaps/TissUUmaps/commit/75433b7dfe6f553f6c7020fe7088a6b38e099790), [`9fc85a9`](https://github.com/TissUUmaps/TissUUmaps/commit/9fc85a9148be339aa0e419620253f03aace7041a), [`16e181e`](https://github.com/TissUUmaps/TissUUmaps/commit/16e181efd919f11a54b259c7e96231b724e628dd)]:
+  - @tissuumaps/core@0.1.0-beta.3
+
+## 0.1.0-beta.2
+
+### Patch Changes
+
+- [#295](https://github.com/TissUUmaps/TissUUmaps/pull/295) [`67b9236`](https://github.com/TissUUmaps/TissUUmaps/commit/67b92362506385171c41b0b9356a23c463303d29) Thanks [@jwindhager](https://github.com/jwindhager)! - Plain images can be opened from a URL or path ([#274](https://github.com/TissUUmaps/TissUUmaps/issues/274)): an image data source's `source` with a PNG, JPEG or WebP file extension, or a `data:image/` URL, is opened as a plain image, also from the workspace; any other `source` is handed to OpenSeadragon as a tile source descriptor, which cannot be opened from the workspace. The data source `type` becomes `image` (was `openseadragon`) and its `tileSourceConfig` field becomes `tileSource`, which takes the URL of a descriptor or an inline tile source configuration and takes precedence over `source`. Inline tile source configurations taken from a project no longer fail to open because OpenSeadragon writes into them. Projects using `openseadragon` data sources have to be updated.
+- Updated dependencies [[`15a214a`](https://github.com/TissUUmaps/TissUUmaps/commit/15a214a7950a1e9aa605ca5445cc4273b826ca2d)]:
+  - @tissuumaps/core@0.1.0-beta.2
+
 ## 0.1.0-beta.1
 
 ### Minor Changes

package/README.md

@@ -20,6 +20,6 @@ Content Security Policy, allow it with `img-src data:`.
 
 ## Documentation
 
-- [API reference](https://tissuumaps.github.io/TissUUmaps/docs/docs/api/@tissuumaps/render/)
-- [Rendering](https://tissuumaps.github.io/TissUUmaps/docs/docs/development/rendering/)
-- [Code architecture](https://tissuumaps.github.io/TissUUmaps/docs/docs/development/code-architecture/)
+- [API reference](https://tissuumaps.github.io/docs/api/@tissuumaps/render/)
+- [Rendering](https://tissuumaps.github.io/docs/development/rendering/)
+- [Code architecture](https://tissuumaps.github.io/docs/development/code-architecture/)

package/dist/index.d.ts

@@ -198,7 +198,8 @@ export declare class OpenSeadragonContext {
      * Applies viewer options to the OpenSeadragon viewer and all existing tiled images
      *
      * For each option key, performs a shallow merge (one level deep) of nested objects
-     * on both the viewer instance and every tiled image in the world.
+     * on both the viewer instance and every tiled image in the world. `showNavigator`
+     * shows or hides the navigator, as OpenSeadragon reads it only on construction.
      *
      * @param viewerOptions - Options to apply
      */
@@ -844,18 +845,20 @@ declare abstract class OpenSeadragonRendererBase<TObject extends Image_2 | Label
     /**
      * Synchronizes the viewer's tiled images with the current model
      *
-     * Loads all objects assigned to the layers of the model set by
-     * {@link setModel}, removes the tiled images that are no longer needed, and
-     * creates or updates the remaining ones. Resolves once the tiled images have
-     * actually been added to the world, i.e. once the viewer reflects the model
-     * state that was read. The model may be set again while the synchronization
-     * runs; it reads the model once, so it sees one consistent state, while the
-     * properties it applies to the tiled images come from the current model (see
+     * Starts loading the objects on the layers of the model (see
+     * {@link setModel}), and right away removes the tiled images that are no
+     * longer needed (see {@link _cleanRenderedObjects}). Each object is then
+     * synchronized as soon as it has loaded, without waiting for the others: its
+     * tiled images are updated, or created at its position in the world (see
+     * {@link _synchronizeRenderedObject}).
+     *
+     * Resolves once the tiled images of all objects are in the world. The model
+     * is read once, so the synchronization sees one consistent state, but the
+     * properties applied to the tiled images come from the current model (see
      * {@link _updateRenderedObject}).
      *
-     * Objects whose tiled images cannot be created, e.g. because their data
-     * provides no tile sources, are logged and skipped, just like objects whose
-     * data failed to load (see {@link _loadObjects}). A synchronization that
+     * Objects whose data fails to load, or whose tiled images cannot be created
+     * (e.g. without tile sources), are logged and dropped. A synchronization that
      * fails or is aborted leaves the model unsynchronized (see
      * {@link needsSynchronization}).
      *
@@ -949,13 +952,12 @@ declare abstract class OpenSeadragonRendererBase<TObject extends Image_2 | Label
     /**
      * Retains what was resolved for the given objects, and discards the rest
      *
-     * Called by {@link synchronize} once all objects have loaded and the rendered
-     * objects of all others have been deleted, with the objects that are about
-     * to be displayed: those assigned to a rendered layer whose data loaded
-     * successfully. Does nothing here; subclasses that keep
-     * state per object (see {@link resolveObject} and
+     * Called by {@link synchronize} with the objects about to be displayed, i.e.
+     * those assigned to a rendered layer, once the rendered objects of all others
+     * have been deleted and before any object has loaded. Does nothing here;
+     * subclasses that keep state per object (see {@link resolveObject} and
      * {@link resolveTiledImageDataTransfer}) override this to drop the state of
-     * every object that is not among the given ones.
+     * all other objects.
      *
      * @param _objects - The objects (images or labels) about to be displayed
      */
@@ -963,15 +965,15 @@ declare abstract class OpenSeadragonRendererBase<TObject extends Image_2 | Label
     /**
      * Resolves what a renderer derives from an object, once its data has loaded
      *
-     * Called by {@link _loadObjects} for every object on one of the given layers,
-     * concurrently, right after
-     * its data has loaded and before its tiled images are created or updated. An
-     * object that cannot be resolved is logged, but kept: its tiled images are
-     * still created or updated, with whatever the synchronous hooks return for
-     * it. Does nothing here; subclasses override this to resolve, from the
-     * object, its data and the inputs of the synchronization, whatever their
-     * synchronous hooks return later (see {@link resolveTiledImageDataTransfer}),
-     * and to keep it for as long as its outcome would not change.
+     * Called by {@link _loadObjects} for each object, concurrently, once its data
+     * has loaded and before its tiled images are created or updated. An object
+     * that cannot be resolved is logged, but kept: its tiled images are still
+     * created or updated, with whatever the synchronous hooks return for it.
+     *
+     * Does nothing here. Subclasses override this to resolve what their
+     * synchronous hooks return later (see {@link resolveTiledImageDataTransfer})
+     * from the object, its data and the inputs of the synchronization, and to
+     * keep it for as long as its outcome would not change.
      *
      * @param _object - The object (image or labels) to resolve
      * @param _data - The loaded data of the object
@@ -1050,88 +1052,113 @@ declare abstract class OpenSeadragonRendererBase<TObject extends Image_2 | Label
      */
     protected resolveTiledImageDataTransfer(_ref: ObjectRef<TObject, TObjectData>, _index: number | null): DataTransfer_2 | undefined;
     /**
-     * Concurrently loads and resolves all objects assigned to the layers of the current model
+     * Starts loading and resolving all objects assigned to the layers of the current model
      *
-     * Each object's data is loaded with the context's `loadObject`, and the object
-     * is then resolved (see {@link resolveObject}). The returned references are
-     * ordered by layer and then by object, which determines the order of the
-     * corresponding tiled images in the world. Objects whose data failed to load
-     * are logged and skipped; objects that could not be resolved are logged, but
-     * kept. The model is read once, before the first `await`, so one
-     * synchronization sees one consistent model state, however often the model
-     * is set while it runs.
+     * Loads each object's data with the context's `loadObject`, then resolves the
+     * object (see {@link resolveObject}). Returns right away, with one loading
+     * per object, in world order: by layer, then by object. A loading rejects if
+     * the object's data fails to load, which is logged. An object that cannot be
+     * resolved is logged, but kept.
+     *
+     * The model is read once, right away, so one synchronization sees one
+     * consistent model state.
      *
      * @param context - The inputs of the current synchronization
      * @param options - Optional abort signal
-     * @returns A promise that resolves to one object reference per successfully loaded object
+     * @returns One loading per object, whose promise resolves to the object's
+     * reference
      * @throws Error if no model has been set (see {@link setModel})
      */
     private _loadObjects;
     /**
-     * Retains the rendered objects that can be reused for the new object references, and deletes the rest
+     * Keeps the rendered objects that can be reused for a synchronization, and deletes the rest
      *
      * A rendered object is matched by the layer and object it references.
-     * Unmatched rendered objects are deleted first, so that removing an object
-     * does not shift the world indices of the objects behind it. A matched
-     * rendered object is reusable if the data source it was loaded for is that of
-     * the reference, and if its backdrop, if any, and all of its tiled images
-     * already sit at the consecutive world indices expected for its position
-     * among the references, counted from the anchor. A partially misplaced object
-     * is not reusable. The other matched rendered objects are deleted as well,
-     * and are expected to be recreated by the caller via
-     * {@link _createRenderedObject}, which is also how the world is reordered.
-     *
-     * The expected indices account for every matched rendered object, reusable or
-     * not, by the world footprint it currently has: a matched object that is
-     * recreated, e.g. because its data source changed, is deleted and inserted at
-     * the same position, with possibly different tiled images, so the objects
-     * behind it keep their indices relative to it and stay reusable. Only the
-     * backdrop and tiled images assigned to it count, i.e. none for an object
-     * whose tiled images could not be added, which is thereby retried without
-     * recreating the objects behind it. The tiled images that an earlier
-     * synchronization is still adding are waited for first, so that each
-     * rendered object is either fully in the world or not at all. This does not
-     * delay the additions of this synchronization, which are queued behind them
-     * anyway (see {@link OpenSeadragonContext.addTiledImage}).
-     *
-     * @param newRefs - The new object references, in the intended world order
+     * Unmatched ones are deleted first, so that their removal does not shift the
+     * world indices of the objects behind them. Only the layers and objects of
+     * the loadings are needed, not their data, so this runs before any of them
+     * has loaded.
+     *
+     * A matched rendered object is reusable if it was loaded for its object's
+     * data source, and if its backdrop, if any, and all of its tiled images sit
+     * at the consecutive world indices expected for its position among the
+     * loadings, counted from the anchor. All other matched rendered objects are
+     * deleted as well, for the caller to recreate them (see
+     * {@link _createRenderedObject}), which is also how the world is reordered.
+     *
+     * The expected indices count every matched rendered object, reusable or not,
+     * by its current footprint. A matched object that is recreated, e.g. because
+     * its data source changed, is reinserted at the same position, so the objects
+     * behind it stay reusable. An object whose tiled images could not be added
+     * has been forgotten (see {@link _createRenderedObject}), so it is created
+     * anew, without recreating the objects behind it.
+     *
+     * The tiled images that an earlier synchronization is still adding are waited
+     * for first, so that each rendered object is either fully in the world or not
+     * at all. This does not delay the additions of this synchronization, which
+     * are queued behind them anyway (see
+     * {@link OpenSeadragonContext.addTiledImage}).
+     *
+     * @param loadings - The loadings of the synchronization (see
+     * {@link _loadObjects}), in world order
      * @param options - Optional abort signal
-     * @returns A map of new object references to their reusable rendered objects
+     * @returns A map of loadings to their reusable rendered objects
      * @throws Error if the renderer has no anchor, i.e. it is not initialized or
      * already destroyed
      */
     private _cleanRenderedObjects;
+    /**
+     * Synchronizes the rendered object of one object, once it has loaded
+     *
+     * A reusable rendered object (see {@link _cleanRenderedObjects}) is updated
+     * with the new reference, or deleted if the object failed to load. Otherwise,
+     * a rendered object is created behind those of the preceding loadings,
+     * whether these are in the world already or still being added. Preceding
+     * objects that arrive later are inserted in front of it, as world mutations
+     * run in request order (see {@link OpenSeadragonContext.addTiledImage}).
+     *
+     * @param precedingLoadings - The loadings that precede the object's in world
+     * order (see {@link _loadObjects})
+     * @param newRefPromise - The promise of the object's reference, from its
+     * loading
+     * @param renderedObject - The object's reusable rendered object, if any
+     * @param options - Optional abort signal
+     * @returns A promise that resolves once the object's tiled images have been
+     * updated, or their creation has been requested
+     */
+    private _synchronizeRenderedObject;
     /**
      * Creates a new rendered object for the given object reference and adds one TiledImage per channel, preceded by a backdrop where required, to the world
      *
-     * The TiledImages are inserted at consecutive indices, starting `offset` places
-     * after the anchor, which establishes the world layout that
-     * {@link _cleanRenderedObjects} expects. `offset` therefore counts TiledImages,
-     * not objects, and callers have to advance it by
-     * {@link RenderedObject.tileSourceCount} plus the object's backdrop, if it has
-     * one. The indices are resolved once each addition is executed, as the anchor
-     * may have been replaced, and world indices may have shifted, while it was
-     * enqueued.
-     *
-     * The tile sources are opened here, rather than by the additions themselves,
-     * so that the backdrop can be sized like the object's content, which is only
-     * known once one of them has been opened. The additions are all requested
-     * before this function returns, and in world order, so that the TiledImages of
-     * the object that the caller creates next end up behind them.
-     *
-     * Returns before the TiledImages exist: they are added asynchronously and only
-     * then assigned to the rendered object, transformed, and included in the anchor
-     * bounds, which is when {@link RenderedObject.tiledImagesPromise} resolves. The
-     * backdrop and TiledImages are removed again immediately after they were added
-     * if the rendered object is deleted or the operation is aborted in the
-     * meantime, or if any of them could not be added at all - a partially added
-     * object would shift the world indices of every object after it. For the same
-     * reason, a tile source that fails to open is replaced by a transparent
-     * placeholder rather than skipped: the indices of the objects created after
-     * this one are resolved against the full footprint of this one, so it has to
-     * take up all of its indices until it is removed again. If the context
-     * is destroyed, nothing is done at all, as the viewer tears down its world
-     * itself.
+     * The TiledImages are inserted at consecutive indices, starting `offset`
+     * places after the anchor, which is the world layout that
+     * {@link _cleanRenderedObjects} expects. `offset` thus counts TiledImages,
+     * not objects: the backdrops and TiledImages of the preceding rendered
+     * objects, including those still being added. The indices are resolved when
+     * each addition is executed, as the anchor may have been replaced, and world
+     * indices may have shifted, in the meantime.
+     *
+     * The tile sources are opened here, rather than by the additions, so that the
+     * backdrop can be sized like the object's content, which is only known once
+     * one of them has opened. All additions are requested before this function
+     * returns, in world order, so that the TiledImages of the object created next
+     * end up behind them.
+     *
+     * Returns before the TiledImages exist: they are added asynchronously, and
+     * only then assigned to the rendered object, transformed and included in the
+     * anchor bounds, which is when {@link RenderedObject.tiledImagesPromise}
+     * resolves.
+     *
+     * If the rendered object is deleted or the operation is aborted in the
+     * meantime, or if any TiledImage could not be added, the added backdrop and
+     * TiledImages are removed again right away: a partially added object would
+     * shift the world indices of every object behind it. For the same reason, a
+     * tile source that fails to open is replaced by a transparent placeholder
+     * rather than skipped, as the objects created after this one are placed
+     * against its full footprint. The rendered object is dropped from
+     * {@link _renderedObjects} as its removals are queued, so that objects
+     * created from then on are placed without it. If the context is destroyed,
+     * nothing is done at all, as the viewer tears down its world itself.
      *
      * @param offset - The number of TiledImages between the anchor and the object's first new TiledImage
      * @param newRef - The object reference for which to create a rendered object
@@ -1307,9 +1334,8 @@ declare type PreparedShapes = {
  * Extended by the renderers with the GPU resources they own, and with a
  * snapshot of the object properties those were built from, which their change
  * detection compares against. Rendered objects are mutated in place across
- * synchronizations:
- * {@link WebGLRendererBase.matchOrDestroyRenderedObjects} replaces the
- * reference of a matched object, and the renderers replace the bounds, the
+ * synchronizations: {@link WebGLRendererBase.synchronize} replaces the
+ * reference of a reused object, and the renderers replace the bounds, the
  * snapshot and the GPU resources of an object as they are rebuilt.
  */
 declare type RenderedObjectBase<TObject extends Points | Shapes, TObjectData extends PointsData | ShapesData> = {
@@ -1958,7 +1984,6 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
     viewport: Rect;
     private _model?;
     private _lastSyncState?;
-    private _hasUnreportedChanges;
     private readonly _renderedObjects;
     private readonly _layerItemsInfosCache;
     /**
@@ -2021,34 +2046,38 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
     /**
      * Synchronizes the rendered objects with the current model and render options
      *
-     * Loads the objects of the model (see {@link loadObjects}), drops the
-     * rendered objects that no longer match one (see
-     * {@link matchOrDestroyRenderedObjects}), and then creates or updates the
-     * rest in two passes. The first prepares every object (see
-     * {@link prepareRenderedObject}), issuing all requests before the first
-     * `await`: requests are shared with, and cancelled once abandoned by, a
-     * superseded synchronization, unless they are reclaimed within the same
-     * task. The second awaits the preparations in order and uploads each of them
-     * in one synchronous block (see {@link createRenderedObject} and
-     * {@link updateRenderedObject}), so a draw never sees a half-updated object.
-     *
-     * An object whose preparation fails, or finds nothing to render, is logged
-     * and dropped. A synchronization that fails or is aborted leaves the model
-     * unsynchronized (see {@link _discardSyncState}), and the changes it made
-     * before it stopped are reported by the next one that completes.
+     * Starts loading the objects of the model (see {@link loadObjects}), and
+     * right away drops the rendered objects that none of them addresses. Each
+     * object is then synchronized on its own, as soon as its data has loaded: the
+     * object is prepared (see {@link prepareRenderedObject}), and the preparation
+     * is uploaded in one synchronous block, either into the reused rendered
+     * object or into one that replaces it (see {@link createRenderedObject} and
+     * {@link updateRenderedObject}). A draw thus never sees a half-updated
+     * object, and a slow or failing object never holds back the others.
+     *
+     * An object issues its requests right after its data has loaded, without
+     * awaiting in between. Requests are shared with a superseded synchronization,
+     * and cancelled once it abandons them, unless they are reclaimed within the
+     * same task. Data that has already loaded allows that.
+     *
+     * An object whose data or preparation fails, or that has nothing to render,
+     * is logged and dropped. A synchronization that fails or is aborted leaves
+     * the model unsynchronized (see {@link _discardSyncState}).
      *
      * @param syncContext - The inputs to synchronize with: the tables and
-     * group-to-value maps that the objects resolve their properties from, and
-     * the loaders for object and table data. It carries inputs only; what an
-     * object was resolved from is captured per object (see {@link ObjectRef})
-     * @param options - Optional abort signal
-     * @returns A promise that resolves to whether any rendered object changed
-     * since the last completed synchronization
+     * group-to-value maps that the objects resolve their properties from, and the
+     * loaders for object and table data. It carries inputs only; what an object
+     * was resolved from is captured per object (see {@link ObjectRef})
+     * @param options - Optional abort signal, and a callback that is called
+     * synchronously whenever a rendered object is added, updated or dropped, so
+     * that the caller can draw each object as soon as it is ready
+     * @returns A promise that resolves once all objects have been synchronized
      * @throws Error if no model has been set (see {@link setModel})
      */
     synchronize(syncContext: TSyncContext, options?: {
         signal?: AbortSignal;
-    }): Promise<boolean>;
+        onChange?: () => void;
+    }): Promise<void>;
     /**
      * Returns the state of the current model and render options that a
      * synchronization depends on
@@ -2103,48 +2132,36 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
      */
     protected getRenderOptionsSyncState(): object | undefined;
     /**
-     * Concurrently loads the data of all objects to be rendered on the layers of the current model
+     * Starts loading the data of all objects to be rendered on the layers of the current model
      *
-     * An object assigned to a layer by layer ID is loaded for that layer only, an
+     * An object assigned to a layer by layer ID is loaded for that layer only. An
      * object assigned per item by a table column is loaded for every layer, with
      * the items on each layer resolved from the table (see
      * {@link _getLayerItemsInfos}). The data of an object, and of a table, is
-     * loaded once, no matter how many references it is shared by.
+     * loaded once, however many references share it.
      *
-     * The returned references are ordered by layer and then by object. Objects
-     * whose data or table failed to load are logged and skipped, and so are
-     * objects whose items are assigned per item without a table to resolve the
-     * assignment from. Objects without items on a layer are skipped silently,
-     * which also covers empty objects and objects whose table is empty - those
-     * are legitimate states, not failures.
+     * Returns right away, with one loading per object and layer, ordered by layer
+     * and then by object. Each loading settles on its own. It rejects if the
+     * object's data or table fails to load, which is logged. It resolves to
+     * `null` if the object has no items on the layer, which is not logged: empty
+     * objects and empty tables are legitimate states, not failures. An object
+     * whose items are assigned per item, but that has no table to resolve the
+     * assignment from, is logged and gets no loading.
      *
      * @param syncContext - The inputs of the current synchronization: the tables
-     * that the objects resolve their item layers from, and the loaders for
-     * object and table data
+     * that the objects resolve their item layers from, and the loaders for object
+     * and table data
      * @param options - Optional abort signal
-     * @returns A promise that resolves to one reference per loaded object and layer
+     * @returns One loading per object and layer, whose promise resolves to the
+     * object's reference, or to `null` if the object has no items on the layer
      * @throws Error if no model has been set (see {@link setModel})
      */
     protected loadObjects(syncContext: TSyncContext, options?: {
         signal?: AbortSignal;
-    }): Promise<ObjectRef_2<TObject, TObjectData>[]>;
-    /**
-     * Matches the rendered objects to a new set of references, and destroys the
-     * ones left over
-     *
-     * A rendered object is matched by the layer and object it is kept under, and
-     * kept if its contributed items and data source are those of the reference,
-     * which it then adopts and is returned for reuse with. Every other rendered
-     * object - one that no reference addresses, or one whose items or data source
-     * changed - is destroyed and dropped.
-     *
-     * @param newRefs - The object references to match against
-     * @returns One match per reference, in the order of the references, each with
-     * the rendered object to reuse for it, or `undefined` if it has none yet
-     */
-    protected matchOrDestroyRenderedObjects(newRefs: ObjectRef_2<TObject, TObjectData>[]): {
-        newRef: ObjectRef_2<TObject, TObjectData>;
-        renderedObject: TRenderedObject | undefined;
+    }): {
+        layerId: string;
+        object: TObject;
+        newRefPromise: Promise<ObjectRef_2<TObject, TObjectData> | null>;
     }[];
     /**
      * Adds a newly created rendered object under its layer and object
@@ -2165,14 +2182,14 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
     /**
      * Prepares everything that has to be uploaded for an object
      *
-     * Runs in the first pass of {@link synchronize}, which calls it synchronously
-     * for every object of a synchronization, one after the other: every request
-     * has to be issued before the first `await`. Decides, from the object's
-     * current rendered state, which of its GPU resources have to be rebuilt, and
-     * resolves only those.
+     * Called by {@link synchronize} as soon as the object's data has loaded.
+     * Every request has to be issued before the first `await` (see
+     * {@link synchronize}). Decides, from the object's current rendered state,
+     * which of its GPU resources have to be rebuilt, and resolves only those.
      *
      * @param newRef - The object to prepare
-     * @param renderedObject - The object's current rendered state, if it is reused
+     * @param renderedObject - The object's current rendered state, if it is
+     * reused
      * @param syncContext - The inputs of the current synchronization
      * @param options - Optional abort signal
      * @returns What {@link createRenderedObject} or {@link updateRenderedObject}
@@ -2185,7 +2202,8 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
     /**
      * Creates the rendered object, with its GPU resources, of a newly prepared object
      *
-     * Runs in the second pass of {@link synchronize}, synchronously.
+     * Called synchronously by {@link synchronize} once the object has been
+     * prepared.
      *
      * @param newRef - The object
      * @param prepared - Its preparation, made without a rendered object to reuse
@@ -2195,7 +2213,8 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
     /**
      * Updates the GPU resources of a rendered object from its preparation
      *
-     * Runs in the second pass of {@link synchronize}, synchronously.
+     * Called synchronously by {@link synchronize} once the object has been
+     * prepared.
      *
      * @param renderedObject - The rendered object to update in place
      * @param prepared - Its preparation, made with it as the rendered object to reuse
@@ -2293,18 +2312,39 @@ declare abstract class WebGLRendererBase<TObject extends Points | Shapes, TObjec
      */
     private _getLayerItemsInfos;
     /**
-     * Awaits the preparation of an object, dropping the object if it fails or
-     * finds nothing to render
+     * Drops the rendered objects that none of the given loadings addresses
      *
-     * @param newRef - The prepared object
-     * @param renderedObject - The object's current rendered state, if any, which
-     * is removed if the object is dropped
-     * @param preparedPromise - The preparation, see {@link prepareRenderedObject}
-     * @param options - Optional abort signal
-     * @returns The preparation, or `undefined` if the object was dropped (which
-     * is logged)
+     * Their layer or object has left the model, or the object has moved to
+     * another layer, so they are no longer drawn (see {@link getRenderPasses}).
+     * They are dropped right away, rather than once the remaining objects have
+     * loaded. Whether the others can be reused is decided per object, once its
+     * data has loaded (see {@link _synchronizeRenderedObject}).
+     *
+     * @param loadings - The loadings of the current synchronization (see
+     * {@link loadObjects})
+     * @returns Whether any rendered object was dropped
+     */
+    private _cleanRenderedObjects;
+    /**
+     * Synchronizes the rendered object of one object and layer, once its data has loaded
+     *
+     * The rendered object kept under the layer and object is reused if its items
+     * and data source match the new reference, which it then adopts. The object
+     * is then prepared and uploaded (see {@link synchronize}). A rendered object
+     * that is not reused stays drawn until its replacement is uploaded, and is
+     * then dropped in the same synchronous block. If the object's data failed to
+     * load, or it has no items on the layer, it is only dropped. So is it if its
+     * preparation fails or finds nothing to render, which is logged.
+     *
+     * @param layerId - The ID of the layer
+     * @param objectId - The ID of the object
+     * @param newRefPromise - The object's loading (see {@link loadObjects})
+     * @param syncContext - The inputs of the current synchronization
+     * @param options - Optional abort signal, and the callback to call whenever
+     * the rendered object is added, updated or dropped
+     * @returns A promise that resolves once the object has been synchronized
      */
-    private _settleRenderedObjectPreparation;
+    private _synchronizeRenderedObject;
     /**
      * Creates the loader for the tables that an object resolves its properties
      * from