From d65567258765146d657aab8250ad60563e872036 Mon Sep 17 00:00:00 2001 From: Nick Fisher Date: Fri, 13 Oct 2023 10:14:43 +0800 Subject: [PATCH] more documentation for FilamentController --- lib/filament_controller.dart | 124 +++++++++++++++++++++++++---------- 1 file changed, 91 insertions(+), 33 deletions(-) diff --git a/lib/filament_controller.dart b/lib/filament_controller.dart index 1dc3f226..93f82946 100644 --- a/lib/filament_controller.dart +++ b/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 { - // SUN, //!< Directional light that also draws a sun's disk in the sky. - // DIRECTIONAL, //!< Directional light, emits light in a given direction. - // 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. - // }; + /// + /// Adds a dynamic light to the scene. + /// copied from filament LightManager.h + /// enum class Type : uint8_t { + /// SUN, //!< Directional light that also draws a sun's disk in the sky. + /// DIRECTIONAL, //!< Directional light, emits light in a given direction. + /// 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 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 weights); + FilamentEntity entity, String meshName, List weights); Future> getMorphTargetNames( - FilamentEntity asset, String meshName); + FilamentEntity entity, String meshName); - Future> getAnimationNames(FilamentEntity asset); + Future> getAnimationNames(FilamentEntity entity); /// /// Returns the length (in seconds) of the animation at the given index. /// - Future getAnimationDuration(FilamentEntity asset, int animationIndex); + Future 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 stopAnimation(FilamentEntity asset, int animationIndex); + Future setAnimationFrame( + 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 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); - Future hide(FilamentEntity asset, String meshName); - Future reveal(FilamentEntity asset, String meshName); + FilamentEntity entity, double rads, double x, double y, double z); + + /// + /// 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.