[enhancement#1658] mesh, material and tile loading callbacks

CHANGES.md

@@ -6,6 +6,8 @@
 
 - Added a Cesium -> Geocoder -> Geocode Blueprint function, making it easy to query the Cesium ion geocoder.
 - Added `UCesiumMetadataPickingBlueprintLibrary::FindPropertyTableProperty` to search for a `FCesiumPropertyTableProperty` by name on a given `UPrimitiveComponent`.
+- Added a property `bAllowMeshBuffersCPUAccess` to `ACesium3DTileset` actors to keep the buffers of Unreal meshes created by the tileset in CPU memory, in order to have access to them in-game. Defaults to false.
+- Added the class `CesiumMeshBuildCallbacks`: when an implementation is registered on a tileset (with `ACesium3DTileset::SetMeshBuildCallbacks`), its functions will be called at various points in a tile's lifecycle, like when a mesh component is created, when a material is instanced, when the tile changes visibility, when it is unloaded, etc.
 
 ##### Fixes :wrench:
 

Source/CesiumRuntime/Private/Cesium3DTileset.cpp

@@ -442,6 +442,14 @@ void ACesium3DTileset::SetCesiumIonServer(UCesiumIonServer* Server) {
   }
 }
 
+void ACesium3DTileset::SetAllowMeshBuffersCPUAccess(
+    bool InMeshBuffersCPUAccess) {
+  if (bAllowMeshBuffersCPUAccess != InMeshBuffersCPUAccess) {
+    this->bAllowMeshBuffersCPUAccess = InMeshBuffersCPUAccess;
+    this->DestroyTileset();
+  }
+}
+
 void ACesium3DTileset::SetMaximumScreenSpaceError(
     double InMaximumScreenSpaceError) {
   if (MaximumScreenSpaceError != InMaximumScreenSpaceError) {
@@ -2322,3 +2330,7 @@ void ACesium3DTileset::RuntimeSettingsChanged(
   }
 }
 #endif
+
+void ACesium3DTileset::SetMeshBuildCallbacks(const TWeakPtr<CesiumMeshBuildCallbacks>& Callbacks) {
+    this->_meshBuildCallbacks = Callbacks;
+}

Source/CesiumRuntime/Private/CesiumGltfComponent.cpp

@@ -9,6 +9,7 @@
 #include "CesiumGltfPrimitiveComponent.h"
 #include "CesiumGltfTextures.h"
 #include "CesiumMaterialUserData.h"
+#include "CesiumMeshBuildCallbacks.h"
 #include "CesiumRasterOverlays.h"
 #include "CesiumRuntime.h"
 #include "CesiumTextureUtility.h"
@@ -1253,6 +1254,9 @@ static void loadPrimitive(
     }
   }
 
+  primitiveResult.MeshBuildCallbacks =
+      options.pMeshOptions->pNodeOptions->pModelOptions->MeshBuildCallbacks;
+
   auto normalAccessorIt = primitive.attributes.find("NORMAL");
   CesiumGltf::AccessorView<TMeshVector3> normalAccessor;
   bool hasNormals = false;
@@ -1668,6 +1672,12 @@ static void loadPrimitive(
     computeTangentSpace(StaticMeshBuildVertices);
   }
 
+  // For iTwin scene mapping mechanism (used both for Synchro 4D schedules and
+  // selection highlight), we need to access vertex data from the CPU (in
+  // packaged game, if we don't set this flag, the data can become inaccessible
+  // at any time...)
+  const bool& bNeedsCPUAccess = options.pMeshOptions->pNodeOptions->pModelOptions->allowMeshBuffersCPUAccess;
+
   {
     TRACE_CPUPROFILER_EVENT_SCOPE(Cesium::InitBuffers)
 
@@ -1679,12 +1689,12 @@ static void loadPrimitive(
 
     LODResources.VertexBuffers.PositionVertexBuffer.Init(
         StaticMeshBuildVertices,
-        false);
+        bNeedsCPUAccess);
 
     FColorVertexBuffer& ColorVertexBuffer =
         LODResources.VertexBuffers.ColorVertexBuffer;
     if (hasVertexColors) {
-      ColorVertexBuffer.Init(StaticMeshBuildVertices, false);
+      ColorVertexBuffer.Init(StaticMeshBuildVertices, bNeedsCPUAccess);
     }
 
     uint32 numberOfTextureCoordinates =
@@ -1697,7 +1707,7 @@ static void loadPrimitive(
     vertexBuffer.Init(
         StaticMeshBuildVertices.Num(),
         numberOfTextureCoordinates,
-        false);
+        bNeedsCPUAccess);
 
     // Manually copy the vertices into the buffer. We do this because UE 5.3
     // and 5.4 have a bug where the overload of `FStaticMeshVertexBuffer::Init`
@@ -1744,6 +1754,9 @@ static void loadPrimitive(
 
   {
     TRACE_CPUPROFILER_EVENT_SCOPE(Cesium::SetIndices)
+    if (bNeedsCPUAccess) {
+      LODResources.IndexBuffer.TrySetAllowCPUAccess(true);
+    }
     LODResources.IndexBuffer.SetIndices(
         indices,
         StaticMeshBuildVertices.Num() >= std::numeric_limits<uint16>::max()
@@ -2452,7 +2465,8 @@ static void SetGltfParameterValues(
     const CesiumGltf::MaterialPBRMetallicRoughness& pbr,
     UMaterialInstanceDynamic* pMaterial,
     EMaterialParameterAssociation association,
-    int32 index) {
+    int32 index,
+    CesiumMeshBuildCallbacks const* meshBuildCallbacks) {
   for (auto& textureCoordinateSet : loadResult.textureCoordinateParameters) {
     pMaterial->SetScalarParameterValueByInfo(
         FMaterialParameterInfo(
@@ -2671,6 +2685,11 @@ static void SetGltfParameterValues(
         FMaterialParameterInfo("emissiveFactor", association, index),
         FVector(1.0f, 1.0f, 1.0f));
   }
+
+  // Extra material customizations
+  if (meshBuildCallbacks) {
+    meshBuildCallbacks->CustomizeGltfMaterial(material, pbr, pMaterial, association, index);
+  }
 }
 
 void SetWaterParameterValues(
@@ -3130,14 +3149,34 @@ static void loadPrimitiveGameThreadPart(
   }
 #endif
 
-  UMaterialInstanceDynamic* pMaterial;
+  // Move this right now: CreateMaterial may need them!
+  // "Safe" even though loadResult is still used later, because the methods used
+  // during material setup (SetGltfParameterValues, etc.) below do not use these
+  // members.
+  primData.Features = std::move(loadResult.Features);
+  primData.Metadata = std::move(loadResult.Metadata);
+
+  UMaterialInstanceDynamic* pMaterial = nullptr;
+  TSharedPtr<CesiumMeshBuildCallbacks> MeshBuildCallbacks =
+      loadResult.MeshBuildCallbacks.Pin();
   {
     TRACE_CPUPROFILER_EVENT_SCOPE(Cesium::SetupMaterial)
-
-    pMaterial = UMaterialInstanceDynamic::Create(
-        pBaseMaterial,
-        nullptr,
-        ImportedSlotName);
+    ensure(pBaseMaterial);
+    if (MeshBuildCallbacks) {
+      // Possibility to override the material for this primitive
+      pMaterial = MeshBuildCallbacks->CreateMaterial(
+          *pCesiumPrimitive,
+          pBaseMaterial,
+          nullptr,
+          ImportedSlotName);
+    }
+    ensure(pBaseMaterial);
+    if (!pMaterial) {
+      pMaterial = UMaterialInstanceDynamic::Create(
+          pBaseMaterial,
+          nullptr,
+          ImportedSlotName);
+    }
 
     pMaterial->SetFlags(
         RF_Transient | RF_DuplicateTransient | RF_TextExportTransient);
@@ -3148,7 +3187,8 @@ static void loadPrimitiveGameThreadPart(
         pbr,
         pMaterial,
         EMaterialParameterAssociation::GlobalParameter,
-        INDEX_NONE);
+        INDEX_NONE,
+        MeshBuildCallbacks.Get());
     SetWaterParameterValues(
         model,
         loadResult,
@@ -3195,7 +3235,8 @@ static void loadPrimitiveGameThreadPart(
           pbr,
           pMaterial,
           EMaterialParameterAssociation::LayerParameter,
-          0);
+          0,
+          MeshBuildCallbacks.Get());
 
       // Initialize fade uniform to fully visible, in case LOD transitions
       // are off.
@@ -3250,9 +3291,6 @@ static void loadPrimitiveGameThreadPart(
     }
   }
 
-  primData.Features = std::move(loadResult.Features);
-  primData.Metadata = std::move(loadResult.Metadata);
-
   primData.EncodedFeatures = std::move(loadResult.EncodedFeatures);
   primData.EncodedMetadata = std::move(loadResult.EncodedMetadata);
 
@@ -3328,6 +3366,11 @@ static void loadPrimitiveGameThreadPart(
     TRACE_CPUPROFILER_EVENT_SCOPE(Cesium::RegisterComponent)
     pMesh->RegisterComponent();
   }
+
+  // Call the observer callback (if any) once all is done
+  if (MeshBuildCallbacks) {
+    MeshBuildCallbacks->OnMeshConstructed(*pGltf, *pCesiumPrimitive);
+  }
 }
 
 /*static*/ CesiumAsync::Future<UCesiumGltfComponent::CreateOffGameThreadResult>
@@ -3352,7 +3395,7 @@ UCesiumGltfComponent::CreateOffGameThread(
     UMaterialInterface* pBaseTranslucentMaterial,
     UMaterialInterface* pBaseWaterMaterial,
     FCustomDepthParameters CustomDepthParameters,
-    const Cesium3DTilesSelection::Tile& tile,
+    Cesium3DTilesSelection::Tile& tile,
     bool createNavCollision) {
   TRACE_CPUPROFILER_EVENT_SCOPE(Cesium::LoadModel)
 
@@ -3366,6 +3409,7 @@ UCesiumGltfComponent::CreateOffGameThread(
   // }
 
   UCesiumGltfComponent* Gltf = NewObject<UCesiumGltfComponent>(pTilesetActor);
+  Gltf->pTile = &tile;
   Gltf->SetMobility(pTilesetActor->GetRootComponent()->Mobility);
   Gltf->SetFlags(RF_Transient | RF_DuplicateTransient | RF_TextExportTransient);
 
@@ -3394,10 +3438,12 @@ UCesiumGltfComponent::CreateOffGameThread(
     encodeMetadataGameThreadPart(*Gltf->EncodedMetadata_DEPRECATED);
   }
 
+  LoadGltfResult::LoadedPrimitiveResult* pAnyPrimResult = nullptr;
   for (LoadedNodeResult& node : pReal->loadModelResult.nodeResults) {
     if (node.meshResult) {
       for (LoadedPrimitiveResult& primitive :
            node.meshResult->primitiveResults) {
+        pAnyPrimResult = &primitive;
         loadPrimitiveGameThreadPart(
             model,
             Gltf,
@@ -3412,11 +3458,28 @@ UCesiumGltfComponent::CreateOffGameThread(
     }
   }
 
+  if (pAnyPrimResult && pAnyPrimResult->MeshBuildCallbacks.IsValid()) {
+    pAnyPrimResult->MeshBuildCallbacks.Pin()->OnTileConstructed(
+        tile.getTileID());
+    Gltf->VisibilityChangedObserver =
+        [MeshBuildCallbacks = pAnyPrimResult->MeshBuildCallbacks,
+         TileId = tile.getTileID()](bool visible) {
+          if (MeshBuildCallbacks.IsValid())
+            MeshBuildCallbacks.Pin()->OnVisibilityChanged(TileId, visible);
+        };
+  }
+
   Gltf->SetVisibility(false, true);
   Gltf->SetCollisionEnabled(ECollisionEnabled::NoCollision);
   return Gltf;
 }
 
+void UCesiumGltfComponent::OnVisibilityChanged() {
+  USceneComponent::OnVisibilityChanged();
+  if (VisibilityChangedObserver)
+    VisibilityChangedObserver(GetVisibleFlag());
+}
+
 UCesiumGltfComponent::UCesiumGltfComponent() : USceneComponent() {
   // Structure to hold one-time initialization
   struct FConstructorStatics {
@@ -3447,6 +3510,20 @@ UCesiumGltfComponent::UCesiumGltfComponent() : USceneComponent() {
   PrimaryComponentTick.bCanEverTick = false;
 }
 
+const FCesiumModelMetadata& UCesiumGltfComponent::GetModelMetadata() const {
+  return Metadata;
+}
+
+const Cesium3DTilesSelection::TileID& UCesiumGltfComponent::GetTileID() const {
+  return pTile->getTileID();
+}
+
+void UCesiumGltfComponent::SetRenderReady(bool bToggle) {
+  if (pTile) {
+    pTile->setRenderEngineReadiness(bToggle);
+  }
+}
+
 void UCesiumGltfComponent::UpdateTransformFromCesium(
     const glm::dmat4& cesiumToUnrealTransform) {
   for (USceneComponent* pSceneComponent : this->GetAttachChildren()) {

Source/CesiumRuntime/Private/CesiumGltfComponent.h

@@ -5,13 +5,15 @@
 #include "Cesium3DTilesSelection/Tile.h"
 #include "Cesium3DTileset.h"
 #include "CesiumEncodedMetadataUtility.h"
+#include "CesiumLoadedTile.h"
 #include "CesiumModelMetadata.h"
 #include "Components/PrimitiveComponent.h"
 #include "Components/SceneComponent.h"
 #include "CoreMinimal.h"
 #include "CustomDepthParameters.h"
 #include "EncodedFeaturesMetadata.h"
 #include "Interfaces/IHttpRequest.h"
+#include "Templates/Function.h"
 #include <CesiumAsync/SharedFuture.h>
 #include <glm/mat4x4.hpp>
 #include <memory>
@@ -56,7 +58,7 @@ struct FRasterOverlayTile {
 };
 
 UCLASS()
-class UCesiumGltfComponent : public USceneComponent {
+class UCesiumGltfComponent : public USceneComponent, public ICesiumLoadedTile {
   GENERATED_BODY()
 
 public:
@@ -87,7 +89,7 @@ class UCesiumGltfComponent : public USceneComponent {
       UMaterialInterface* BaseTranslucentMaterial,
       UMaterialInterface* BaseWaterMaterial,
       FCustomDepthParameters CustomDepthParameters,
-      const Cesium3DTilesSelection::Tile& tile,
+      Cesium3DTilesSelection::Tile& tile,
       bool createNavCollision);
 
   UCesiumGltfComponent();
@@ -104,6 +106,8 @@ class UCesiumGltfComponent : public USceneComponent {
   UPROPERTY(EditAnywhere, Category = "Rendering")
   FCustomDepthParameters CustomDepthParameters{};
 
+  Cesium3DTilesSelection::Tile* pTile = nullptr;
+
   FCesiumModelMetadata Metadata{};
   EncodedFeaturesMetadata::EncodedModelMetadata EncodedMetadata{};
 
@@ -131,10 +135,18 @@ class UCesiumGltfComponent : public USceneComponent {
   virtual void SetCollisionEnabled(ECollisionEnabled::Type NewType);
 
   virtual void BeginDestroy() override;
+  virtual void OnVisibilityChanged() override;
+
+  // from ICesiumLoadedTile
+  const FCesiumModelMetadata& GetModelMetadata() const override;
+  const Cesium3DTilesSelection::TileID& GetTileID() const override;
+  void SetRenderReady(bool bToggle) override;
 
   void UpdateFade(float fadePercentage, bool fadingIn);
 
 private:
   UPROPERTY()
   UTexture2D* Transparent1x1 = nullptr;
+
+  TFunction<void(bool /*visible*/)> VisibilityChangedObserver;
 };