more documentation for FilamentController

lib/filament_controller.dart

@@ -45,7 +45,8 @@ abstract class FilamentController {
   void setPixelRatio(double ratio);
 
   ///
-  /// Destroys the viewer and all backing textures. You can leave the FilamentWidget in the hierarchy after this is called, but
+  /// Destroys the viewer and all backing textures. You can leave the FilamentWidget in the hierarchy after this is called, but you will need to manually call [createViewer] to
+  ///
   Future destroy();
 
   ///
@@ -59,9 +60,10 @@ abstract class FilamentController {
   Future destroyTexture();
 
   ///
-  /// You can insert a Filament viewport into the Flutter rendering hierarchy as follows:
+  /// Called by [FilamentWidget]; you generally will not need to call this yourself.
+  /// To recap, you can create a viewport is created in the Flutter rendering hierarchy by:
   /// 1) Create a FilamentController
-  /// 2) Insert a FilamentWidget into the rendering tree, passing this instance of FilamentController
+  /// 2) Insert a FilamentWidget into the rendering tree, passing your FilamentController
   /// 3) Initially, the FilamentWidget will only contain an empty Container (by default, with a solid red background).
   ///    This widget will render a single frame to get its actual size, then will itself call [createViewer]. You do not need to call [createViewer] yourself.
   ///    This will dispatch a request to the native platform to create a hardware texture (Metal on iOS, OpenGL on Linux, GLES on Android and Windows) and a FilamentViewer (the main interface for manipulating the 3D scene) .
@@ -70,26 +72,68 @@ abstract class FilamentController {
   /// If you need to wait until a FilamentViewer has been created, [await] the [isReadyForScene] Future.
   ///
   Future createViewer(int width, int height);
+
+  ///
+  /// Resize the viewport & backing texture.
+  /// This is called by FilamentWidget; you shouldn't need to invoke this manually.
+  ///
   Future resize(int width, int height, {double scaleFactor = 1.0});
 
-  Future clearBackgroundImage();
+  ///
+  /// Set the background image to [path] (which should have a file extension .png, .jpg, or .ktx).
+  /// This will be rendered at the maximum depth (i.e. behind all other objects including the skybox).
+  /// If [fillHeight] is false, the image will be rendered at its original size. Note this may cause issues with pixel density so be sure to specify the correct resolution
+  /// If [fillHeight] is true, the image will be stretched/compressed to fit the height of the viewport.
+  ///
   Future setBackgroundImage(String path, {bool fillHeight = false});
 
-  Future setBackgroundColor(Color color);
+  ///
+  /// Moves the background image to the relative offset from the origin (bottom-left) specified by [x] and [y].
+  /// If [clamp] is true, the image cannot be positioned outside the bounds of the viewport.
+  ///
   Future setBackgroundImagePosition(double x, double y, {bool clamp = false});
+
+  ///
+  /// Removes the background image.
+  ///
+  Future clearBackgroundImage();
+
+  ///
+  /// Sets the color for the background plane (positioned at the maximum depth, i.e. behind all other objects including the skybox).
+  ///
+  Future setBackgroundColor(Color color);
+
+  ///
+  /// Load a skybox from [skyboxPath] (which must be a .ktx file)
+  ///
   Future loadSkybox(String skyboxPath);
-  Future loadIbl(String lightingPath, {double intensity = 30000});
+
+  ///
+  /// Removes the skybox from the scene.
+  ///
   Future removeSkybox();
+
+  ///
+  /// Loads an image-based light from the specified path at the given intensity.
+  /// Only one IBL can be active at any given time; if an IBL has already been loaded, it will be replaced.
+  ///
+  Future loadIbl(String lightingPath, {double intensity = 30000});
+
+  ///
+  /// Removes the image-based light from the scene.
+  ///
   Future removeIbl();
 
-  // copied from LightManager.h
+  ///
-  //  enum class Type : uint8_t {
+  /// Adds a dynamic light to the scene.
-  //       SUN,            //!< Directional light that also draws a sun's disk in the sky.
+  /// copied from filament LightManager.h
-  //       DIRECTIONAL,    //!< Directional light, emits light in a given direction.
+  ///  enum class Type : uint8_t {
-  //       POINT,          //!< Point light, emits light from a position, in all directions.
+  ///       SUN,            //!< Directional light that also draws a sun's disk in the sky.
-  //       FOCUSED_SPOT,   //!< Physically correct spot light.
+  ///       DIRECTIONAL,    //!< Directional light, emits light in a given direction.
-  //       SPOT,           //!< Spot light with coupling of outer cone and illumination disabled.
+  ///       POINT,          //!< Point light, emits light from a position, in all directions.
-  //   };
+  ///       FOCUSED_SPOT,   //!< Physically correct spot light.
+  ///       SPOT,           //!< Spot light with coupling of outer cone and illumination disabled.
+  ///   };
   Future<FilamentEntity> addLight(
       int type,
       double colour,
@@ -147,17 +191,18 @@ abstract class FilamentController {
   /// Set the weights for all morph targets under node [meshName] in [asset] to [weights].
   ///
   Future setMorphTargetWeights(
-      FilamentEntity asset, String meshName, List<double> weights);
+      FilamentEntity entity, String meshName, List<double> weights);
 
   Future<List<String>> getMorphTargetNames(
-      FilamentEntity asset, String meshName);
+      FilamentEntity entity, String meshName);
 
-  Future<List<String>> getAnimationNames(FilamentEntity asset);
+  Future<List<String>> getAnimationNames(FilamentEntity entity);
 
   ///
   /// Returns the length (in seconds) of the animation at the given index.
   ///
-  Future<double> getAnimationDuration(FilamentEntity asset, int animationIndex);
+  Future<double> getAnimationDuration(
+      FilamentEntity entity, int animationIndex);
 
   ///
   /// Create/start a dynamic morph target animation for [asset].
@@ -166,7 +211,7 @@ abstract class FilamentController {
   /// Each frame is [numWeights] in length, and each entry is the weight to be applied to the morph target located at that index in the mesh primitive at that frame.
   ///
   Future setMorphAnimationData(
-      FilamentEntity asset, MorphAnimationData animation);
+      FilamentEntity entity, MorphAnimationData animation);
 
   ///
   /// Animates morph target weights/bone transforms (where each frame requires a duration of [frameLengthInMs].
@@ -174,13 +219,13 @@ abstract class FilamentController {
   /// Each frame is [numWeights] in length, and each entry is the weight to be applied to the morph target located at that index in the mesh primitive at that frame.
   /// for now we only allow animating a single bone (though multiple skinned targets are supported)
   ///
-  Future setBoneAnimation(FilamentEntity asset, BoneAnimationData animation);
+  Future setBoneAnimation(FilamentEntity entity, BoneAnimationData animation);
 
   ///
   /// Removes/destroys the specified entity from the scene.
   /// [asset] will no longer be a valid handle after this method is called; ensure you immediately discard all references once this method is complete.
   ///
-  Future removeAsset(FilamentEntity asset);
+  Future removeAsset(FilamentEntity entity);
 
   ///
   /// Removes/destroys all renderable entities from the scene (including cameras).
@@ -206,18 +251,19 @@ abstract class FilamentController {
   ///
   /// Schedules the glTF animation at [index] in [asset] to start playing on the next frame.
   ///
-  Future playAnimation(FilamentEntity asset, int index,
+  Future playAnimation(FilamentEntity entity, int index,
       {bool loop = false,
       bool reverse = false,
       bool replaceActive = true,
       double crossfade = 0.0});
-  Future setAnimationFrame(FilamentEntity asset, int index, int animationFrame);
+  Future setAnimationFrame(
-  Future stopAnimation(FilamentEntity asset, int animationIndex);
+      FilamentEntity entity, int index, int animationFrame);
+  Future stopAnimation(FilamentEntity entity, int animationIndex);
 
   ///
   /// Sets the current scene camera to the glTF camera under [name] in [asset].
   ///
-  Future setCamera(FilamentEntity asset, String? name);
+  Future setCamera(FilamentEntity entity, String? name);
 
   ///
   /// Sets the tone mapping (requires postprocessing).
@@ -235,7 +281,7 @@ abstract class FilamentController {
   ///
   /// Repositions the camera to the last vertex of the bounding box of [asset], looking at the penultimate vertex.
   ///
-  Future moveCameraToAsset(FilamentEntity asset);
+  Future moveCameraToAsset(FilamentEntity entity);
 
   ///
   /// Enables/disables frustum culling. Currently we don't expose a method for manipulating the camera projection/culling matrices so this is your only option to deal with unwanted near/far clipping.
@@ -247,27 +293,39 @@ abstract class FilamentController {
   Future setCameraModelMatrix(List<double> matrix);
 
   Future setMaterialColor(
-      FilamentEntity asset, String meshName, int materialIndex, Color color);
+      FilamentEntity entity, String meshName, int materialIndex, Color color);
 
   ///
   /// Scales [asset] up/down so it fits within a unit cube.
   ///
-  Future transformToUnitCube(FilamentEntity asset);
+  Future transformToUnitCube(FilamentEntity entity);
 
   ///
   /// Sets the world space position for [asset] to the given coordinates.
   ///
-  Future setPosition(FilamentEntity asset, double x, double y, double z);
+  Future setPosition(FilamentEntity entity, double x, double y, double z);
 
   ///
   /// Enable/disable postprocessing.
   ///
   Future setPostProcessing(bool enabled);
-  Future setScale(FilamentEntity asset, double scale);
+
+  ///
+  /// Sets the scale for the given entity.
+  ///
+  Future setScale(FilamentEntity entity, double scale);
   Future setRotation(
-      FilamentEntity asset, double rads, double x, double y, double z);
+      FilamentEntity entity, double rads, double x, double y, double z);
-  Future hide(FilamentEntity asset, String meshName);
+
-  Future reveal(FilamentEntity asset, String meshName);
+  ///
+  /// Reveal the node [meshName] under [entity]. Only applicable if [hide] had previously been called; this is a no-op otherwise.
+  ///
+  Future reveal(FilamentEntity entity, String meshName);
+
+  ///
+  /// Hide the node [meshName] under [entity]. The node is still loaded, but is no longer being rendered into the scene. Call [reveal] to re-commence rendering.
+  ///
+  Future hide(FilamentEntity entity, String meshName);
 
   ///
   /// Used to select the entity in the scene at the given viewport coordinates.