ImageOverlayPlugin: Use the original texture directly if the bounds match geometry exactly. (#1535)

* Allow for "init" to be called twice

* Ensure consistent return value from "_init"

* Make "init" async

* Add memory efficient path to RegionImageSource, ImageOverlayPlugin

* Cleanup

Author: gkjohnson

src/three/plugins/images/ImageOverlayPlugin.js

@@ -904,27 +904,21 @@ export class ImageOverlayPlugin {
 
 		const { tiles } = this;
 
-		if ( ! overlay.isInitialized ) {
+		overlay.init().then( () => {
 
-			overlay.init();
+			// Set resolution on the overlay
+			overlay.setResolution( this.resolution );
 
-			overlay.whenReady().then( () => {
+			const overlayFetch = overlay.fetch.bind( overlay );
+			overlay.fetch = ( ...args ) => tiles
+				.downloadQueue
+				.add( { priority: - performance.now() }, () => {
 
-				// Set resolution on the overlay
-				overlay.setResolution( this.resolution );
+					return overlayFetch( ...args );
 
-				const overlayFetch = overlay.fetch.bind( overlay );
-				overlay.fetch = ( ...args ) => tiles
-					.downloadQueue
-					.add( { priority: - performance.now() }, () => {
-
-						return overlayFetch( ...args );
-
-					} );
-
-			} );
+				} );
 
-		}
+		} );
 
 		const promises = [];
 		const initTile = async ( scene, tile ) => {
@@ -1311,8 +1305,14 @@ class ImageOverlay {
 
 	init() {
 
-		this.isInitialized = true;
-		this._whenReady = this._init().then( () => this.isReady = true );
+		if ( ! this.isInitialized ) {
+
+			this.isInitialized = true;
+			this._whenReady = this._init().then( () => this.isReady = true );
+
+		}
+
+		return this._whenReady;
 
 	}
 
@@ -1323,7 +1323,11 @@ class ImageOverlay {
 	}
 
 	// overrideable
-	_init() {}
+	_init() {
+
+		return Promise.resolve();
+
+	}
 
 	fetch( url, options = {} ) {
 

src/three/plugins/images/sources/RegionImageSource.js

@@ -3,6 +3,10 @@ import { forEachTileInBounds } from '../overlays/utils.js';
 import { DataCache } from '../utils/DataCache.js';
 import { SRGBColorSpace, CanvasTexture } from 'three';
 
+// Epsilon for comparing normalized tile bounds to determine if a region exactly matches a single
+// image tile.
+const BOUNDS_EPSILON = 1e-10;
+
 export class RegionImageSource extends DataCache {
 
 	hasContent( ...tokens ) {
@@ -21,6 +25,8 @@ export class TiledRegionImageSource extends RegionImageSource {
 		this.tiledImageSource = tiledImageSource;
 		this.tileComposer = new TiledTextureComposer();
 		this.resolution = 256;
+		this.IS_DIRECT_TILE = Symbol( 'IS_DIRECT_TILE' );
+		this.LOCK_TOKENS = Symbol( 'LOCK_TOKENS' );
 
 	}
 
@@ -40,22 +46,63 @@ export class TiledRegionImageSource extends RegionImageSource {
 
 	async fetchItem( [ minX, minY, maxX, maxY, level ], signal ) {
 
+		const { tiledImageSource, tileComposer, IS_DIRECT_TILE, LOCK_TOKENS } = this;
 		const range = [ minX, minY, maxX, maxY ];
-		const imageSource = this.tiledImageSource;
-		const tileComposer = this.tileComposer;
-		const tiling = imageSource.tiling;
+		const tiling = tiledImageSource.tiling;
+		const tokens = [ ...range, level ];
+
+		// lock tiles for the requested level
+		await this._markImages( range, level, false );
+
+		//
+
+		// Fast path: if the range maps to exactly one tile with matching bounds, use its
+		// texture directly without compositing into an intermediate canvas to save memory.
+		let singleTileBounds = null;
+		let tileCount = 0;
+		forEachTileInBounds( range, level, tiling, ( tx, ty, tl ) => {
+
+			tileCount ++;
+			singleTileBounds = [ tx, ty, tl ];
+
+		} );
+
+		if ( tileCount === 1 ) {
+
+			const [ tx, ty, tl ] = singleTileBounds;
+			const tileBounds = tiling.getTileBounds( tx, ty, tl, true, false );
+			if (
+				Math.abs( tileBounds[ 0 ] - minX ) <= BOUNDS_EPSILON &&
+				Math.abs( tileBounds[ 1 ] - minY ) <= BOUNDS_EPSILON &&
+				Math.abs( tileBounds[ 2 ] - maxX ) <= BOUNDS_EPSILON &&
+				Math.abs( tileBounds[ 3 ] - maxY ) <= BOUNDS_EPSILON
+			) {
+
+				// Clone rather than returning the texture directly so each region cache entry owns
+				// a distinct object. Returning the shared texture would cause symbol properties
+				// to be overwritten or deleted by concurrent cache entries during race conditions,
+				// (create, delete, create) leading to errors on disposal.
+				// Cloning shares the underlying Source so no extra GPU memory is used.
+				const clone = tiledImageSource.get( tx, ty, tl ).clone();
+				clone[ IS_DIRECT_TILE ] = true;
+				clone[ LOCK_TOKENS ] = tokens;
+				return clone;
+
+			}
+
+		}
+
+		//
 
+		// Compose path: tiles must be composed into a single texture
 		const canvas = document.createElement( 'canvas' );
 		canvas.width = this.resolution;
 		canvas.height = this.resolution;
 
 		const target = new CanvasTexture( canvas );
 		target.colorSpace = SRGBColorSpace;
 		target.generateMipmaps = false;
-		target.tokens = [ ...range, level ];
-
-		// Start locking tiles for the requested level
-		await this._markImages( range, level, false );
+		target[ LOCK_TOKENS ] = tokens;
 
 		// TODO: we could draw the parent tile data here if it's available just to make sure we
 		// have something to display but the texture is not usable until it returns. Though it
@@ -69,7 +116,7 @@ export class TiledRegionImageSource extends RegionImageSource {
 
 			// draw using normalized bounds since the mercator bounds are non-linear
 			const span = tiling.getTileBounds( tx, ty, tl, true, false );
-			const tex = imageSource.get( tx, ty, tl );
+			const tex = tiledImageSource.get( tx, ty, tl );
 			tileComposer.draw( tex, span );
 
 		} );
@@ -80,10 +127,14 @@ export class TiledRegionImageSource extends RegionImageSource {
 
 	disposeItem( target ) {
 
+		const { IS_DIRECT_TILE, LOCK_TOKENS } = this;
+		const [ minX, minY, maxX, maxY, level ] = target[ LOCK_TOKENS ];
+
 		target.dispose();
+		delete target[ IS_DIRECT_TILE ];
+		delete target[ LOCK_TOKENS ];
 
-		// Unlock the component tiles using the tokens stored on the target
-		const [ minX, minY, maxX, maxY, level ] = target.tokens;
+		// Unlock the component tiles using the stored tokens
 		this._markImages( [ minX, minY, maxX, maxY ], level, true );
 
 	}