FBX_SceneProxy.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        FBX_SceneProxy.h (FBX Library, C++)
 *
 * COMMENTS:    
 *
 */

#ifndef __FBX_SCENEPROXY_H_INCLUDED__
#define __FBX_SCENEPROXY_H_INCLUDED__

#include "FBX_API.h"
#include "FBX_SceneProxySupport.h"
#include <GU/GU_DetailHandle.h>
#include <GA/GA_OffsetList.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_VectorTypes.h>
#include <UT/UT_TransformUtil.h>
#include <SYS/SYS_Types.h>


class FBX_ErrorManager;
class GU_Detail;
enum class OP_OrientationMode;

FBX_SCENEPROXY_DECLARE_ID(FBX_NodeID);
FBX_SCENEPROXY_DECLARE_ID(FBX_GeometryID);
FBX_SCENEPROXY_DECLARE_ID(FBX_ClipID);
FBX_SCENEPROXY_DECLARE_ID(FBX_AnimCurveID);
FBX_SCENEPROXY_DECLARE_ID(FBX_AnimLayerID);

FBX_SCENEPROXY_DECLARE_ID(FBX_PropertyID);

template <typename T>
class FBX_Property : public FBX_PropertyID
{
public:
    using value_type = T;

    using FBX_PropertyID::FBX_PropertyID;

private:
    friend class FBX_SceneProxy;
};
using FBX_Property3D = FBX_Property<UT_Vector3D>;

class FBX_AnimCurveModifier;
struct FBX_AxisSystem;

class FBX_API FBX_SceneProxy
{
public:
    struct FBX_API LoadOptions
    {
        bool myConvertUnits = true;
        bool myConvertAxisSystem = true;
        bool myConvertAxisSystemForceYUp = true; /// only used when converting
        bool myImportTemplates = true;
        bool myImportPivots = true;
        bool myImportGlobalSettings = true;
        bool myImportCharacters = true;
        bool myImportConstraints = true;
        bool myImportGobos = true;
        bool myImportShapes = true;
        bool myImportLinks = true;
        bool myImportTextures = true;
        bool myImportModels = true;
        bool myImportAnimations = true;
        bool myImportMaterials = false; /// should also enable
                                        /// myExtractEmbeddedMedia when
                                        /// enabling this.
        bool myExtractEmbeddedData = false; // evil!
    };

    struct FBX_API SaveOptions
    {
        bool myBinary = true;
        bool myAnimationOnly = false;
        bool myEmbedData = false; /// only used when myBinary is true
    };

    /// Construct wrapper around the FBX SDK
    /// @note By default, no scene is set up. You must still call one of load()
    ///       or initInitNewScene().
                    FBX_SceneProxy();

                    ~FBX_SceneProxy();

    /// Initialize a new empty scene
    /// @note Resets mySceneScale/myShouldConvertMaterials to default.
    bool            initNewScene(FBX_ErrorManager& errors);

    /// Load a new scene
    /// @{
    bool            load(const char* path,
                         const LoadOptions& options,
                         FBX_ErrorManager& errors);
    inline bool     load(const char* path,
                         bool convert_units,
                         FBX_ErrorManager& errors)
                    {
                        LoadOptions options;
                        options.myConvertUnits = convert_units;
                        return load(path, options, errors);
                    }
    /// @}

    /// Save current scene. One of initNewScene() or load() must have been
    /// called.
    /// @{
    bool            save(const char* path,
                         FBX_ErrorManager& errors,
                         const SaveOptions& options) const;
    inline bool     save(const char* path,
                         FBX_ErrorManager& errors,
                         bool binary = true,
                         bool animation_only = false) const
                    {
                        SaveOptions options;
                        options.myBinary = binary;
                        options.myAnimationOnly = animation_only;
                        return save(path, errors, options);
                    }
    // @}
    
    /// Stamp FbxDocumentInfo using the current $JOB, $HIPFILE and software
    /// version.
    void            stampDocumentInfo(const char* orig_fbx_filename = nullptr);

    fpreal          globalFrameRate() const;
    void            setGlobalFrameRate(fpreal fps);

    void            getGlobalTimeRange(fpreal& start, fpreal &stop) const;
    void            setGlobalTimeRange(fpreal start, fpreal stop);

    /// Get the scene's current axis system
    FBX_AxisSystem  globalAxisSystem() const;

    /// Set the scene's current axis system
    /// @{
    void            setGlobalAxisSystem(const FBX_AxisSystem& axis_system);
    void            setGlobalAxisSystem(OP_OrientationMode orientation_mode);
    /// @}

    /// Convert the scene to the given axis system
    void            convertAxisSystem(const FBX_AxisSystem& target);

    /// Convert the scene to match Houdini.
    /// Returns true if conversion was done, false if no conversion was needed
    bool            convertToHoudiniAxisSystem();

    /// Return name of node
    const char*     nodeName(FBX_NodeID node) const;

    /// Find first node in scene that has given name
    FBX_NodeID      findNode(const char* name) const;

    /// Return "path" from scene root of node. If node == nullptr, returns
    /// empty string.
    UT_StringHolder nodePath(FBX_NodeID node) const;

    /// Find node in scene by hierarchical path from the scene root.
    /// If path does not begin with a '/' then it returns findNode(path).
    FBX_NodeID      findNodeByPath(const char* path) const;

    int             nodeCount() const;
    FBX_NodeID      node(int i) const;

    FBX_NodeID      rootNode() const;
    FBX_NodeID      parentNode(FBX_NodeID node) const;
    int             childNodeCount(FBX_NodeID node) const;
    FBX_NodeID      childNode(FBX_NodeID node, int i) const;

    enum NodeType
    {   
        eUnknown,           // Unknown
        eNull,              // Null object
        eMarker,            // Mocap marker OR IK/FK effector
        eSkeleton,          // Bone/Joint
        eMesh,              // Geometry
        eNurbs,             // Geometry
        ePatch,             // Geometry
        eCamera,            // Camera
        eCameraStereo,      // Stereo camera
        eCameraSwitcher,    // Switch between child cameras
        eLight,             // Light
        eOpticalReference,  // Mocap marker
        eOpticalMarker,     // Mocap marker OR IK/FK effector
        eNurbsCurve,        // Geometry
        eTrimNurbsSurface,  // Geometry
        eBoundary,          // Geometry
        eNurbsSurface,      // Geometry
        eShape,             // Blendshape
        eLODGroup,          // Group of objects with different levels of detail
        eSubDiv,            // Geometry
        eCachedEffect,      // Particles, fluids, hair, etc. cache
        eLine               // Geometry
    };
    NodeType        nodeType(FBX_NodeID node) const;

    /// Add new FbxNode with new FbxSkeleton attribute as a joint
    FBX_NodeID      createJointNode(const char* name, bool is_root);

    /// Add child to parent. If child already has a parent, first it is removed
    /// from current parent and then added to this one.
    void            nodeAddChild(FBX_NodeID parent, FBX_NodeID child);

    bool            visibility(FBX_NodeID node) const;

    FBX_GeometryID  geometry(FBX_NodeID node) const;
    FBX_NodeID      geometryNode(FBX_GeometryID geometry) const;
    int             geometrySkinDeformerCount(FBX_GeometryID geometry) const;

    /// Count of skin deformers in the file
    int             skinDeformerCount() const;

    /// Get geometry associated with skin deformer i
    /// @note There might no geometry attached and this will return nullptr
    FBX_GeometryID  skinDeformerGeometry(int i) const;

    /// Convert geometry into GU_Detail, with skin deformers converted into
    /// a boneCapture attribute. If world_xform is given, the result including
    /// the transforms within boneCapture will have this baked into it.
    /// When add_unused_joints is true, add ancestor joints for any captured
    /// joints will also be added to the boneCapture attribute with identity
    /// transforsm.
    bool            convertGeometry(
                        GU_Detail& detail,
                        FBX_GeometryID geometry,
                        FBX_ErrorManager& errors,
                        bool add_unused_joints,
                        const UT_Matrix4D* world_xform = nullptr) const;

    enum class SkinningType
    {
        eRigid,
        eLinear,
        eDualQuaternion,
        eBlend
    };
    /// Returns the skinning type for the i'th skin deformer in the geometry.
    SkinningType geometrySkinDeformerType(FBX_GeometryID geometry, int i) const;

    /// Returns the number of blend shape deformers for the geometry.
    int             blendshapeCount(FBX_GeometryID geometry) const;
    /// Returns the number of channels for the i'th blend shape deformer.
    int             blendshapeChannelCount(
                        FBX_GeometryID geometry, int blendshape_idx) const;
    /// Returns the name of the specified blendshape channel.
    UT_StringHolder blendshapeChannelName(FBX_GeometryID geometry,
                        int blendshape_idx, int channel_idx) const;

    /// Returns the geometry, name, and weight (multiplied by 0.01) for each of
    /// the channel's target shapes. Multiple targets imply that there are
    /// in-between shapes, and the shapes are sorted by weight in ascending
    /// order.
    void            blendShapeChannelTargets(
                        FBX_GeometryID geometry,
                        int blendshape_idx,
                        int channel_idx,
                        UT_Array<GU_DetailHandle>& details,
                        UT_StringArray& names,
                        UT_Array<fpreal>& weights,
                        const UT_Matrix4D* world_xform = nullptr) const;

    /// Returns curve for the blend shape channel's values.
    /// @note Result might be null for non-animated blendshapes.
    /// @{
    FBX_AnimCurveID blendshapeChannelCurve(
                        FBX_GeometryID geometry,
                        int blendshape_idx,
                        int channel_idx) const;
    FBX_AnimCurveID blendshapeChannelCurve(
                        FBX_GeometryID geometry,
                        int blendshape_idx,
                        int channel_idx,
                        bool create_if_needed);
    /// @}

    /// Evaluate an animation curve at the given time
    fpreal          animCurveEval(
                        FBX_AnimCurveID curve, fpreal time_seconds) const;

    /// Number of keys in anim curve
    int             animCurveKeyCount(FBX_AnimCurveID curve) const;

    /// Get the time range of the anim curve
    void            getAnimCurveTimeInterval(
                        FBX_AnimCurveID curve,
                        fpreal &start, fpreal &end) const;

    /// Local translation property of node
    FBX_Property3D  nodeLocalTranslate(FBX_NodeID node) const;

    /// Local rotation property of node
    FBX_Property3D  nodeLocalRotate(FBX_NodeID node) const;

    /// Local scale property of node
    FBX_Property3D  nodeLocalScale(FBX_NodeID node) const;

    /// Local pre-rotation property of node. Should only be used when
    /// nodeIsRotationActive() is true.
    FBX_Property3D  nodeLocalPreRotation(FBX_NodeID node) const;

    /// When nodeIsRotationActive() is false, then these node properties are
    /// ignored from the FBX file:
    ///   rotation order, pivots, pre/post rotation values, rotation limits
    bool            nodeIsRotationActive(FBX_NodeID node) const;

    /// Return the transform order for given node. For FBX, we always return a
    /// transform order of SRT, so really only the rotation order is pertinent
    /// here.
    /// @note Returns a default value when !nodeIsRotationActive()
    UT_XformOrder   nodeTransformOrder(FBX_NodeID node) const;

    /// Return the rotation pivot for given node. 
    /// @note Returns a default value when !nodeIsRotationActive()
    UT_Vector3D     nodeRotationPivot(FBX_NodeID node) const;

    int             animLayerCount(FBX_ClipID clip) const;
    FBX_AnimLayerID animLayer(FBX_ClipID clip, int i) const;

    /// Create a new animation layer. If given clip, the layer is added to it.
    FBX_AnimLayerID createAnimLayer(const char* name,
                                    FBX_ClipID clip = FBX_ClipID{});

    /// Destroy give animation layer. If recurse_unused is true, then
    /// recursively destroy all unused dst objects as a result.
    void            destroyAnimLayer(FBX_AnimLayerID layer,
                                     bool recurse_unused = false);

    /// Add/remove a layer to clip as a src object
    /// @{
    void            addAnimLayer(FBX_ClipID clip, FBX_AnimLayerID layer);
    void            removeAnimLayer(FBX_ClipID clip, FBX_AnimLayerID layer);
    /// @}

    /// Return src object count of layer
    int             animLayerSrcCount(FBX_AnimLayerID layer) const;

    /// Return animation curve attached to property
    FBX_AnimCurveID propertyAnimCurve(
                        FBX_PropertyID property,
                        FBX_AnimLayerID layer,
                        int component,
                        bool create = false);

    /// Evaluate animated value from property
    /// @{
    fpreal          propertyEvalFloat(
                        FBX_PropertyID property,
                        fpreal time_seconds);
    UT_Vector3R     propertyEvalVector(
                        FBX_Property3D property,
                        fpreal time_seconds);
    /// @}

    /// Set non-animated value on property
    /// @{
    void            propertySetFloat(
                        FBX_PropertyID property,
                        fpreal value);
    void            propertySetVector(
                        FBX_PropertyID property,
                        const UT_Vector3R& vector);
    /// @}

    /// Scene scale to convert from internal FBX scene. Determined by load()
    /// This is currently only used by nodeGlobalTransform()
    double          sceneScale() const;

    /// Set the scene scale
    void            setSceneScale(fpreal scale);

    /// Return a node's global transform, scaled by sceneScale()
    UT_Matrix4D     nodeGlobalTransform(
                        FBX_NodeID node, fpreal time_seconds) const;

    /// Get a node's local transform at given time.
    /// @note This transform is NOT scaled by sceneScale()
    UT_Matrix4D     nodeLocalTransform(
                        FBX_NodeID node, fpreal time_seconds) const;

    /// Return global transform without animation, scaled by sceneScale()
    UT_Matrix4D     nodeGlobalRestTransform(FBX_NodeID node) const;

    /// Access node's local transform without animation
    /// @note This transform is NOT scaled by sceneScale()
    /// @{
    UT_Matrix4D     nodeLocalRestTransform(FBX_NodeID node) const;

    /// Set a node's local transform without anim
    void            setNodeLocalRestTransform(
                        FBX_NodeID node,
                        const UT_Matrix4D& local);
    /// @}

    /// Get a node's geometric transform. Returns false if there is none.
    /// A geometric transform is a transform that is only applied to the node's
    /// geometry and is not part of its global transform.
    /// @note This transform is NOT scaled by sceneScale()
    bool            nodeGeometricTransform(
                        FBX_NodeID node, UT_Matrix4D& transform) const;

    /// Remove all animation on the transform properties of given node
    void            removeNodeAnimation(FBX_NodeID node);

    /// Compute a scene scale needed convert transforms from
    /// nodeGlobalTransform() to the Houdini unit length.
    /// This will be 1.0 if the file was loaded with convert_units=true.
    double          computeConversionFactor() const;
    
    UT_ScaleInheritanceMode
                    nodeScaleInheritanceMode(FBX_NodeID node) const;

    /// Set the scale inheritance mode for a node. Note that FBX does NOT
    /// support everything, and only these modes:
    ///     DEFAULT, OFFSET_ONLY, and OFFSET_AND_SCALE
    /// If its given an invalid type, it will map to the next closest thing
    void            setNodeScaleInheritanceMode(
                        FBX_NodeID node, UT_ScaleInheritanceMode inherit);

    int             clipCount() const;
    FBX_ClipID      clip(int i) const;

    FBX_ClipID      findClip(const char* name) const;
    const char*     clipName(FBX_ClipID clip) const;

    void            setActiveClip(FBX_ClipID clip);
    FBX_ClipID      activeClip() const;

    FBX_ClipID      createClip(const char* name);

    /// Get/set the *inclusive* time range for the given clip in seconds
    /// @{
    void            getClipTimeRange(
                        FBX_ClipID clip, fpreal& start, fpreal &stop) const;
    void            setClipTimeRange(
                        FBX_ClipID clip, fpreal start, fpreal stop);
    /// @}

    struct JointInfo
    {
        FBX_NodeID myNode;
        UT_Matrix4D myTransform;
    };
    using JointInfoMap = UT_ArrayStringMap<JointInfo>;
    struct SkinningInfo
    {
        SkinningType myType;
        JointInfoMap myCapturePose;
    };

    /// Export geometry to FBX scene, with automatic handling of shapes
    /// partitioned by name and/or path primitive attributes. If the nodes
    /// already exist, then their geometry will be destroyed and recreated.
    /// In order to export them with an identity global transform, a time is
    /// needed to evaluate its parent node. If not specified, the time at 0
    /// seconds will be used.
    /// @warn Currently, everything is first converted to polygons.
    /// @{
    bool            exportGeometry(
                        UT_Array<FBX_NodeID>& exported_nodes,
                        const UT_Matrix4D& parent_xform,
                        const GU_Detail& geo,
                        const SkinningInfo* skinning_info,
                        FBX_ErrorManager& errors);
    bool            exportGeometry(
                        UT_Array<FBX_NodeID>& exported_nodes,
                        fpreal time_seconds,
                        const UT_Matrix4D& parent_xform,
                        const GU_Detail& geo,
                        const SkinningInfo* skinning_info,
                        FBX_ErrorManager& errors);
    /// @}

    /// Iterates over a node's user properties.
    class FBX_API PropertyIterator
    {
    public:
        PropertyIterator(FBX_NodeID node);
        ~PropertyIterator();

        bool isValid();
        void advance();

        const char *getName() const;
        fpreal evalFloat(fpreal time_seconds) const;

        enum DataType
        {
            eUndefined,
            eChar,
            eUChar,
            eShort,
            eUShort,
            eUInt,
            eLongLong,
            eULongLong,
            eHalfFloat,
            eBool,
            eInt,
            eFloat,
            eDouble,
            eDouble2,
            eDouble3,
            eDouble4,
            eDouble4x4,
            eEnum,
            eString,
            eTime,
            eReference,
            eBlob,
            eDistance,
            eDateTime
        };

        DataType getDataType() const;

    private:
        struct Impl;
        UT_UniquePtr<Impl> myImpl;
    };

private:
    template <typename FBX_T, typename ID_T>
    static inline FBX_T * castID(ID_T id);

private:
    struct Impl;
    UT_UniquePtr<Impl> myImpl;

    friend FBX_AnimCurveModifier;
};

enum class FBX_KeyInterp
{
    CONSTANT,
    LINEAR,
    CUBIC
};

class FBX_API FBX_AnimCurveModifier
{
public:
                    FBX_AnimCurveModifier() = default;
                    FBX_AnimCurveModifier(FBX_AnimCurveID curve);
                    ~FBX_AnimCurveModifier();

    void            reset(FBX_AnimCurveID curve);

    void            clearKeys();
    int             addKey(fpreal time_seconds);

    void            setKeyInterpolation(int key_i, FBX_KeyInterp interp);
    FBX_KeyInterp   keyInterpolation(int key_i) const;

    void            setKeyValue(int key_i, fpreal val);
    fpreal          keyValue(int key_i) const;

    FBX_AnimCurveID curve() const { return myCurve; }
    int             lastKeyIndex() const { return myLastKeyIndex; }

private:
    template <typename FBX_T, typename ID_T>
    static inline FBX_T * castID(ID_T id)
        { return FBX_SceneProxy::castID<FBX_T,ID_T>(id); }

private:
    FBX_AnimCurveID myCurve         = FBX_AnimCurveID{};
    int             myLastKeyIndex  = 0;
};

struct FBX_API FBX_AxisSystem
{
    enum class UpVector
    {
        XAxis,
        YAxis,
        ZAxis
    };
    enum class FrontVector
    {
        ParityEven,
        ParityOdd
    };
    enum class CoordSystem
    {
        RightHanded,
        LeftHanded
    };

    UpVector    myUpVector;
    FrontVector myFrontVector;
    CoordSystem myCoordSystem;

    bool operator==(const FBX_AxisSystem &x) const
    {
        return myUpVector == x.myUpVector &&
               myFrontVector == x.myFrontVector &&
               myCoordSystem == x.myCoordSystem;
    }
    bool operator!=(const FBX_AxisSystem &x) const
    {
        return !(*this == x);
    }
};

namespace UT
{
    template <>
    struct DefaultClearer<FBX_SceneProxy::JointInfo>
    {
        using T = FBX_SceneProxy::JointInfo;
        using D = DefaultClearer<FBX_NodeID>;
        static void clear(T& v) { D::clear(v.myNode) ; }
        static bool isClear(const T& v) { return D::isClear(v.myNode); }
        static void clearConstruct(T* p) { D::clear(p->myNode); }
        static const bool clearNeedsDestruction = false;
    };
}

#endif // __FBX_SCENEPROXY_H_INCLUDED__