3D Tiles: byte-budget eager texture binds across frames

The adaptive install cap counted mesh installs, but every texture from
the installed meshes eager-bound in a single frame - and one 2048
mipmapped texture is ~21 MB of glTexImage2D. City-scale loading
produced 20-150 ms GL-thread stalls in the eager-bind drawable while
the pipeline stayed "within budget".

Freshly-installed texture keys now queue on the layer and each frame
binds a byte-capped batch; the rest carries over, with a redraw
requested while the queue drains. The budget derives from MEASURED
upload throughput: each batch times its own GL-thread duration, an
EWMA tracks bytes-per-ms, and the budget targets a 3 ms bind slice
(clamped 2-32 MB). The whole-frame EWMA that drives the install cap
cannot control this tail - a rare oversized batch spikes one frame yet
barely moves a frame-work average, so that controller kept raising the
budget it should have cut.

An oversized texture still binds alone. Keys instead of Texture refs
so a cache eviction while pending is a skip, not a resurrected orphan
GL texture. Bitmap recycling - the reason eager binds exist - is
delayed by at most a few frames and stays bounded by the batch drain.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RXPy4LJSC8yVMp2RUfUE5q

Author: EMaksymenko

worldwind/src/commonMain/kotlin/earth/worldwind/layer/ogc3d/Ogc3dTilesLayer.kt

@@ -73,6 +73,7 @@ import kotlin.concurrent.Volatile
 import kotlin.time.Clock
 import kotlin.time.Duration.Companion.milliseconds
 import kotlin.time.Instant
+import kotlin.time.TimeSource
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -505,11 +506,26 @@ open class Ogc3dTilesLayer(
                 minOf(adaptiveInstallCap + 1, MAX_INSTALL_CAP)
             else -> adaptiveInstallCap
         }
+        // Eager-bind budget from MEASURED upload throughput: each batch times its own
+        // GL-thread duration, and the budget targets a fixed bind slice. A rare oversized
+        // batch spikes one frame yet barely moves a whole-frame-work average, so the
+        // install cap's EWMA controller cannot push back on the bind tail.
+        val bindBytes = lastEagerBindBytes
+        if (bindBytes > 0) {
+            lastEagerBindBytes = 0
+            val bindMs = lastEagerBindNanos / 1_000_000.0
+            if (bindMs > 0.05) {
+                val bytesPerMs = bindBytes / bindMs
+                ewmaBindBytesPerMs =
+                    if (ewmaBindBytesPerMs == 0.0) bytesPerMs
+                    else bytesPerMs * EWMA_ALPHA + ewmaBindBytesPerMs * (1.0 - EWMA_ALPHA)
+                adaptiveEagerBindBudget = (ewmaBindBytesPerMs * TARGET_EAGER_BIND_MS).toInt()
+                    .coerceIn(MIN_EAGER_BIND_BUDGET, MAX_EAGER_BIND_BUDGET)
+            }
+        }
         var loadedAny = false
         var stoppedAtBudget = false
         var uploaded = 0
-        // Lazy-init — most frames upload nothing and shouldn't pay for an ArrayList.
-        var newlyUploadedTextures: ArrayList<Texture>? = null
         while (uploaded < adaptiveInstallCap) {
             val entry = pendingMeshUploads.tryReceive().getOrNull() ?: break
             uploaded++
@@ -520,13 +536,7 @@ open class Ogc3dTilesLayer(
                 entry.tile.content = entry.shell
                 entry.tile.loadState = Tile3d.LoadState.LOADED
                 entry.shell.submeshes?.forEach { sub ->
-                    sub.baseColorTextureKey?.let { key ->
-                        (rc.renderResourceCache[key] as? Texture)?.let { tex ->
-                            val list = newlyUploadedTextures
-                                ?: ArrayList<Texture>(8).also { newlyUploadedTextures = it }
-                            list.add(tex)
-                        }
-                    }
+                    sub.baseColorTextureKey?.let { key -> pendingEagerBinds.addLast(key) }
                 }
                 loadedAny = true
             } catch (t: Throwable) {
@@ -538,25 +548,55 @@ open class Ogc3dTilesLayer(
             }
         }
         if (uploaded >= adaptiveInstallCap) stoppedAtBudget = true
-        newlyUploadedTextures?.let { rc.offerBackgroundDrawable(TextureEagerBindDrawable(it)) }
-        // Redraw if we installed new content this frame OR if we hit the cap with
-        // entries still pending — without the latter, an idle camera could leave the
-        // channel sitting with un-installed uploads.
-        if (loadedAny || stoppedAtBudget) rc.requestRedraw()
+        // Byte-budgeted eager-bind batch; the rest carries over to following frames. Binding
+        // every fresh texture in one frame stalled the GL thread 20-150 ms in city scenes -
+        // a single 2048 mipmapped texture is ~21 MB of glTexImage2D. An oversized texture
+        // still binds alone. Keys (not Texture refs) so an eviction while pending is a skip,
+        // not a resurrected orphan GL texture.
+        if (pendingEagerBinds.isNotEmpty()) {
+            var batchBytes = 0
+            var batch: ArrayList<Texture>? = null
+            while (pendingEagerBinds.isNotEmpty() && batchBytes < adaptiveEagerBindBudget) {
+                val texture = rc.renderResourceCache[pendingEagerBinds.removeFirst()] as? Texture ?: continue
+                batchBytes += texture.byteCount
+                (batch ?: ArrayList<Texture>(8).also { batch = it }).add(texture)
+            }
+            batch?.let { rc.offerBackgroundDrawable(TextureEagerBindDrawable(it, batchBytes)) }
+        }
+        // Redraw if we installed new content this frame OR if we hit the cap with entries
+        // still pending OR if eager binds carried over — without it, an idle camera could
+        // leave the channel or the bind queue sitting with work.
+        if (loadedAny || stoppedAtBudget || pendingEagerBinds.isNotEmpty()) rc.requestRedraw()
     }
 
     // Adaptive throttling state — read + written only on the render thread, so plain vars.
     private var ewmaGLFrameWorkMs: Double = 0.0
     private var adaptiveInstallCap: Int = INITIAL_INSTALL_CAP
 
+    /** RR-cache keys of freshly-installed textures awaiting their first GL bind; drained a
+     *  byte-budgeted batch per frame by [drainPendingMeshUploads]. Render thread only. */
+    private val pendingEagerBinds = ArrayDeque<Any>()
+    private var adaptiveEagerBindBudget: Int = INITIAL_EAGER_BIND_BUDGET
+    /** EWMA of measured texture-upload throughput in bytes per GL-thread millisecond. */
+    private var ewmaBindBytesPerMs = 0.0
+    /** Last batch measurement, written by the GL thread ([TextureEagerBindDrawable.draw]) and
+     *  consumed once by the render thread. Nanos written BEFORE bytes - bytes > 0 publishes
+     *  the pair. */
+    @Volatile private var lastEagerBindNanos = 0L
+    @Volatile private var lastEagerBindBytes = 0
+
     /** Force-binds freshly-cached textures so their first [Texture.allocTexImage] runs
      *  this frame, recycling the CPU-side Bitmap that would otherwise sit in Android
      *  native heap until the tile happens to draw. */
-    private class TextureEagerBindDrawable(private val textures: List<Texture>) : Drawable {
+    private inner class TextureEagerBindDrawable(
+        private val textures: List<Texture>,
+        private val bytes: Int,
+    ) : Drawable {
         override fun draw(dc: DrawContext) {
-            // GL cost is captured by the WorldWind.drawFrame whole-frame wall-time measurement
-            // — no per-drawable self-timing needed.
+            val start = TimeSource.Monotonic.markNow()
             for (texture in textures) texture.bindTexture(dc)
+            lastEagerBindNanos = start.elapsedNow().inWholeNanoseconds
+            lastEagerBindBytes = bytes
         }
         override fun recycle() {}
     }
@@ -1260,6 +1300,16 @@ open class Ogc3dTilesLayer(
         private const val MIN_INSTALL_CAP: Int = 1
         private const val MAX_INSTALL_CAP: Int = 8
 
+        /** GL-thread milliseconds one eager-bind batch may take; the byte budget is this
+         *  slice times the measured upload throughput. Sub-half-vsync at 120 Hz. */
+        private const val TARGET_EAGER_BIND_MS: Double = 3.0
+
+        /** Eager-bind byte-budget bounds and starting value before the first batch
+         *  measurement lands; the working value tracks measured throughput. */
+        private const val INITIAL_EAGER_BIND_BUDGET: Int = 8 * 1024 * 1024
+        private const val MIN_EAGER_BIND_BUDGET: Int = 2 * 1024 * 1024
+        private const val MAX_EAGER_BIND_BUDGET: Int = 32 * 1024 * 1024
+
         /** Pending-upload channel capacity. Back-pressures parsers when uploads can't keep
          *  up. Each in-flight prep retains a decoded bitmap + combined-vertex bytes (~5 MB
          *  CPU memory for Photoreal); 4 in-flight keeps Android native-heap headroom even