react-native-cesium 1.0.6 → 1.2.0

package/ios/HybridCesiumView.swift

@@ -8,15 +8,23 @@ class HybridCesiumView: HybridCesiumViewSpec {
   // MARK: - Props
 
   var ionAccessToken: String = "" {
-    didSet { bridge?.updateIonAccessToken(ionAccessToken, assetId: Int64(ionAssetId)) }
+    didSet {
+      let token = ionAccessToken
+      let assetId = Int64(ionAssetId)
+      postToRender { [weak self] in self?.bridge?.updateIonAccessToken(token, assetId: assetId) }
+    }
   }
   var ionAssetId: Double = 1 {
-    didSet { bridge?.updateIonAccessToken(ionAccessToken, assetId: Int64(ionAssetId)) }
+    didSet {
+      let token = ionAccessToken
+      let assetId = Int64(ionAssetId)
+      postToRender { [weak self] in self?.bridge?.updateIonAccessToken(token, assetId: assetId) }
+    }
   }
 
-  /// Construction-time seed camera. Once the bridge exists, use `setCamera(_:)`
-  /// for runtime updates; later prop writes are stored but do not drive the
-  /// active native camera.
+  /// Construction-time seed camera. Used exactly once when the native bridge
+  /// is created; subsequent prop writes are ignored. Use `setCamera(_:)` to
+  /// drive the camera at runtime — it does NOT mutate this value.
   var initialCamera: CameraState = CameraState(
     latitude: 46.15,
     longitude: 7.35,
@@ -28,32 +36,82 @@ class HybridCesiumView: HybridCesiumViewSpec {
   )
   var pauseRendering: Bool = false {
     didSet {
-      displayLink?.isPaused = pauseRendering
+      displayLink?.isPaused = pauseRendering // UIKit-ish, must stay on main
       if !pauseRendering {
-        bridge?.markNeedsRender()
+        postToRender { [weak self] in self?.bridge?.markNeedsRender() }
       }
     }
   }
 
   var maximumScreenSpaceError: Double = 32 {
-    didSet { bridge?.setMaximumScreenSpaceError(maximumScreenSpaceError) }
+    didSet { let v = maximumScreenSpaceError; postToRender { [weak self] in self?.bridge?.setMaximumScreenSpaceError(v) } }
   }
   var maximumSimultaneousTileLoads: Double = 12 {
-    didSet { bridge?.setMaximumSimultaneousTileLoads(Int32(maximumSimultaneousTileLoads)) }
+    didSet { let v = Int32(maximumSimultaneousTileLoads); postToRender { [weak self] in self?.bridge?.setMaximumSimultaneousTileLoads(v) } }
   }
   var loadingDescendantLimit: Double = 20 {
-    didSet { bridge?.setLoadingDescendantLimit(Int32(loadingDescendantLimit)) }
+    didSet { let v = Int32(loadingDescendantLimit); postToRender { [weak self] in self?.bridge?.setLoadingDescendantLimit(v) } }
   }
   var msaaSampleCount: Double = 1 {
     didSet {
       let s = Int32(msaaSampleCount)
-      bridge?.setMsaaSampleCount(s)
+      // applyMtkViewMsaa touches MTKView/UIKit so it stays on main.
       applyMtkViewMsaa(Int(s))
+      postToRender { [weak self] in self?.bridge?.setMsaaSampleCount(s) }
     }
   }
   var ionImageryAssetId: Double = 1 {
-    didSet { bridge?.updateImageryAssetId(Int64(ionImageryAssetId)) }
+    didSet { let v = Int64(ionImageryAssetId); postToRender { [weak self] in self?.bridge?.updateImageryAssetId(v) } }
+  }
+
+  // ── Optional perf / quality knobs ────────────────────────────────────────
+  var maximumCachedMiB: Double? {
+    didSet { if let v = maximumCachedMiB { postToRender { [weak self] in self?.bridge?.setMaximumCachedMiB(Int32(v)) } } }
+  }
+  var preloadAncestors: Bool? {
+    didSet { if let v = preloadAncestors { postToRender { [weak self] in self?.bridge?.setPreloadAncestors(v) } } }
+  }
+  var preloadSiblings: Bool? {
+    didSet { if let v = preloadSiblings { postToRender { [weak self] in self?.bridge?.setPreloadSiblings(v) } } }
+  }
+  var forbidHoles: Bool? {
+    didSet { if let v = forbidHoles { postToRender { [weak self] in self?.bridge?.setForbidHoles(v) } } }
+  }
+  var enableWaterMask: Bool? {
+    didSet { if let v = enableWaterMask { postToRender { [weak self] in self?.bridge?.setEnableWaterMask(v) } } }
+  }
+  var enableFogCulling: Bool? {
+    didSet { if let v = enableFogCulling { postToRender { [weak self] in self?.bridge?.setEnableFogCulling(v) } } }
+  }
+  var enforceCulledScreenSpaceError: Bool? {
+    didSet { if let v = enforceCulledScreenSpaceError { postToRender { [weak self] in self?.bridge?.setEnforceCulledScreenSpaceError(v) } } }
   }
+  var culledScreenSpaceError: Double? {
+    didSet { if let v = culledScreenSpaceError { postToRender { [weak self] in self?.bridge?.setCulledScreenSpaceError(v) } } }
+  }
+  var enableLodTransitionPeriod: Bool? {
+    didSet { if let v = enableLodTransitionPeriod { postToRender { [weak self] in self?.bridge?.setEnableLodTransitionPeriod(v) } } }
+  }
+  var lodTransitionLength: Double? {
+    didSet { if let v = lodTransitionLength { postToRender { [weak self] in self?.bridge?.setLodTransitionLength(v) } } }
+  }
+  var sqliteCacheMaxRows: Double? {
+    didSet { if let v = sqliteCacheMaxRows { postToRender { [weak self] in self?.bridge?.setSqliteCacheMaxRows(Int32(v)) } } }
+  }
+  var taskProcessorThreads: Double? {
+    didSet { if let v = taskProcessorThreads { postToRender { [weak self] in self?.bridge?.setTaskProcessorThreads(Int32(v)) } } }
+  }
+
+  // MARK: - Render-thread dispatch helper
+
+  /// Posts a closure to the dedicated render queue. Used by every prop setter
+  /// that mutates engine state, so the EngineConfig + GPU resources are only
+  /// ever touched from one thread (renderQueue) — the render path itself, the
+  /// surface init, and bridge teardown all run there.
+  private func postToRender(_ action: @escaping () -> Void) {
+    renderQueue.async { action() }
+  }
+
   var onMetrics: ((CesiumMetrics) -> Void)?
 
   // MARK: - Methods
@@ -81,15 +139,19 @@ class HybridCesiumView: HybridCesiumViewSpec {
   }
 
   func setCamera(camera: CameraState) throws {
-    // Runtime camera updates flow through this method; if the view is not ready
-    // yet we keep the latest value and apply it during initialization.
-    initialCamera = camera
-    pushCameraStateIfChanged(camera)
+    // Runtime camera updates flow through this method. We do *not* mutate
+    // `initialCamera` (it is construction-time only). If the view is not
+    // ready yet, the value is buffered in `pendingRuntimeCamera` and pushed
+    // during initialization.
+    pendingRuntimeCamera = camera
+    pendingRuntimeViewCorrection = nil
+    postToRender { [weak self] in self?.pushCameraStateIfChanged(camera) }
   }
 
   func setCameraQuaternion(camera: CameraState, viewCorrection: Quaternion) throws {
-    initialCamera = camera
-    pushCameraQuaternionIfChanged(camera, viewCorrection: viewCorrection)
+    pendingRuntimeCamera = camera
+    pendingRuntimeViewCorrection = viewCorrection
+    postToRender { [weak self] in self?.pushCameraQuaternionIfChanged(camera, viewCorrection: viewCorrection) }
   }
 
   func getViewCorrection() throws -> Promise<Quaternion> {
@@ -120,8 +182,28 @@ class HybridCesiumView: HybridCesiumViewSpec {
   private var lastPushedCameraState: CameraState?
   /// Last quaternion pushed via `setCameraQuaternion`; `nil` if only `setCamera` has been used.
   private var lastPushedViewCorrection: Quaternion?
+  /// Camera state requested by `setCamera` before the bridge was ready.
+  private var pendingRuntimeCamera: CameraState?
+  private var pendingRuntimeViewCorrection: Quaternion?
   private var lastBridgePixelSize: CGSize = .zero
 
+  /// Dedicated serial render queue. CADisplayLink fires on `.main`, but the
+  /// actual `bridge.shouldRenderNextFrame()` / `bridge.renderFrame(...)` work
+  /// is dispatched here so the main thread is never blocked on Cesium tile
+  /// loading or Metal command-buffer encoding. All bridge prop setters also
+  /// dispatch here so they serialize with rendering and never race with
+  /// engine state.
+  private let renderQueue = DispatchQueue(
+    label: "com.margelo.cesium.render",
+    qos: .userInteractive
+  )
+  /// Drops a CADisplayLink tick if the render queue is still finishing the
+  /// previous frame — keeps it from queuing up an unbounded backlog under
+  /// stutter (Metal's frameSemaphore would already throttle, but this saves
+  /// the dispatch hop and keeps `dt` accurate).
+  private var renderInFlight = false
+  private let renderInFlightLock = NSLock()
+
   var view: UIView { metalView }
 
   override init() {
@@ -185,7 +267,17 @@ class HybridCesiumView: HybridCesiumViewSpec {
     if !ionAccessToken.isEmpty {
       bridge?.updateIonAccessToken(ionAccessToken, assetId: Int64(ionAssetId))
     }
+    // Apply construction-time seed first; if the consumer already invoked
+    // setCamera / setCameraQuaternion before we were ready, replay it last so
+    // the runtime value wins.
     pushCameraStateIfChanged(initialCamera)
+    if let runtime = pendingRuntimeCamera {
+      if let q = pendingRuntimeViewCorrection {
+        pushCameraQuaternionIfChanged(runtime, viewCorrection: q)
+      } else {
+        pushCameraStateIfChanged(runtime)
+      }
+    }
     if ionImageryAssetId != 1 {
       bridge?.updateImageryAssetId(Int64(ionImageryAssetId))
     }
@@ -215,6 +307,18 @@ class HybridCesiumView: HybridCesiumViewSpec {
     bridge?.setMaximumScreenSpaceError(maximumScreenSpaceError)
     bridge?.setMaximumSimultaneousTileLoads(Int32(maximumSimultaneousTileLoads))
     bridge?.setLoadingDescendantLimit(Int32(loadingDescendantLimit))
+    if let v = maximumCachedMiB { bridge?.setMaximumCachedMiB(Int32(v)) }
+    if let v = preloadAncestors { bridge?.setPreloadAncestors(v) }
+    if let v = preloadSiblings { bridge?.setPreloadSiblings(v) }
+    if let v = forbidHoles { bridge?.setForbidHoles(v) }
+    if let v = enableWaterMask { bridge?.setEnableWaterMask(v) }
+    if let v = enableFogCulling { bridge?.setEnableFogCulling(v) }
+    if let v = enforceCulledScreenSpaceError { bridge?.setEnforceCulledScreenSpaceError(v) }
+    if let v = culledScreenSpaceError { bridge?.setCulledScreenSpaceError(v) }
+    if let v = enableLodTransitionPeriod { bridge?.setEnableLodTransitionPeriod(v) }
+    if let v = lodTransitionLength { bridge?.setLodTransitionLength(v) }
+    if let v = sqliteCacheMaxRows { bridge?.setSqliteCacheMaxRows(Int32(v)) }
+    if let v = taskProcessorThreads { bridge?.setTaskProcessorThreads(Int32(v)) }
   }
 
   /// Pushes camera state into native bridge only when values changed.
@@ -302,54 +406,107 @@ class HybridCesiumView: HybridCesiumViewSpec {
 
     let dt = max(dl.targetTimestamp - dl.timestamp, 1.0 / 120.0)
 
+    // metalView.bounds / drawableSize are UIKit, must stay on main.
     let scale = metalView.contentScaleFactor
     let w = Int(metalView.bounds.width * scale)
     let h = Int(metalView.bounds.height * scale)
-
+    var didResize = false
     if w > 0 && h > 0 {
       let pixelSize = CGSize(width: w, height: h)
       if lastBridgePixelSize != pixelSize {
         metalView.drawableSize = pixelSize
         lastBridgePixelSize = pixelSize
-        bridge.resize(Int32(w), height: Int32(h))
-        bridge.markNeedsRender()
+        didResize = true
       }
     }
 
-    let shouldRenderNow = bridge.shouldRenderNextFrame()
-    if shouldRenderNow {
-      setDisplayLinkFrameRate(idle: false)
-      idleProbeAccumulator = 0
-      bridge.renderFrame(withDt: dt)
-    } else {
-      setDisplayLinkFrameRate(idle: true)
-      idleProbeAccumulator += dt
-      if idleProbeAccumulator >= 0.25 {
-        // Safety probe: occasionally tick engine state for late tile completions.
-        idleProbeAccumulator = 0
+    // Throttle: drop the tick if the render queue hasn't finished the previous
+    // frame yet. This keeps the dispatch backlog at zero and lets the next
+    // CADisplayLink fire pick up a fresh dt.
+    renderInFlightLock.lock()
+    if renderInFlight {
+      renderInFlightLock.unlock()
+      return
+    }
+    renderInFlight = true
+    renderInFlightLock.unlock()
+
+    let resizedW = w
+    let resizedH = h
+    let weakSelf = self  // captured for main-thread post-frame work
+    renderQueue.async { [weak self, weak bridge] in
+      guard let self = self, let bridge = bridge else {
+        weakSelf.renderInFlightLock.lock()
+        weakSelf.renderInFlight = false
+        weakSelf.renderInFlightLock.unlock()
+        return
+      }
+
+      if didResize {
+        bridge.resize(Int32(resizedW), height: Int32(resizedH))
         bridge.markNeedsRender()
       }
-    }
 
-    metricsFrameCounter += 1
-    if metricsFrameCounter >= 20, let cb = onMetrics {
-      metricsFrameCounter = 0
-      let m = CesiumMetrics(
+      let shouldRenderNow = bridge.shouldRenderNextFrame()
+      let nextIsIdle: Bool
+      if shouldRenderNow {
+        self.idleProbeAccumulator = 0
+        bridge.renderFrame(withDt: dt)
+        nextIsIdle = false
+      } else {
+        self.idleProbeAccumulator += dt
+        if self.idleProbeAccumulator >= 0.25 {
+          // Safety probe: occasionally tick engine state for late tile completions.
+          self.idleProbeAccumulator = 0
+          bridge.markNeedsRender()
+        }
+        nextIsIdle = true
+      }
+
+      self.metricsFrameCounter += 1
+      let shouldEmitMetrics =
+        self.metricsFrameCounter >= 20 && self.onMetrics != nil
+      let metricsSnapshot: CesiumMetrics? = shouldEmitMetrics ? CesiumMetrics(
         fps: bridge.metricsFps,
         tilesRendered: Double(bridge.metricsTilesRendered),
         tilesLoading: Double(bridge.metricsTilesLoading),
         tilesVisited: Double(bridge.metricsTilesVisited),
         ionTokenConfigured: bridge.metricsIonTokenConfigured,
+        tlsConfigured: bridge.metricsTlsConfigured,
         tilesetReady: bridge.metricsTilesetReady,
         creditsPlainText: bridge.metricsCreditsPlainText
-      )
-      cb(m)
+      ) : nil
+      if shouldEmitMetrics { self.metricsFrameCounter = 0 }
+
+      // Hop back to main to update CADisplayLink rate (UIKit) and emit the
+      // metrics callback (consumer may touch UI from it).
+      DispatchQueue.main.async { [weak self] in
+        guard let self = self else { return }
+        self.setDisplayLinkFrameRate(idle: nextIsIdle)
+        if let m = metricsSnapshot, let cb = self.onMetrics {
+          cb(m)
+        }
+      }
+
+      self.renderInFlightLock.lock()
+      self.renderInFlight = false
+      self.renderInFlightLock.unlock()
     }
   }
 
   deinit {
     layoutPollTimer?.invalidate()
     displayLink?.invalidate()
-    bridge?.shutdown()
+
+    // Drain the render queue so we don't release `bridge` while it's
+    // mid-encode. `sync` here is bounded by Metal's frameSemaphore wait —
+    // which itself is already bounded to 1 s in MetalBackend::shutdown().
+    let bridgeRef = bridge
+    bridge = nil
+    if let b = bridgeRef {
+      renderQueue.sync {
+        b.shutdown()
+      }
+    }
   }
 }

package/ios/metal/MetalBackend.mm

@@ -304,15 +304,19 @@ fragment float4 skyFragment(SkyVOut in [[stage_in]],
   float3 org=u.cameraEcef.xyz;
   float2 at=rsi(org,rd,AR);
   if(at.y<0)return float4(0,0,0,1);
-  float2 er=rsi(org,rd,ER);
-  float tmax=at.y;if(er.x>0)tmax=min(tmax,er.x);
+  // No earth-surface tmax clamp — that creates a visible band discontinuity
+  // at the geometric horizon. Integrate full atmospheric path and clamp
+  // underground sample heights to zero (ground-level density).
+  float tmax=at.y;
   float tmin=max(at.x,0.f);if(tmin>=tmax)return float4(0,0,0,1);
-  const int S=16,L=4;
+  // Halved from 16/4 to 8/2 — visually negligible at typical phone DPI
+  // (atmospheric scattering banding is sub-pixel at this sample count).
+  const int S=8,L=2;
   float ss=(tmax-tmin)/float(S);
   float3 rayl=0,miel=0;float oR=0,oM=0;
   for(int i=0;i<S;++i){
     float t=tmin+(float(i)+.5f)*ss;
-    float3 sp=org+rd*t;float h=length(sp)-ER;
+    float3 sp=org+rd*t;float h=max(0.f,length(sp)-ER);
     float hr=exp(-h/10000.f)*ss,hm=exp(-h/3200.f)*ss;
     oR+=hr;oM+=hm;
     float2 lh=rsi(sp,u.lightDir.xyz,AR);
@@ -330,11 +334,16 @@ fragment float4 skyFragment(SkyVOut in [[stage_in]],
   float rPh=.75f*(1+cos2);
   float g2=MG*MG,mPh=1.5f*((1-g2)/(2+g2))*(1+cos2)/pow(1+g2-2*MG*cosT,1.5f);
   float3 col=LINT*(rayl*RAY*rPh+miel*MIE3*mPh);
-  col=1-exp(-col*1.1f);col*=float3(.18f,.45f,1.f);
-  float3 nu=normalize(org);float up=saturate(dot(rd,nu));
-  float camH=max(0.f,length(org)-ER);
-  float hStr=saturate(1-camH/35000.f);
-  col=mix(col,float3(.40f,.62f,.96f),(1-smoothstep(.05f,.45f,up))*.40f*hStr);
+  col=1-exp(-col*1.1f);
+  col*=float3(.30f,.55f,1.f);
+  // Single-scatter atmosphere produces sunset-like yellow at horizons with
+  // long path lengths (because blue out-scatters faster). Real daytime sky
+  // appears whitish-blue at horizon thanks to multiple scattering, which we
+  // approximate here by blending toward a natural blue based on the
+  // total atmospheric path length traversed by the view ray.
+  float pathLen=tmax-tmin;
+  float hazeFactor=smoothstep(100000.f,600000.f,pathLen);
+  col=mix(col,float3(.35f,.58f,.90f),hazeFactor*.65f);
   return float4(col,1.f);
 }
 )MSL";
@@ -409,8 +418,6 @@ void MetalBackend::buildRenderPipelines() {
   CAMetalLayer* layer = (__bridge CAMetalLayer*)metalLayer_;
   const MTLPixelFormat colorFmt = layer.pixelFormat;
 
-  NSError* err = nil;
-
   if (terrainPipeline_) {
     CFRelease(terrainPipeline_);
     terrainPipeline_ = nullptr;
@@ -420,9 +427,16 @@ void MetalBackend::buildRenderPipelines() {
     skyPipeline_ = nullptr;
   }
 
+  // Use a separate NSError* per compile + a strict result check. Sharing a
+  // single `err` across multiple operations conflated unrelated failures
+  // (P2-error-handling).
+  NSError* terrainLibErr = nil;
   id<MTLLibrary> tLib = [dev newLibraryWithSource:kTerrainShaderSrc
-                                          options:nil error:&err];
-  if (err) NSLog(@"[MetalBackend] terrain shader error: %@", err);
+                                          options:nil error:&terrainLibErr];
+  if (!tLib) {
+    NSLog(@"[MetalBackend] terrain shader compilation FAILED: %@", terrainLibErr);
+    return;
+  }
 
   MTLRenderPipelineDescriptor* tDesc = [MTLRenderPipelineDescriptor new];
   tDesc.vertexFunction   = [tLib newFunctionWithName:@"terrainVertex"];
@@ -430,13 +444,22 @@ void MetalBackend::buildRenderPipelines() {
   tDesc.colorAttachments[0].pixelFormat = colorFmt;
   tDesc.depthAttachmentPixelFormat      = MTLPixelFormatDepth32Float;
   tDesc.rasterSampleCount               = (NSUInteger)std::max(1, sampleCount_);
-  terrainPipeline_ = (__bridge_retained void*)
-      [dev newRenderPipelineStateWithDescriptor:tDesc error:&err];
-  if (err) NSLog(@"[MetalBackend] terrain pipeline error: %@", err);
+  NSError* terrainPipelineErr = nil;
+  id<MTLRenderPipelineState> terrainPipeline =
+      [dev newRenderPipelineStateWithDescriptor:tDesc error:&terrainPipelineErr];
+  if (!terrainPipeline) {
+    NSLog(@"[MetalBackend] terrain pipeline build FAILED: %@", terrainPipelineErr);
+    return;
+  }
+  terrainPipeline_ = (__bridge_retained void*)terrainPipeline;
 
+  NSError* skyLibErr = nil;
   id<MTLLibrary> sLib = [dev newLibraryWithSource:kSkyShaderSrc
-                                          options:nil error:&err];
-  if (err) NSLog(@"[MetalBackend] sky shader error: %@", err);
+                                          options:nil error:&skyLibErr];
+  if (!sLib) {
+    NSLog(@"[MetalBackend] sky shader compilation FAILED: %@", skyLibErr);
+    return;
+  }
 
   MTLRenderPipelineDescriptor* sDesc = [MTLRenderPipelineDescriptor new];
   sDesc.vertexFunction   = [sLib newFunctionWithName:@"skyVertex"];
@@ -444,9 +467,14 @@ void MetalBackend::buildRenderPipelines() {
   sDesc.colorAttachments[0].pixelFormat = colorFmt;
   sDesc.depthAttachmentPixelFormat      = MTLPixelFormatDepth32Float;
   sDesc.rasterSampleCount               = (NSUInteger)std::max(1, sampleCount_);
-  skyPipeline_ = (__bridge_retained void*)
-      [dev newRenderPipelineStateWithDescriptor:sDesc error:&err];
-  if (err) NSLog(@"[MetalBackend] sky pipeline error: %@", err);
+  NSError* skyPipelineErr = nil;
+  id<MTLRenderPipelineState> skyPipeline =
+      [dev newRenderPipelineStateWithDescriptor:sDesc error:&skyPipelineErr];
+  if (!skyPipeline) {
+    NSLog(@"[MetalBackend] sky pipeline build FAILED: %@", skyPipelineErr);
+    return;
+  }
+  skyPipeline_ = (__bridge_retained void*)skyPipeline;
 
   if (!terrainDepthState_) {
     MTLDepthStencilDescriptor* dd = [MTLDepthStencilDescriptor new];
@@ -473,8 +501,20 @@ void MetalBackend::setMsaaSampleCount(int sc) {
 
   if (frameSemaphore_) {
     dispatch_semaphore_t sem = (__bridge dispatch_semaphore_t)frameSemaphore_;
+    // Bound the wait per slot at 1 second so a stuck GPU encode (the only
+    // realistic cause of a missed completion handler) cannot wedge the UI
+    // thread forever.  On timeout we proceed regardless: the worst that can
+    // happen is one frame's worth of pipeline rebuild lands on a slot the
+    // GPU is still using, which Metal handles gracefully (the prior
+    // pipeline stays alive via ARC until the encoder finishes).
     for (int i = 0; i < kMaxFramesInFlight; ++i) {
-      dispatch_semaphore_wait(sem, DISPATCH_TIME_FOREVER);
+      dispatch_time_t deadline = dispatch_time(DISPATCH_TIME_NOW,
+                                               (int64_t)NSEC_PER_SEC);
+      if (dispatch_semaphore_wait(sem, deadline) != 0) {
+        NSLog(@"[CesiumMetal] MSAA-change semaphore timed out (slot %d); "
+              @"proceeding with rebuild", i);
+        break;
+      }
     }
   }
 
@@ -499,10 +539,19 @@ void MetalBackend::resize(int width, int height) {
 void MetalBackend::shutdown() {
   // Drain in-flight frames: wait until all GPU completion handlers have fired
   // before releasing the semaphore and the persistent buffers they reference.
+  // Bounded wait — if a slot doesn't release in 1 s we are almost certainly
+  // looking at a hung GPU command. Forcing release lets the app exit/teardown
+  // cleanly rather than ANRing on backgrounding.
   if (frameSemaphore_) {
     dispatch_semaphore_t sem = (__bridge dispatch_semaphore_t)frameSemaphore_;
     for (int i = 0; i < kMaxFramesInFlight; ++i) {
-      dispatch_semaphore_wait(sem, DISPATCH_TIME_FOREVER);
+      dispatch_time_t deadline = dispatch_time(DISPATCH_TIME_NOW,
+                                               (int64_t)NSEC_PER_SEC);
+      if (dispatch_semaphore_wait(sem, deadline) != 0) {
+        NSLog(@"[CesiumMetal] shutdown semaphore wait timed out at slot %d; "
+              @"force-releasing and continuing teardown", i);
+        break;
+      }
     }
     CFRelease(frameSemaphore_);
     frameSemaphore_ = nullptr;

package/lib/typescript/src/specs/cesium-view.nitro.d.ts

@@ -26,6 +26,8 @@ export interface CesiumMetrics {
     tilesLoading: number;
     tilesVisited: number;
     ionTokenConfigured: boolean;
+    /** True when a CA bundle has been resolved for libcurl TLS. */
+    tlsConfigured: boolean;
     tilesetReady: boolean;
     creditsPlainText: string;
 }
@@ -41,6 +43,30 @@ export interface CesiumViewProps extends HybridViewProps {
     /** 1 = off; 2 or 4 = MSAA when supported. */
     msaaSampleCount: number;
     ionImageryAssetId: number;
+    /** RAM budget for live tileset, in mebibytes. Default 256. */
+    maximumCachedMiB?: number;
+    /** Pre-load ancestor tiles around the visible set (smoother panning, more loads). Default true. */
+    preloadAncestors?: boolean;
+    /** Pre-load sibling tiles around the visible set. Default true. */
+    preloadSiblings?: boolean;
+    /** Refuse to render holes in the terrain. Default true. Relax for fast pans. */
+    forbidHoles?: boolean;
+    /** Decode water-mask textures (coastline shading). Default true. */
+    enableWaterMask?: boolean;
+    /** Cull tiles fully inside the fog volume. Default false. */
+    enableFogCulling?: boolean;
+    /** When fog culling is on, override SSE for fogged tiles. Default true. */
+    enforceCulledScreenSpaceError?: boolean;
+    /** SSE applied to fogged tiles when `enforceCulledScreenSpaceError` is true. Default 64. */
+    culledScreenSpaceError?: number;
+    /** Cross-fade between LODs when refining (smoother pop-in). Default false. */
+    enableLodTransitionPeriod?: boolean;
+    /** Length (s) of the LOD cross-fade. Default 1. */
+    lodTransitionLength?: number;
+    /** Sqlite asset cache row budget. Default 4096. */
+    sqliteCacheMaxRows?: number;
+    /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
+    taskProcessorThreads?: number;
     onMetrics?: (metrics: CesiumMetrics) => void;
 }
 export interface CesiumViewMethods extends HybridViewMethods {

package/lib/typescript/src/specs/cesium-view.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,aAAa,EAAE,WAAW,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,sBAAsB,EAAE,MAAM,CAAA;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,+CAA+C;IAC/C,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACpC;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,GAAG,IAAI,CAAA;IAC1E,4FAA4F;IAC5F,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA"}
+{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,aAAa,EAAE,WAAW,CAAA;IAC1B,cAAc,EAAE,OAAO,CAAA;IACvB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,MAAM,CAAA;IACpC,sBAAsB,EAAE,MAAM,CAAA;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IAGzB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,2EAA2E;IAC3E,6BAA6B,CAAC,EAAE,OAAO,CAAA;IACvC,4FAA4F;IAC5F,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,8EAA8E;IAC9E,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAE7B,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,+CAA+C;IAC/C,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACpC;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,GAAG,IAAI,CAAA;IAC1E,4FAA4F;IAC5F,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CACzC;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA"}

package/nitrogen/generated/android/c++/JCesiumMetrics.hpp

@@ -41,6 +41,8 @@ namespace margelo::nitro::reactnativecesium {
       double tilesVisited = this->getFieldValue(fieldTilesVisited);
       static const auto fieldIonTokenConfigured = clazz->getField<jboolean>("ionTokenConfigured");
       jboolean ionTokenConfigured = this->getFieldValue(fieldIonTokenConfigured);
+      static const auto fieldTlsConfigured = clazz->getField<jboolean>("tlsConfigured");
+      jboolean tlsConfigured = this->getFieldValue(fieldTlsConfigured);
       static const auto fieldTilesetReady = clazz->getField<jboolean>("tilesetReady");
       jboolean tilesetReady = this->getFieldValue(fieldTilesetReady);
       static const auto fieldCreditsPlainText = clazz->getField<jni::JString>("creditsPlainText");
@@ -51,6 +53,7 @@ namespace margelo::nitro::reactnativecesium {
         tilesLoading,
         tilesVisited,
         static_cast<bool>(ionTokenConfigured),
+        static_cast<bool>(tlsConfigured),
         static_cast<bool>(tilesetReady),
         creditsPlainText->toStdString()
       );
@@ -62,7 +65,7 @@ namespace margelo::nitro::reactnativecesium {
      */
     [[maybe_unused]]
     static jni::local_ref<JCesiumMetrics::javaobject> fromCpp(const CesiumMetrics& value) {
-      using JSignature = JCesiumMetrics(double, double, double, double, jboolean, jboolean, jni::alias_ref<jni::JString>);
+      using JSignature = JCesiumMetrics(double, double, double, double, jboolean, jboolean, jboolean, jni::alias_ref<jni::JString>);
       static const auto clazz = javaClassStatic();
       static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
       return create(
@@ -72,6 +75,7 @@ namespace margelo::nitro::reactnativecesium {
         value.tilesLoading,
         value.tilesVisited,
         value.ionTokenConfigured,
+        value.tlsConfigured,
         value.tilesetReady,
         jni::make_jstring(value.creditsPlainText)
       );