Merge pull request #1503 from CesiumGS/overlay-tweaks

Raster overlay lifecycle and doc improvements

CHANGES.md

@@ -5,11 +5,13 @@
 ##### Additions :tada:
 
 - Added universal (Intel and Apple Silicon) binaries for Unreal Engine 5.2. Unreal Engine 5.3 and 5.4 already had universal binaries.
+- Raster overlays now have `bAllowAnyoneToDestroyMe` set to true by default. This allows them to be dynamically removed and destroyed at runtime via the Blueprint `Destroy Component` function called from anywhere, including Level Blueprints. Previously, attempting to delete a raster overlay from outside the Actor would result in an error.
 
 ##### Fixes :wrench:
 
 - Fixed a bug introduced in the previous release that caused instanced tilesets to render incorrectly.
 - Debug sections are no longer compressed on Linux and Android, improving compatibility.
+- Fixed a bug where calling `Refresh` on a `CesiumRasterOverlay` would cause the overlay to appear on the Cesium3DTileset, even if inactive.
 
 ### v2.7.1 - 2024-08-01
 

Source/CesiumRuntime/Private/CesiumRasterOverlay.cpp

@@ -20,7 +20,11 @@ UCesiumRasterOverlay::UCesiumRasterOverlay()
   // don't need them.
   PrimaryComponentTick.bCanEverTick = false;
 
-  // ...
+  // Allow DestroyComponent to be called from Blueprints by anyone. Without
+  // this, only the Actor (Cesium3DTileset) itself can destroy raster overlays.
+  // That's really annoying because it's fairly common to dynamically add/remove
+  // overlays at runtime.
+  bAllowAnyoneToDestroyMe = true;
 }
 
 #if WITH_EDITOR
@@ -127,7 +131,9 @@ void UCesiumRasterOverlay::RemoveFromTileset() {
 
 void UCesiumRasterOverlay::Refresh() {
   this->RemoveFromTileset();
-  this->AddToTileset();
+  if (this->IsActive()) {
+    this->AddToTileset();
+  }
 }
 
 double UCesiumRasterOverlay::GetMaximumScreenSpaceError() const {

Source/CesiumRuntime/Public/CesiumRasterOverlay.h

@@ -78,25 +78,37 @@ class CESIUMRUNTIME_API UCesiumRasterOverlay : public UActorComponent {
   UCesiumRasterOverlay();
 
   /**
-   * Adds this raster overlay to its owning Cesium 3D Tileset Actor. If the
-   * overlay is already added or if this component's Owner is not a Cesium 3D
-   * Tileset, this method does nothing.
+   * Displays this raster overlay on its owning Cesium 3D Tileset Actor, without
+   * changing its activation state. It is usually better to call Activate
+   * rather than this function, in order to ensure that the component is also
+   * activated. Otherwise, if the Cesium3DTileset is reloaded for any reason,
+   * this overlay will no longer be shown.
+   *
+   * If the overlay is already added or if this component's Owner is not a
+   * Cesium 3D Tileset, this method does nothing.
    */
   UFUNCTION(BlueprintCallable, Category = "Cesium")
   void AddToTileset();
 
   /**
-   * Removes this raster overlay from its owning Cesium 3D Tileset Actor. If the
-   * overlay is not yet added or if this component's Owner is not a Cesium 3D
-   * Tileset, this method does nothing.
+   * Stops displaying this raster overlay on its owning Cesium 3D Tileset Actor.
+   * It is usually better to call Deactivate rather than this function, in order
+   * to ensure that the component is also deactivated. Otherwise, if the
+   * component remains active and the Cesium3DTileset is reloaded for any
+   * reason, this overlay will reappear.
+   *
+   * If the overlay is not yet added or if this component's Owner is not a
+   * Cesium 3D Tileset, this method does nothing.
    */
   UFUNCTION(BlueprintCallable, Category = "Cesium")
   void RemoveFromTileset();
 
   /**
    * Refreshes this overlay by removing from its owning Cesium 3D Tileset Actor
    * and re-adding it. If this component's Owner is not a Cesium 3D Tileset
-   * Actor, this method does nothing.
+   * Actor, this method does nothing. If this component is not active, the
+   * overlay will be removed from the Cesium3DTileset if already present but not
+   * re-added.
    */
   UFUNCTION(BlueprintCallable, Category = "Cesium")
   void Refresh();
@@ -125,8 +137,32 @@ class CESIUMRUNTIME_API UCesiumRasterOverlay : public UActorComponent {
   UFUNCTION(BlueprintCallable, Category = "Cesium")
   void SetSubTileCacheBytes(int64 Value);
 
+  /**
+   * Activates this raster overlay, which will display it on the Cesium3DTileset
+   * to which the component is attached, if it isn't already displayed. The
+   * overlay will continue to be shown on the tileset until it is deactivated.
+   *
+   * If the overlay is already displayed on the Cesium3DTileset, calling this
+   * function will not cause it to pick up any new values for properties that
+   * have been modified since it was added. To do that, call Refresh.
+   *
+   * If you created this overlay component via Blueprints, consider setting the
+   * "Auto Activate" property to false on the "Add Component" node and calling
+   * Activate after setting all the desired properties. This will avoid the need
+   * to call Refresh, and will ensure the overlay is not loaded multiple times.
+   *
+   * @param bReset  Whether the activation should happen even if ShouldActivate
+   * returns false.
+   */
   virtual void Activate(bool bReset) override;
+
+  /**
+   * Deactivates this raster overlay. This will stop displaying it on the
+   * Cesium3DTileset to which the component is attached. The overlay will not be
+   * shown again until the component is re-activated.
+   */
   virtual void Deactivate() override;
+
   virtual void OnComponentDestroyed(bool bDestroyingHierarchy) override;
   virtual bool IsReadyForFinishDestroy() override;
 
@@ -178,12 +214,12 @@ class CESIUMRUNTIME_API UCesiumRasterOverlay : public UActorComponent {
   /**
    * The maximum number of bytes to use to cache sub-tiles in memory.
    *
-   * This is used by provider types, that have an underlying tiling
-   * scheme that may not align with the tiling scheme of the geometry tiles on
-   * which the raster overlay tiles are draped. Because a single sub-tile may
-   * overlap multiple geometry tiles, it is useful to cache loaded sub-tiles
-   * in memory in case they're needed again soon. This property controls the
-   * maximum size of that cache.
+   * This is used by provider types that have an underlying tiling scheme that
+   * may not align with the tiling scheme of the geometry tiles on which the
+   * raster overlay tiles are draped. Because a single sub-tile may overlap
+   * multiple geometry tiles, it is useful to cache loaded sub-tiles in memory
+   * in case they're needed again soon. This property controls the maximum size
+   * of that cache.
    */
   UPROPERTY(
       EditAnywhere,