Improve RasterOverlay doc.

CHANGES.md

@@ -10,6 +10,7 @@
 
 - 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/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,33 @@ class CESIUMRUNTIME_API UCesiumRasterOverlay : public UActorComponent {
   UFUNCTION(BlueprintCallable, Category = "Cesium")
   void SetSubTileCacheBytes(int64 Value);
 
+  /**
+   * Activates this raster overlay, which will add it to (that is: display it
+   * on) the Cesium3DTileset to which the component is attached, if it hasn't
+   * already been added. 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 as 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 call
+   * 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 remove it from (that is: 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;