react-native-cesium 1.0.1

package/cpp/engine/ResourcePreparer.cpp

@@ -0,0 +1,224 @@
+#include "ResourcePreparer.hpp"
+
+#include <Cesium3DTilesSelection/Tile.h>
+#include <CesiumGltf/ImageAsset.h>
+#include <CesiumGltf/Model.h>
+#include <CesiumUtility/JsonValue.h>
+
+#include <cstring>
+#include <spdlog/spdlog.h>
+
+namespace reactnativecesium {
+
+ResourcePreparer::ResourcePreparer(TileLifecycleManager& lifecycle)
+    : lifecycle_(lifecycle) {}
+
+CesiumAsync::Future<Cesium3DTilesSelection::TileLoadResultAndRenderResources>
+ResourcePreparer::prepareInLoadThread(
+    const CesiumAsync::AsyncSystem& asyncSystem,
+    Cesium3DTilesSelection::TileLoadResult&& tileLoadResult,
+    const glm::dmat4& transform,
+    const std::any& /*rendererOptions*/) {
+
+  const CesiumGltf::Model* pModel =
+      std::get_if<CesiumGltf::Model>(&tileLoadResult.contentKind);
+
+  TileGPUResources* res = new TileGPUResources();
+  if (pModel) {
+    res->primitives = GltfToMesh::convert(*pModel, transform);
+
+    if (!pModel->meshes.empty() && !pModel->meshes[0].primitives.empty()) {
+      const CesiumGltf::MeshPrimitive& prim = pModel->meshes[0].primitives[0];
+      const CesiumUtility::JsonValue&  ex   = prim.extras;
+
+      const auto* onlyWater = ex.getValuePtrForKey("OnlyWater");
+      const auto* onlyLand  = ex.getValuePtrForKey("OnlyLand");
+      const bool  isOnlyWater = onlyWater && onlyWater->getBool();
+      const bool  isOnlyLand  = onlyLand  && onlyLand->getBool();
+
+      const auto* texIdPtr = ex.getValuePtrForKey("WaterMaskTex");
+      const int64_t texId  = texIdPtr ? texIdPtr->getSafeNumber<int64_t>().value_or(-2) : -3;
+
+      const auto* wmTxPtr = ex.getValuePtrForKey("WaterMaskTranslationX");
+      const auto* wmTyPtr = ex.getValuePtrForKey("WaterMaskTranslationY");
+      const auto* wmSPtr  = ex.getValuePtrForKey("WaterMaskScale");
+      res->wmTranslation.x = wmTxPtr ? (float)wmTxPtr->getSafeNumber<double>().value_or(0.0) : 0.0f;
+      res->wmTranslation.y = wmTyPtr ? (float)wmTyPtr->getSafeNumber<double>().value_or(0.0) : 0.0f;
+      res->wmScale         = wmSPtr  ? (float)wmSPtr->getSafeNumber<double>().value_or(1.0)  : 1.0f;
+      res->isOnlyWater     = isOnlyWater;
+
+      if (!isOnlyWater && !isOnlyLand) {
+        if (texIdPtr && texId >= 0 &&
+            static_cast<size_t>(texId) < pModel->textures.size()) {
+          const int32_t srcId = pModel->textures[static_cast<size_t>(texId)].source;
+          if (srcId >= 0 && static_cast<size_t>(srcId) < pModel->images.size()) {
+            const auto& img = pModel->images[static_cast<size_t>(srcId)];
+            const bool assetOk = img.pAsset &&
+                                 img.pAsset->width == 256 &&
+                                 img.pAsset->height == 256 &&
+                                 img.pAsset->channels == 1 &&
+                                 img.pAsset->bytesPerChannel == 1 &&
+                                 img.pAsset->pixelData.size() == 65536;
+            if (assetOk) {
+              res->waterMaskPixels.resize(256 * 256 * 4);
+              const auto* src =
+                  reinterpret_cast<const uint8_t*>(img.pAsset->pixelData.data());
+              for (int i = 0; i < 256 * 256; ++i) {
+                const uint8_t v = src[i];
+                res->waterMaskPixels[i * 4 + 0] = v;
+                res->waterMaskPixels[i * 4 + 1] = v;
+                res->waterMaskPixels[i * 4 + 2] = v;
+                res->waterMaskPixels[i * 4 + 3] = 255;
+              }
+            } else {
+              spdlog::warn("[WM] tile srcId={} has unexpected image format", srcId);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return asyncSystem.createResolvedFuture(
+      Cesium3DTilesSelection::TileLoadResultAndRenderResources{
+          std::move(tileLoadResult), res});
+}
+
+void* ResourcePreparer::prepareInMainThread(
+    Cesium3DTilesSelection::Tile& /*tile*/, void* pLoadThreadResult) {
+  auto* res = static_cast<TileGPUResources*>(pLoadThreadResult);
+  if (res) {
+    res->lastUsedFrame = lifecycle_.currentFrame();
+    if (!res->waterMaskPixels.empty() && waterMaskCreator_) {
+      res->waterMaskTexture = waterMaskCreator_(
+          res->waterMaskPixels.data(), 256, 256);
+      res->waterMaskPixels.clear();
+      res->waterMaskPixels.shrink_to_fit();
+    } else if (!res->waterMaskPixels.empty() && !waterMaskCreator_) {
+      spdlog::error("[WM] waterMaskCreator_ is null — water mask will not be uploaded");
+    }
+  }
+  return pLoadThreadResult;
+}
+
+void ResourcePreparer::free(Cesium3DTilesSelection::Tile& /*tile*/,
+                             void* pLoadThreadResult,
+                             void* pMainThreadResult) noexcept {
+  TileGPUResources* res = pLoadThreadResult
+      ? static_cast<TileGPUResources*>(pLoadThreadResult)
+      : static_cast<TileGPUResources*>(pMainThreadResult);
+  if (res) {
+    if (res->waterMaskTexture && waterMaskDeleter_) {
+      waterMaskDeleter_(res->waterMaskTexture);
+    }
+    delete res;
+  }
+}
+
+// ── Raster overlay pipeline ─────────────────────────────────────────────────
+
+void* ResourcePreparer::prepareRasterInLoadThread(CesiumGltf::ImageAsset& image,
+                                                   const std::any&) {
+  if (image.pixelData.empty() || image.width <= 0 || image.height <= 0) {
+    return nullptr;
+  }
+  if (image.compressedPixelFormat != CesiumGltf::GpuCompressedPixelFormat::NONE) {
+    return nullptr;
+  }
+  if (image.bytesPerChannel != 1) return nullptr;
+
+  auto* data = new RasterPixelData();
+  data->width  = image.width;
+  data->height = image.height;
+
+  const size_t pixelCount = static_cast<size_t>(image.width) *
+                            static_cast<size_t>(image.height);
+  data->pixels.resize(pixelCount * 4);
+
+  const auto* src = reinterpret_cast<const uint8_t*>(image.pixelData.data());
+
+  if (image.channels == 4) {
+    std::memcpy(data->pixels.data(), src, pixelCount * 4);
+  } else if (image.channels == 3) {
+    for (size_t i = 0; i < pixelCount; ++i) {
+      data->pixels[i * 4 + 0] = src[i * 3 + 0];
+      data->pixels[i * 4 + 1] = src[i * 3 + 1];
+      data->pixels[i * 4 + 2] = src[i * 3 + 2];
+      data->pixels[i * 4 + 3] = 255;
+    }
+  } else if (image.channels == 1) {
+    for (size_t i = 0; i < pixelCount; ++i) {
+      uint8_t v = src[i];
+      data->pixels[i * 4 + 0] = v;
+      data->pixels[i * 4 + 1] = v;
+      data->pixels[i * 4 + 2] = v;
+      data->pixels[i * 4 + 3] = 255;
+    }
+  } else {
+    std::fill(data->pixels.begin(), data->pixels.end(), uint8_t(255));
+  }
+
+  return data;
+}
+
+void* ResourcePreparer::prepareRasterInMainThread(
+    CesiumRasterOverlays::RasterOverlayTile& /*rasterTile*/,
+    void* pLoadThreadResult) {
+  auto* pixelData = static_cast<RasterPixelData*>(pLoadThreadResult);
+  if (!pixelData) return nullptr;
+
+  void* texture = nullptr;
+  if (gpuTextureCreator_) {
+    texture = gpuTextureCreator_(
+        pixelData->pixels.data(), pixelData->width, pixelData->height);
+  }
+
+  delete pixelData;
+  return texture;
+}
+
+void ResourcePreparer::freeRaster(
+    const CesiumRasterOverlays::RasterOverlayTile& /*rasterTile*/,
+    void* pLoadThreadResult,
+    void* pMainThreadResult) noexcept {
+  if (pLoadThreadResult) {
+    delete static_cast<RasterPixelData*>(pLoadThreadResult);
+  }
+  if (pMainThreadResult && gpuTextureDeleter_) {
+    gpuTextureDeleter_(pMainThreadResult);
+  }
+}
+
+void ResourcePreparer::attachRasterInMainThread(
+    const Cesium3DTilesSelection::Tile& tile,
+    int32_t /*overlayTextureCoordinateID*/,
+    const CesiumRasterOverlays::RasterOverlayTile& /*rasterTile*/,
+    void* pMainThreadRendererResources,
+    const glm::dvec2& translation,
+    const glm::dvec2& scale) {
+  const auto* renderContent = tile.getContent().getRenderContent();
+  if (!renderContent) return;
+  auto* res = static_cast<TileGPUResources*>(renderContent->getRenderResources());
+  if (res) {
+    res->overlayTexture     = pMainThreadRendererResources;
+    res->overlayTranslation = glm::vec2(translation);
+    res->overlayScale       = glm::vec2(scale);
+  }
+}
+
+void ResourcePreparer::detachRasterInMainThread(
+    const Cesium3DTilesSelection::Tile& tile,
+    int32_t /*overlayTextureCoordinateID*/,
+    const CesiumRasterOverlays::RasterOverlayTile& /*rasterTile*/,
+    void* /*pMainThreadRendererResources*/) noexcept {
+  const auto* renderContent = tile.getContent().getRenderContent();
+  if (!renderContent) return;
+  auto* res = static_cast<TileGPUResources*>(renderContent->getRenderResources());
+  if (res) {
+    res->overlayTexture     = nullptr;
+    res->overlayTranslation = {0.0f, 0.0f};
+    res->overlayScale       = {1.0f, 1.0f};
+  }
+}
+
+} // namespace reactnativecesium

package/cpp/engine/ResourcePreparer.hpp

@@ -0,0 +1,96 @@
+#pragma once
+
+#include "../renderer/RenderTypes.hpp"
+#include "GltfToMesh.hpp"
+#include "TileLifecycleManager.hpp"
+
+#include <Cesium3DTilesSelection/IPrepareRendererResources.h>
+
+#include <functional>
+#include <vector>
+
+namespace reactnativecesium {
+
+// Raw decoded pixel data produced on the background load thread.
+// Converted to a platform texture on the main thread via GPUTextureCreator.
+struct RasterPixelData {
+  std::vector<uint8_t> pixels; // RGBA8 decoded image
+  int32_t width  = 0;
+  int32_t height = 0;
+};
+
+// Factory: called on the MAIN THREAD to create a native GPU texture
+// (id<MTLTexture> on iOS, VulkanTexture* on Android) from decoded RGBA8 pixels.
+// Set from the platform bridge before any overlays are activated.
+using GPUTextureCreator =
+    std::function<void*(const uint8_t* pixels, int32_t width, int32_t height)>;
+
+// Destructor: called to free a GPU texture previously created by GPUTextureCreator.
+// On iOS: CFRelease(tex). On Android: VulkanBackend::freeRasterTexture(tex).
+using GPUTextureDeleter = std::function<void(void* tex)>;
+
+class ResourcePreparer
+    : public Cesium3DTilesSelection::IPrepareRendererResources {
+public:
+  explicit ResourcePreparer(TileLifecycleManager& lifecycle);
+  ~ResourcePreparer() override = default;
+
+  void setGPUTextureCreator(GPUTextureCreator creator) {
+    gpuTextureCreator_ = std::move(creator);
+  }
+  void setGPUTextureDeleter(GPUTextureDeleter deleter) {
+    gpuTextureDeleter_ = std::move(deleter);
+  }
+
+  // Water mask texture lifecycle — identical signature to the imagery callbacks
+  // but the platform allocates from a different descriptor pool (Vulkan Set 2).
+  void setWaterMaskTextureCreator(GPUTextureCreator creator) {
+    waterMaskCreator_ = std::move(creator);
+  }
+  void setWaterMaskTextureDeleter(GPUTextureDeleter deleter) {
+    waterMaskDeleter_ = std::move(deleter);
+  }
+
+  CesiumAsync::Future<Cesium3DTilesSelection::TileLoadResultAndRenderResources>
+  prepareInLoadThread(
+      const CesiumAsync::AsyncSystem& asyncSystem,
+      Cesium3DTilesSelection::TileLoadResult&& tileLoadResult,
+      const glm::dmat4& transform,
+      const std::any& rendererOptions) override;
+
+  void* prepareInMainThread(Cesium3DTilesSelection::Tile& tile,
+                            void* pLoadThreadResult) override;
+
+  void free(Cesium3DTilesSelection::Tile& tile, void* pLoadThreadResult,
+            void* pMainThreadResult) noexcept override;
+
+  void* prepareRasterInLoadThread(CesiumGltf::ImageAsset& image,
+                                  const std::any& rendererOptions) override;
+  void* prepareRasterInMainThread(
+      CesiumRasterOverlays::RasterOverlayTile& rasterTile,
+      void* pLoadThreadResult) override;
+  void freeRaster(const CesiumRasterOverlays::RasterOverlayTile& rasterTile,
+                  void* pLoadThreadResult,
+                  void* pMainThreadResult) noexcept override;
+  void attachRasterInMainThread(
+      const Cesium3DTilesSelection::Tile& tile,
+      int32_t overlayTextureCoordinateID,
+      const CesiumRasterOverlays::RasterOverlayTile& rasterTile,
+      void* pMainThreadRendererResources,
+      const glm::dvec2& translation,
+      const glm::dvec2& scale) override;
+  void detachRasterInMainThread(
+      const Cesium3DTilesSelection::Tile& tile,
+      int32_t overlayTextureCoordinateID,
+      const CesiumRasterOverlays::RasterOverlayTile& rasterTile,
+      void* pMainThreadRendererResources) noexcept override;
+
+private:
+  TileLifecycleManager& lifecycle_;
+  GPUTextureCreator     gpuTextureCreator_;
+  GPUTextureDeleter     gpuTextureDeleter_;
+  GPUTextureCreator     waterMaskCreator_;
+  GPUTextureDeleter     waterMaskDeleter_;
+};
+
+} // namespace reactnativecesium

package/cpp/engine/TaskProcessor.cpp

@@ -0,0 +1,61 @@
+#include "TaskProcessor.hpp"
+
+namespace reactnativecesium {
+
+TaskProcessor::TaskProcessor(uint32_t numThreads) {
+  workers_.reserve(numThreads);
+  for (uint32_t i = 0; i < numThreads; ++i) {
+    workers_.emplace_back(&TaskProcessor::workerLoop, this);
+  }
+}
+
+TaskProcessor::~TaskProcessor() {
+  shutdown_.store(true, std::memory_order_release);
+  cv_.notify_all();
+  for (auto& t : workers_) {
+    if (t.joinable()) {
+      t.join();
+    }
+  }
+}
+
+void TaskProcessor::startTask(std::function<void()> f) {
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    tasks_.push(std::move(f));
+  }
+  cv_.notify_one();
+}
+
+void TaskProcessor::waitUntilIdle() {
+  std::unique_lock<std::mutex> lock(mutex_);
+  idleCv_.wait(lock, [this] {
+    return tasks_.empty() && activeTasks_ == 0;
+  });
+}
+
+void TaskProcessor::workerLoop() {
+  while (true) {
+    std::function<void()> task;
+    {
+      std::unique_lock<std::mutex> lock(mutex_);
+      cv_.wait(lock, [this] {
+        return shutdown_.load(std::memory_order_acquire) || !tasks_.empty();
+      });
+      if (shutdown_.load(std::memory_order_acquire) && tasks_.empty()) {
+        return;
+      }
+      task = std::move(tasks_.front());
+      tasks_.pop();
+      ++activeTasks_; // increment under the lock so waitUntilIdle sees it
+    }
+    task();
+    {
+      std::lock_guard<std::mutex> lock(mutex_);
+      --activeTasks_;
+    }
+    idleCv_.notify_all(); // wake any thread waiting in waitUntilIdle
+  }
+}
+
+} // namespace reactnativecesium

package/cpp/engine/TaskProcessor.hpp

@@ -0,0 +1,43 @@
+#pragma once
+
+#include <CesiumAsync/ITaskProcessor.h>
+
+#include <atomic>
+#include <condition_variable>
+#include <functional>
+#include <mutex>
+#include <queue>
+#include <thread>
+#include <vector>
+
+namespace reactnativecesium {
+
+class TaskProcessor : public CesiumAsync::ITaskProcessor {
+public:
+  explicit TaskProcessor(uint32_t numThreads = 4);
+  ~TaskProcessor() override;
+
+  TaskProcessor(const TaskProcessor&) = delete;
+  TaskProcessor& operator=(const TaskProcessor&) = delete;
+
+  void startTask(std::function<void()> f) override;
+
+  // Block the calling thread until the task queue is empty and every
+  // in-flight task has returned.  Worker tasks may post main-thread
+  // callbacks (via the AsyncSystem) and return without waiting for them,
+  // so this does not deadlock when called from the main thread.
+  void waitUntilIdle();
+
+private:
+  void workerLoop();
+
+  std::vector<std::thread>           workers_;
+  std::queue<std::function<void()>>  tasks_;
+  std::mutex                         mutex_;
+  std::condition_variable            cv_;
+  std::condition_variable            idleCv_;   // signalled when queue + active reach 0
+  std::atomic<bool>                  shutdown_{false};
+  uint32_t                           activeTasks_{0}; // guarded by mutex_
+};
+
+} // namespace reactnativecesium

package/cpp/engine/TileLifecycleManager.cpp

@@ -0,0 +1,30 @@
+#include "TileLifecycleManager.hpp"
+
+#include <Cesium3DTilesSelection/TileContent.h>
+#include <Cesium3DTilesSelection/TileSelectionState.h>
+
+namespace reactnativecesium {
+
+void TileLifecycleManager::stampTileUsed(TileGPUResources* resources) {
+  if (resources) {
+    resources->lastUsedFrame = frameNumber_;
+  }
+}
+
+bool TileLifecycleManager::shouldDeferFree(
+    const TileGPUResources* resources) const {
+  if (!resources)
+    return false;
+  return resources->lastUsedFrame >= frameNumber_;
+}
+
+bool TileLifecycleManager::isRefinementLocked(
+    const Cesium3DTilesSelection::Tile& /*tile*/) const {
+  // Cesium Native guarantees that free() is not called on tiles that are
+  // currently needed for rendering (including refined parent tiles whose
+  // children are loading). Therefore, explicit refinement locking is not
+  // required here.
+  return false;
+}
+
+} // namespace reactnativecesium

package/cpp/engine/TileLifecycleManager.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "../renderer/RenderTypes.hpp"
+
+#include <Cesium3DTilesSelection/Tile.h>
+
+#include <cstdint>
+
+namespace reactnativecesium {
+
+class TileLifecycleManager {
+public:
+  uint64_t currentFrame() const { return frameNumber_; }
+  void advanceFrame() { ++frameNumber_; }
+
+  void stampTileUsed(TileGPUResources* resources);
+
+  bool shouldDeferFree(const TileGPUResources* resources) const;
+  bool isRefinementLocked(const Cesium3DTilesSelection::Tile& tile) const;
+
+private:
+  uint64_t frameNumber_ = 0;
+};
+
+} // namespace reactnativecesium

package/cpp/fmt/format.h

@@ -0,0 +1,9 @@
+// Shadow header: must appear on the include path before Cesium Native's bundled fmt.
+// Apple Clang rejects fmt's default FMT_STRING (consteval / FMT_COMPILE_STRING) in some
+// spdlog helpers; runtime format strings are sufficient for this library.
+#pragma once
+
+#include_next <fmt/format.h>
+
+#undef FMT_STRING
+#define FMT_STRING(s) ::fmt::runtime(s)

package/cpp/renderer/IGPUBackend.hpp

@@ -0,0 +1,22 @@
+#pragma once
+
+#include "RenderTypes.hpp"
+
+#include <glm/glm.hpp>
+
+namespace reactnativecesium {
+
+class IGPUBackend {
+public:
+  virtual ~IGPUBackend() = default;
+
+  virtual void initialize(void* nativeSurface, int width, int height) = 0;
+  virtual void resize(int width, int height) = 0;
+  virtual void shutdown() = 0;
+
+  virtual void beginFrame(const FrameParams& params) = 0;
+  virtual void drawScene(const FrameResult& frame) = 0;
+  virtual void endFrame() = 0;
+};
+
+} // namespace reactnativecesium

package/cpp/renderer/RenderTypes.hpp

@@ -0,0 +1,112 @@
+#pragma once
+
+#include <cstdint>
+#include <vector>
+#include <glm/glm.hpp>
+
+namespace reactnativecesium {
+
+// ── CPU-side tile resources ─────────────────────────────────────────────────
+// RTC (Relative-to-Center) layout:
+//   • rtcCenter   – tile centre in absolute ECEF (double precision)
+//   • localPositions – vertex positions relative to rtcCenter (float32)
+//     Keeping positions small (~tile radius) preserves float32 precision even
+//     at planetary scale.  The large camera-to-centre offset is baked into the
+//     per-tile MVP matrix using double-precision arithmetic on the CPU; only the
+//     final cast to float32 (which happens at the end of double-precision maths)
+//     introduces rounding, not the original position data.
+//   • altitudes   – ellipsoid height in metres per vertex, computed on the CPU
+//     in double precision (Bowring formula in double gives sub-mm accuracy).
+//     Passed as a vertex attribute so the fragment shader never has to call
+//     ellipsoidHeightMeters(wp) — that path catastrophically cancels two ~6.4 Mm
+//     float32 values and produces ±50 m errors.
+
+struct TilePrimitive {
+  glm::dvec3              rtcCenter;       // tile RTC centre in absolute ECEF (double)
+  std::vector<glm::vec3>  localPositions;  // vertex positions relative to rtcCenter (float)
+  std::vector<float>      altitudes;       // ellipsoid height metres per vertex (float, from double)
+  std::vector<glm::vec2>  uvs;             // overlay UV coords (_CESIUMOVERLAY_0); empty if unavailable
+  std::vector<uint32_t>   indices;         // triangle list (uint32)
+};
+
+struct TileGPUResources {
+  std::vector<TilePrimitive> primitives;
+  uint64_t lastUsedFrame  = 0;
+  void*    overlayTexture = nullptr;
+  glm::vec2 overlayTranslation{0.0f, 0.0f};
+  glm::vec2 overlayScale{1.0f, 1.0f};
+
+  // Water mask — extracted from GLTF extras in the load thread, then converted
+  // to a GPU texture on the main thread by the platform waterMaskCreator_.
+  std::vector<uint8_t> waterMaskPixels;
+  void* waterMaskTexture = nullptr;
+  bool      isOnlyWater      = false;
+  glm::vec2 wmTranslation{0.0f, 0.0f};
+  float     wmScale = 1.0f;
+};
+
+// ── Per-frame result passed from engine to renderer ─────────────────────────
+
+struct DrawPrimitive {
+  uint32_t  indexByteOffset      = 0;
+  uint32_t  indexCount           = 0;
+  bool      hasUVs               = false;
+  bool      isEllipsoidFallback  = false;
+  void*     overlayTexture       = nullptr;
+  glm::vec2 overlayTranslation{0.0f, 0.0f};
+  glm::vec2 overlayScale{1.0f, 1.0f};
+  void*     waterMaskTexture     = nullptr;
+  bool      isOnlyWater          = false;
+  glm::vec4 wmTileBounds{0.0f, 0.0f, 0.0f, 0.0f};
+  glm::vec2 wmTranslation{0.0f, 0.0f};
+  float     wmScale = 1.0f;
+
+  // RTC: per-tile MVP matrix (computed in double precision on the CPU,
+  // then cast to float32).  Used by the vertex shader instead of the global
+  // rotation-only VP, so that the large camera↔tile-centre offset is encoded
+  // accurately without a float32 subtraction in the vertex shader.
+  glm::mat4 mvpMatrix{1.0f};
+
+  // Tile RTC centre in ECEF (float3).  Passed to the fragment shader so it can
+  // reconstruct the world position as  wp = localPos + rtcCenterEcef,  which
+  // avoids the catastrophic cancellation of eyeRelPos + cameraEcef at altitude.
+  glm::vec3 rtcCenterEcef{0.0f};
+};
+
+struct FrameResult {
+  // Merged geometry — one flat buffer, globally-offset indices.
+  // localPositions: vertex positions relative to each tile's RTC centre (float).
+  // altitudes:      ellipsoid height metres per vertex (float, double-precision source).
+  std::vector<float>    localPositions; // xyz per vertex (tile-local float)
+  std::vector<float>    altitudes;      // 1 float per vertex, ellipsoid height metres
+  std::vector<float>    uvs;            // uv per vertex (2 floats)
+  std::vector<uint32_t> indices;
+
+  std::vector<DrawPrimitive> draws;
+
+  // Global rotation-only VP (no translation) — used by the sky shader and for
+  // reference.  Terrain tiles use per-draw mvpMatrix instead.
+  glm::mat4 vpMatrix;
+  glm::vec3 cameraEcef;   // camera ECEF (float) — for sky shader
+  glm::mat4 invVP;
+
+  int tilesRendered  = 0;
+  int tilesLoading   = 0;
+  int tilesVisited   = 0;
+  double cameraLat   = 0.0;
+  double cameraLon   = 0.0;
+  double cameraAlt   = 0.0;
+
+  bool                     ionTokenConfigured = false;
+  bool                     tilesetActive      = false;
+  double                   verticalFovDeg     = 60.0;
+  std::vector<std::string> creditHtmlLines;
+};
+
+// ── Frame setup ─────────────────────────────────────────────────────────────
+
+struct FrameParams {
+  glm::vec4 clearColor{0.0f, 0.0f, 0.0f, 1.0f};
+};
+
+} // namespace reactnativecesium

package/cpp/renderer/ShaderTypes.hpp

@@ -0,0 +1,29 @@
+#pragma once
+
+#include <glm/glm.hpp>
+
+namespace reactnativecesium {
+
+// NOTE: Metal float3 has 16-byte alignment in structs (same as float4).
+// To avoid C++/Metal layout mismatch, each vec3+float pair is packed into vec4.
+struct SceneUniforms {
+  glm::mat4 viewProjection;
+  glm::vec4 cameraPositionF;   // w = earthRadius
+  glm::vec4 sunDirection;      // w = atmosphereHeight
+  glm::vec4 atmosphereColor;   // w = (unused, pad)
+};
+
+// Metal float3x3 columns are each 16 bytes (same as float4).
+// Store matrices as three float4 columns to avoid C++/Metal layout mismatch.
+struct TileUniforms {
+  glm::vec4 rtcCenterHigh;   // .w = 0 (pad)
+  glm::vec4 rtcCenterLow;    // .w = 0 (pad)
+  glm::vec4 rotCol0;         // rotation matrix col 0, .w = 0
+  glm::vec4 rotCol1;         // rotation matrix col 1, .w = 0
+  glm::vec4 rotCol2;         // rotation matrix col 2, .w = 0
+  glm::vec4 normalCol0;      // normalMatrix col 0, .w = 0
+  glm::vec4 normalCol1;      // normalMatrix col 1, .w = 0
+  glm::vec4 normalCol2;      // normalMatrix col 2, .w = 0
+};
+
+} // namespace reactnativecesium