react-native-cesium 1.2.7 → 1.2.9

package/ios/metal/MetalBackend.mm

@@ -62,7 +62,7 @@ struct OverlayParamsCPP {
   float    wmTransX;             // offset 48
   float    wmTransY;             // offset 52
   float    wmScale;              // offset 56
-  float    _pad1;                // offset 60
+  float    lodFade;              // offset 60  — LOD dither threshold
   // RTC centre in absolute ECEF (float3).  Fragment shader reconstructs world
   // position as:  wp = in.localPos + rtcCentre  (see shader).
   float    rtcCenterX;           // offset 64
@@ -125,7 +125,7 @@ struct OverlayParams {
   float wmWest, wmSouth, wmEast, wmNorth;
   float wmTransX, wmTransY;
   float wmScale;
-  float _pad1;
+  float lodFade;  // LOD dither threshold (was _pad1)
   // RTC centre in ECEF (float).  wp = in.localPos + rtcCentre gives a world
   // position with ~0.75 m ULP (vs ~4 m for eyeRelPos + cameraEcef at altitude).
   float rtcCenterX, rtcCenterY, rtcCenterZ;
@@ -157,6 +157,20 @@ fragment float4 terrainFragment(
     texture2d<float>         overlayTex   [[texture(0)]],
     texture2d<float>         waterMaskTex [[texture(1)]])
 {
+#ifdef TERRAIN_DITHER
+  // ── LOD transition dither (IGN / Jorge Jimenez) ──────────────────────────
+  // Compiled only into the dither pipeline so the solid pipeline keeps Apple
+  // TBDR Hidden Surface Removal enabled at full speed.  Interleaved Gradient
+  // Noise produces a fine-grained per-pixel threshold approximating blue noise
+  // without a texture lookup; the pattern is far less perceptible than Bayer.
+  // lodFade=1 → all pass; lodFade=0 → all discard.
+  {
+    float ign = fract(52.9829189f *
+        fract(0.06711056f * in.position.x + 0.00583715f * in.position.y));
+    if (ov.lodFade <= ign) { discard_fragment(); }
+  }
+#endif
+
   constexpr sampler s(filter::linear, address::clamp_to_edge);
 
   // ── World position (RTC reconstruction) ──────────────────────────────────
@@ -190,14 +204,19 @@ fragment float4 terrainFragment(
       ? 1.0f
       : waterMaskTex.sample(s, wmUV).r;
 
-  float3 lit;
-
   if (ov.hasOverlay != 0u) {
     float2 texUV = in.uv * float2(ov.scale[0], ov.scale[1])
                  + float2(ov.translation[0], ov.translation[1]);
     texUV.y = 1.0f - texUV.y;
-    lit = overlayTex.sample(s, texUV).rgb;
-  } else {
+    // Return the overlay RGBA directly — preserves any transparency at tile
+    // edges and avoids incorrectly stamping the coastline outline on top of
+    // satellite imagery.  The dither discard above fires before this return,
+    // so LOD fading still works correctly on overlay tiles.
+    return overlayTex.sample(s, texUV);
+  }
+
+  float3 lit;
+  {
     // ── Lighting ──────────────────────────────────────────────────────────
     // Normals from screen-space derivatives of tile-local position.
     // (Using localPos rather than eyeRelPos makes no difference for the
@@ -237,21 +256,28 @@ fragment float4 terrainFragment(
 
     // 1 km lat/lon grid — fades when sub-pixel to suppress Moiré.
     float gridLat = 1000.f / 6371000.f;
-    float cosLat  = max(cos(lat), 0.001f);
+    // cosLat from pxy (already computed above for the Bowring iteration) —
+    // avoids a second cos() transcendental.  pxy/a_e is the geocentric cosine;
+    // the ~0.2 % geodetic difference is imperceptible at grid-line scale.
+    float cosLat  = max(pxy / 6378137.f, 0.001f);
     float gridLon = gridLat / cosLat;
     float wLat = fwidth(lat) * 1.5f, wLon = fwidth(lon) * 1.5f;
     float gridVis = clamp(min(gridLat / max(wLat, 1e-9f),
                               gridLon / max(wLon, 1e-9f)), 0.f, 1.f);
+    // MSL fmod() uses truncation (not floor), which returns negative values for
+    // negative latitudes (southern hemisphere) — use the floor formula.
     float latCell = lat - gridLat * floor(lat / gridLat);
     float lonCell = lon - gridLon * floor(lon / gridLon);
     float dLat = min(latCell, gridLat - latCell);
     float dLon = min(lonCell, gridLon - lonCell);
-    float gridA = max(1.f - smoothstep(0.f, wLat, dLat),
-                      1.f - smoothstep(0.f, wLon, dLon)) * gridVis;
+    // Linear ramp instead of smoothstep cubic — visually identical for a
+    // 1.5 px anti-aliased line, saves two multiplies per component.
+    float gridA = max(clamp(1.f - dLat / max(wLat, 1e-9f), 0.f, 1.f),
+                      clamp(1.f - dLon / max(wLon, 1e-9f), 0.f, 1.f)) * gridVis;
     lit = mix(lit, float3(0.15f, 0.15f, 0.15f), gridA * 0.6f);
   }
 
-  // Coastline outline from water mask (magenta for easy diagnostics).
+  // Coastline outline from water mask.
   if (ov.isEllipsoidFallback == 0u) {
     float dWater  = fwidth(waterVal);
     float coastPx = abs(waterVal - 0.5f) / max(dWater * 0.5f, 0.01f);
@@ -373,7 +399,8 @@ namespace reactnativecesium {
 
 MetalBackend::MetalBackend()
     : device_(nullptr), commandQueue_(nullptr), metalLayer_(nullptr),
-      terrainPipeline_(nullptr), skyPipeline_(nullptr),
+      terrainSolidPipeline_(nullptr), terrainDitherPipeline_(nullptr),
+      skyPipeline_(nullptr),
       terrainDepthState_(nullptr), skyDepthState_(nullptr),
       depthTexture_(nullptr), fallbackTexture_(nullptr),
       fallbackWaterMaskTexture_(nullptr),
@@ -383,6 +410,8 @@ MetalBackend::MetalBackend()
   for (int i = 0; i < kMaxFramesInFlight; ++i) {
     vtxBufs_[i] = idxBufs_[i] = uvBufs_[i] = altBufs_[i] = nullptr;
     vtxCaps_[i] = idxCaps_[i] = uvCaps_[i] = altCaps_[i] = 0;
+    uniformsBufs_[i] = nullptr;
+    uniformsCaps_[i] = 0;
   }
 }
 
@@ -418,40 +447,68 @@ void MetalBackend::buildRenderPipelines() {
   CAMetalLayer* layer = (__bridge CAMetalLayer*)metalLayer_;
   const MTLPixelFormat colorFmt = layer.pixelFormat;
 
-  if (terrainPipeline_) {
-    CFRelease(terrainPipeline_);
-    terrainPipeline_ = nullptr;
+  if (terrainSolidPipeline_) {
+    CFRelease(terrainSolidPipeline_);
+    terrainSolidPipeline_ = nullptr;
+  }
+  if (terrainDitherPipeline_) {
+    CFRelease(terrainDitherPipeline_);
+    terrainDitherPipeline_ = nullptr;
   }
   if (skyPipeline_) {
     CFRelease(skyPipeline_);
     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:&terrainLibErr];
-  if (!tLib) {
-    NSLog(@"[MetalBackend] terrain shader compilation FAILED: %@", terrainLibErr);
-    return;
-  }
+  // Build two terrain pipelines from a single MSL source:
+  //   • Solid:  compiled without TERRAIN_DITHER → no discard_fragment() in the
+  //             shader, so Apple TBDR Hidden Surface Removal stays enabled.
+  //             Used for every tile whose LOD-fade percentage is 1.0 (i.e. the
+  //             overwhelming majority outside an active LOD transition).
+  //   • Dither: compiled with TERRAIN_DITHER=1 → includes the IGN-based dither
+  //             discard.  Only used for tiles where DrawPrimitive::lodFade<1.
+  //
+  // Engineering trade-off documented in CesiumEngine::updateFrame: the draws
+  // are stable_partition-ed so all solid tiles come first; a single pipeline
+  // switch per frame is then enough to render the fading tail.
+  auto buildTerrainPipeline =
+      ^id<MTLRenderPipelineState>(NSDictionary<NSString*, NSObject*>* macros,
+                                  NSString* label) {
+    MTLCompileOptions* opts = [MTLCompileOptions new];
+    if (macros) opts.preprocessorMacros = macros;
+    NSError* libErr = nil;
+    id<MTLLibrary> lib = [dev newLibraryWithSource:kTerrainShaderSrc
+                                            options:opts error:&libErr];
+    if (!lib) {
+      NSLog(@"[MetalBackend] terrain %@ shader compilation FAILED: %@",
+            label, libErr);
+      return nil;
+    }
+    MTLRenderPipelineDescriptor* desc = [MTLRenderPipelineDescriptor new];
+    desc.label             = [@"terrain-" stringByAppendingString:label];
+    desc.vertexFunction    = [lib newFunctionWithName:@"terrainVertex"];
+    desc.fragmentFunction  = [lib newFunctionWithName:@"terrainFragment"];
+    desc.colorAttachments[0].pixelFormat = colorFmt;
+    desc.depthAttachmentPixelFormat      = MTLPixelFormatDepth32Float;
+    desc.rasterSampleCount               = (NSUInteger)std::max(1, sampleCount_);
+    NSError* pipeErr = nil;
+    id<MTLRenderPipelineState> pipe =
+        [dev newRenderPipelineStateWithDescriptor:desc error:&pipeErr];
+    if (!pipe) {
+      NSLog(@"[MetalBackend] terrain %@ pipeline build FAILED: %@",
+            label, pipeErr);
+    }
+    return pipe;
+  };
 
-  MTLRenderPipelineDescriptor* tDesc = [MTLRenderPipelineDescriptor new];
-  tDesc.vertexFunction   = [tLib newFunctionWithName:@"terrainVertex"];
-  tDesc.fragmentFunction = [tLib newFunctionWithName:@"terrainFragment"];
-  tDesc.colorAttachments[0].pixelFormat = colorFmt;
-  tDesc.depthAttachmentPixelFormat      = MTLPixelFormatDepth32Float;
-  tDesc.rasterSampleCount               = (NSUInteger)std::max(1, sampleCount_);
-  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;
+  id<MTLRenderPipelineState> solidPipeline = buildTerrainPipeline(nil, @"solid");
+  if (!solidPipeline) return;
+  terrainSolidPipeline_ = (__bridge_retained void*)solidPipeline;
+
+  id<MTLRenderPipelineState> ditherPipeline = buildTerrainPipeline(
+      @{ @"TERRAIN_DITHER": @"1" }, @"dither");
+  if (!ditherPipeline) return;
+  terrainDitherPipeline_ = (__bridge_retained void*)ditherPipeline;
 
   NSError* skyLibErr = nil;
   id<MTLLibrary> sLib = [dev newLibraryWithSource:kSkyShaderSrc
@@ -562,12 +619,15 @@ void MetalBackend::shutdown() {
     if (idxBufs_[i]) { CFRelease(idxBufs_[i]); idxBufs_[i] = nullptr; }
     if (uvBufs_[i])  { CFRelease(uvBufs_[i]);  uvBufs_[i]  = nullptr; }
     if (altBufs_[i]) { CFRelease(altBufs_[i]); altBufs_[i] = nullptr; }
+    if (uniformsBufs_[i]) { CFRelease(uniformsBufs_[i]); uniformsBufs_[i] = nullptr; }
+    uniformsCaps_[i] = 0;
     vtxCaps_[i] = idxCaps_[i] = uvCaps_[i] = altCaps_[i] = 0;
   }
 
   if (device_)                   { CFRelease(device_);                   device_                  = nullptr; }
   if (commandQueue_)             { CFRelease(commandQueue_);             commandQueue_            = nullptr; }
-  if (terrainPipeline_)          { CFRelease(terrainPipeline_);          terrainPipeline_         = nullptr; }
+  if (terrainSolidPipeline_)     { CFRelease(terrainSolidPipeline_);     terrainSolidPipeline_    = nullptr; }
+  if (terrainDitherPipeline_)    { CFRelease(terrainDitherPipeline_);    terrainDitherPipeline_   = nullptr; }
   if (skyPipeline_)              { CFRelease(skyPipeline_);              skyPipeline_             = nullptr; }
   if (terrainDepthState_)        { CFRelease(terrainDepthState_);        terrainDepthState_       = nullptr; }
   if (skyDepthState_)            { CFRelease(skyDepthState_);            skyDepthState_           = nullptr; }
@@ -763,38 +823,75 @@ void MetalBackend::drawScene(const FrameResult& frame) {
   }
 
   // ── Terrain pass ──────────────────────────────────────────────────────────
-  if (frame.draws.empty() || frame.localPositions.empty() || frame.indices.empty() ||
-      !terrainPipeline_ || !terrainDepthState_) {
+  if (frame.draws.empty() ||
+      !terrainSolidPipeline_ || !terrainDitherPipeline_ || !terrainDepthState_) {
     return;
   }
 
   const int fi = frameIndex_;
 
-  // Upload merged geometry to the current frame's persistent Metal buffers.
-  const size_t vtxBytes = frame.localPositions.size() * sizeof(float);
-  const size_t idxBytes = frame.indices.size()        * sizeof(uint32_t);
-  const size_t uvBytes  = frame.uvs.size()            * sizeof(float);
-  const size_t altBytes = frame.altitudes.size()      * sizeof(float);
-
-  id<MTLBuffer> vtxBuf = ensureBuffer(&vtxBufs_[fi], &vtxCaps_[fi],
-                                       vtxBytes, frame.localPositions.data(), dev);
-  id<MTLBuffer> idxBuf = ensureBuffer(&idxBufs_[fi], &idxCaps_[fi],
-                                       idxBytes, frame.indices.data(), dev);
-  id<MTLBuffer> uvBuf  = ensureBuffer(&uvBufs_[fi],  &uvCaps_[fi],
-                                       uvBytes,  frame.uvs.data(), dev);
-  id<MTLBuffer> altBuf = ensureBuffer(&altBufs_[fi], &altCaps_[fi],
-                                       altBytes, frame.altitudes.data(), dev);
+  // check the per-slot geometry signature. When it matches the engine
+  // has intentionally skipped repopulating the merged CPU arrays — the
+  // persistent vtx/idx/uv/alt buffers from a previous frame already hold the
+  // right bytes for this signature.
+  const uint64_t sig         = frame.geometrySignature;
+  const bool     slotMatches = (sig != 0ULL) && (sig == geomSlotSig_[fi]);
+
+  if (!slotMatches && (frame.localPositions.empty() || frame.indices.empty())) {
+    return;
+  }
+
+  id<MTLBuffer> vtxBuf = nil;
+  id<MTLBuffer> idxBuf = nil;
+  id<MTLBuffer> uvBuf  = nil;
+  id<MTLBuffer> altBuf = nil;
+
+  if (slotMatches) {
+    vtxBuf = (__bridge id<MTLBuffer>)vtxBufs_[fi];
+    idxBuf = (__bridge id<MTLBuffer>)idxBufs_[fi];
+    uvBuf  = (__bridge id<MTLBuffer>)uvBufs_[fi];
+    altBuf = (__bridge id<MTLBuffer>)altBufs_[fi];
+  } else {
+    const size_t vtxBytes = frame.localPositions.size() * sizeof(float);
+    const size_t idxBytes = frame.indices.size()        * sizeof(uint32_t);
+    const size_t uvBytes  = frame.uvs.size()            * sizeof(float);
+    const size_t altBytes = frame.altitudes.size()      * sizeof(float);
+
+    vtxBuf = ensureBuffer(&vtxBufs_[fi], &vtxCaps_[fi],
+                          vtxBytes, frame.localPositions.data(), dev);
+    idxBuf = ensureBuffer(&idxBufs_[fi], &idxCaps_[fi],
+                          idxBytes, frame.indices.data(), dev);
+    uvBuf  = ensureBuffer(&uvBufs_[fi],  &uvCaps_[fi],
+                          uvBytes,  frame.uvs.data(), dev);
+    altBuf = ensureBuffer(&altBufs_[fi], &altCaps_[fi],
+                          altBytes, frame.altitudes.data(), dev);
+
+    // Record what this slot now holds — set only after all four buffers
+    // have been refreshed (avoids the partial-update bug we hit on the
+    // previous attempt where the signature was bumped after the first
+    // buffer copy and the rest were skipped).
+    geomSlotSig_[fi] = sig;
+  }
 
   if (!vtxBuf || !idxBuf || !altBuf) return;
 
-  [enc setRenderPipelineState:(__bridge id<MTLRenderPipelineState>)terrainPipeline_];
+  id<MTLRenderPipelineState> solidPS  =
+      (__bridge id<MTLRenderPipelineState>)terrainSolidPipeline_;
+  id<MTLRenderPipelineState> ditherPS =
+      (__bridge id<MTLRenderPipelineState>)terrainDitherPipeline_;
+  // Start with the solid pipeline. CesiumEngine has stable_partition-ed draws so
+  // every lodFade==1 draw is first; we only switch to the dither pipeline once,
+  // when the first fading draw is reached.
+  id<MTLRenderPipelineState> currentPS = solidPS;
+  [enc setRenderPipelineState:currentPS];
   [enc setDepthStencilState:(__bridge id<MTLDepthStencilState>)terrainDepthState_];
   [enc setFrontFacingWinding:MTLWindingCounterClockwise];
   [enc setCullMode:MTLCullModeBack];
 
   // Set vertex buffers that are shared across all draws.
   // buffer(0): tile-local positions, buffer(1): altitudes, buffer(3): UVs.
-  // buffer(2) is the per-draw MVP set in the loop below.
+  // buffer(2) is the per-draw VS uniforms (offset is updated per draw via the
+  // uniforms ring, fragment slot 0 likewise).
   [enc setVertexBuffer:vtxBuf offset:0 atIndex:0];
   [enc setVertexBuffer:altBuf offset:0 atIndex:1];
   if (uvBuf) [enc setVertexBuffer:uvBuf offset:0 atIndex:3];
@@ -802,55 +899,113 @@ void MetalBackend::drawScene(const FrameResult& frame) {
   id<MTLTexture> fallbackTex   = (__bridge id<MTLTexture>)fallbackTexture_;
   id<MTLTexture> fallbackWMTex = (__bridge id<MTLTexture>)fallbackWaterMaskTexture_;
 
+  // ── build the per-draw uniforms ring ───────────────────────────────
+  // Layout: [draw0 VS][draw0 FS][draw1 VS][draw1 FS]…, each padded to
+  // kUniformAlign (256 B). One contiguous MTLBuffer per frame slot. We
+  // memcpy all per-draw structs in one pass on the CPU, then in the draw
+  // loop only update setVertexBufferOffset / setFragmentBufferOffset.
+  const size_t pad      = kUniformAlign;
+  const size_t vsStride = ((sizeof(PerDrawVertexUniformsCPP) + pad - 1) / pad) * pad;
+  const size_t fsStride = ((sizeof(OverlayParamsCPP)         + pad - 1) / pad) * pad;
+  const size_t perDraw  = vsStride + fsStride;
+  const size_t needed   = perDraw * frame.draws.size();
+
+  id<MTLBuffer> uniBuf = nil;
+  if (needed > 0) {
+    if (needed > uniformsCaps_[fi]) {
+      size_t newCap = std::max(needed, uniformsCaps_[fi] > 0 ? uniformsCaps_[fi] * 2 : needed);
+      newCap = (newCap + 4095UL) & ~4095UL;
+      if (uniformsBufs_[fi]) CFRelease(uniformsBufs_[fi]);
+      id<MTLBuffer> b = [dev newBufferWithLength:newCap
+                                          options:MTLResourceStorageModeShared];
+      uniformsBufs_[fi] = (__bridge_retained void*)b;
+      uniformsCaps_[fi] = newCap;
+    }
+    uniBuf = (__bridge id<MTLBuffer>)uniformsBufs_[fi];
+
+    uint8_t* base = static_cast<uint8_t*>(uniBuf.contents);
+    size_t   off  = 0;
+    for (const auto& draw : frame.draws) {
+      auto* vdu = reinterpret_cast<PerDrawVertexUniformsCPP*>(base + off);
+      const float* mp = glm::value_ptr(draw.mvpMatrix);
+      for (int i = 0; i < 16; ++i) vdu->mvpMatrix[i] = mp[i];
+
+      auto* ov = reinterpret_cast<OverlayParamsCPP*>(base + off + vsStride);
+      *ov = OverlayParamsCPP{};
+      ov->hasOverlay          = (draw.overlayTexture && draw.hasUVs) ? 1u : 0u;
+      ov->isEllipsoidFallback = draw.isEllipsoidFallback ? 1u : 0u;
+      ov->isOnlyWater         = draw.isOnlyWater         ? 1u : 0u;
+      ov->hasWaterMask        = draw.waterMaskTexture     ? 1u : 0u;
+      ov->translation[0]      = draw.overlayTranslation.x;
+      ov->translation[1]      = draw.overlayTranslation.y;
+      ov->scale[0]            = draw.overlayScale.x;
+      ov->scale[1]            = draw.overlayScale.y;
+      ov->wmWest              = draw.wmTileBounds.x;
+      ov->wmSouth             = draw.wmTileBounds.y;
+      ov->wmEast              = draw.wmTileBounds.z;
+      ov->wmNorth             = draw.wmTileBounds.w;
+      ov->wmTransX            = draw.wmTranslation.x;
+      ov->wmTransY            = draw.wmTranslation.y;
+      ov->wmScale             = draw.wmScale;
+      ov->lodFade             = draw.lodFade;
+      ov->rtcCenterX          = draw.rtcCenterEcef.x;
+      ov->rtcCenterY          = draw.rtcCenterEcef.y;
+      ov->rtcCenterZ          = draw.rtcCenterEcef.z;
+      ov->cameraTilespaceX    = frame.cameraEcef.x - draw.rtcCenterEcef.x;
+      ov->cameraTilespaceY    = frame.cameraEcef.y - draw.rtcCenterEcef.y;
+      ov->cameraTilespaceZ    = frame.cameraEcef.z - draw.rtcCenterEcef.z;
+
+      off += perDraw;
+    }
+
+    // Bind once; per-draw we only rebind the offset (cheap encoder call).
+    [enc setVertexBuffer:uniBuf   offset:0 atIndex:2];
+    [enc setFragmentBuffer:uniBuf offset:0 atIndex:0];
+  }
+
   if (fallbackWMTex) [enc setFragmentTexture:fallbackWMTex atIndex:1];
 
+  // track last-bound textures to dedupe redundant setFragmentTexture
+  // calls. The Vulkan path already dedupes its descriptor-set 1/2 binds via
+  // VkDescriptorSet identity; this matches that on Metal.
+  id<MTLTexture> lastTex0 = nil;
+  id<MTLTexture> lastTex1 = fallbackWMTex; // bound above
+
+  size_t drawOff = 0;
   for (const auto& draw : frame.draws) {
+    const size_t thisOff = drawOff;
+    drawOff += perDraw;
+
     if (draw.indexCount == 0) continue;
 
-    // ── Per-draw vertex uniforms: the tile's RTC MVP matrix ───────────────
-    PerDrawVertexUniformsCPP vdu{};
-    const float* mp = glm::value_ptr(draw.mvpMatrix);
-    for (int i = 0; i < 16; ++i) vdu.mvpMatrix[i] = mp[i];
-    [enc setVertexBytes:&vdu length:sizeof(vdu) atIndex:2];
-
-    // ── Per-draw fragment uniforms ─────────────────────────────────────────
-    OverlayParamsCPP ov{};
-    ov.hasOverlay          = (draw.overlayTexture && draw.hasUVs) ? 1u : 0u;
-    ov.isEllipsoidFallback = draw.isEllipsoidFallback ? 1u : 0u;
-    ov.isOnlyWater         = draw.isOnlyWater         ? 1u : 0u;
-    ov.hasWaterMask        = draw.waterMaskTexture     ? 1u : 0u;
-    ov.translation[0]      = draw.overlayTranslation.x;
-    ov.translation[1]      = draw.overlayTranslation.y;
-    ov.scale[0]            = draw.overlayScale.x;
-    ov.scale[1]            = draw.overlayScale.y;
-    ov.wmWest              = draw.wmTileBounds.x;
-    ov.wmSouth             = draw.wmTileBounds.y;
-    ov.wmEast              = draw.wmTileBounds.z;
-    ov.wmNorth             = draw.wmTileBounds.w;
-    ov.wmTransX            = draw.wmTranslation.x;
-    ov.wmTransY            = draw.wmTranslation.y;
-    ov.wmScale             = draw.wmScale;
-    // RTC: tile centre and camera-in-tile-space for fragment world-position
-    // reconstruction and view-direction lighting.
-    ov.rtcCenterX          = draw.rtcCenterEcef.x;
-    ov.rtcCenterY          = draw.rtcCenterEcef.y;
-    ov.rtcCenterZ          = draw.rtcCenterEcef.z;
-    // cameraTilespace = cameraEcef − rtcCentre.  Calculated here to keep the
-    // fragment shader free of subtraction of two large float3 values.
-    ov.cameraTilespaceX    = frame.cameraEcef.x - draw.rtcCenterEcef.x;
-    ov.cameraTilespaceY    = frame.cameraEcef.y - draw.rtcCenterEcef.y;
-    ov.cameraTilespaceZ    = frame.cameraEcef.z - draw.rtcCenterEcef.z;
-    [enc setFragmentBytes:&ov length:sizeof(ov) atIndex:0];
+    // ── Pipeline switch for LOD-fade dither ─────────────────────────────────
+    // Solid pipeline (no discard) for fully-visible tiles preserves Apple TBDR
+    // Hidden Surface Removal; dither pipeline only used for actively-fading
+    // tiles. Draws are partitioned so this switch fires at most once per frame.
+    id<MTLRenderPipelineState> wantedPS = (draw.lodFade < 1.0f) ? ditherPS : solidPS;
+    if (wantedPS != currentPS) {
+      currentPS = wantedPS;
+      [enc setRenderPipelineState:currentPS];
+    }
+
+    [enc setVertexBufferOffset:thisOff             atIndex:2];
+    [enc setFragmentBufferOffset:thisOff + vsStride atIndex:0];
 
     id<MTLTexture> tex = (draw.overlayTexture && draw.hasUVs)
         ? (__bridge id<MTLTexture>)draw.overlayTexture
         : fallbackTex;
-    if (tex) [enc setFragmentTexture:tex atIndex:0];
+    if (tex && tex != lastTex0) {
+      [enc setFragmentTexture:tex atIndex:0];
+      lastTex0 = tex;
+    }
 
     id<MTLTexture> wmTex = draw.waterMaskTexture
         ? (__bridge id<MTLTexture>)draw.waterMaskTexture
         : fallbackWMTex;
-    if (wmTex) [enc setFragmentTexture:wmTex atIndex:1];
+    if (wmTex && wmTex != lastTex1) {
+      [enc setFragmentTexture:wmTex atIndex:1];
+      lastTex1 = wmTex;
+    }
 
     [enc drawIndexedPrimitives:MTLPrimitiveTypeTriangle
                     indexCount:draw.indexCount

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

@@ -57,7 +57,7 @@ export interface CesiumViewProps extends HybridViewProps {
     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. */
+    /** Refuse to render holes in the terrain. Default false (matching Cesium Native). Relax for fast pans. */
     forbidHoles?: boolean;
     /** Decode water-mask textures (coastline shading). Default true. */
     enableWaterMask?: boolean;
@@ -71,9 +71,17 @@ export interface CesiumViewProps extends HybridViewProps {
     enableLodTransitionPeriod?: boolean;
     /** Length (s) of the LOD cross-fade. Default 1. */
     lodTransitionLength?: number;
-    /** Sqlite asset cache row budget. Default 4096. */
+    /**
+     * Sqlite asset cache row budget. Default 4096.
+     * Must be set on initial mount — changes after the first render are ignored
+     * because the cache is opened once at engine construction time.
+     */
     sqliteCacheMaxRows?: number;
-    /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
+    /**
+     * Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..16).
+     * Must be set on initial mount — the thread pool is sized once at engine
+     * construction time and cannot be resized at runtime.
+     */
     taskProcessorThreads?: number;
     /**
      * Minimum altitude above the loaded terrain surface, in metres MSL.

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":"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"}
+{"version":3,"file":"cesium-view.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/cesium-view.nitro.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-cesium",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "description": "Experimental Cesium rendering for React Native via Nitro (iOS/Metal today; Android planned)",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/specs/cesium-view.nitro.ts

@@ -61,13 +61,17 @@ export interface CesiumViewProps extends HybridViewProps {
   ionImageryAssetId: number
 
   // ── Optional perf / quality knobs ────────────────────────────────────────
+  // Note: all optional props below use "set once" semantics. Once a value has
+  // been applied to the native engine, removing the prop (returning it to
+  // `undefined`) does NOT revert the engine to its built-in default — the last
+  // explicitly set value is retained. To reset, pass the desired default value.
   /** 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. */
+  /** Refuse to render holes in the terrain. Default false (matching Cesium Native). Relax for fast pans. */
   forbidHoles?: boolean
   /** Decode water-mask textures (coastline shading). Default true. */
   enableWaterMask?: boolean
@@ -81,9 +85,17 @@ export interface CesiumViewProps extends HybridViewProps {
   enableLodTransitionPeriod?: boolean
   /** Length (s) of the LOD cross-fade. Default 1. */
   lodTransitionLength?: number
-  /** Sqlite asset cache row budget. Default 4096. */
+  /**
+   * Sqlite asset cache row budget. Default 4096.
+   * Must be set on initial mount — changes after the first render are ignored
+   * because the cache is opened once at engine construction time.
+   */
   sqliteCacheMaxRows?: number
-  /** Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..8). */
+  /**
+   * Worker thread count. 0 = auto (hardware_concurrency-1, clamped 2..16).
+   * Must be set on initial mount — the thread pool is sized once at engine
+   * construction time and cannot be resized at runtime.
+   */
   taskProcessorThreads?: number
   /**
    * Minimum altitude above the loaded terrain surface, in metres MSL.
@@ -98,6 +110,8 @@ export interface CesiumViewProps extends HybridViewProps {
   // angular / linear speed on the integrator's per-DoF velocity. Useful when
   // your sensor feed is noisy and you would rather drop the change than
   // visually whip the camera.
+  // Note: same "set once" semantics as the knobs above — removing the prop
+  // keeps the last value rather than reverting to 0 (uncapped).
   /** Maximum yaw rate (degrees per second). 0 = uncapped. */
   maxYawRateDegSec?: number
   /** Maximum pitch rate (degrees per second). 0 = uncapped. */