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 <OP/OP_Director.h>
#include <UT/UT_StringArray.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;

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!
    };

                    FBX_SceneProxy();
                    ~FBX_SceneProxy();

    bool            load(const char* path,
                         const LoadOptions& options,
                         FBX_ErrorManager& errors);
    bool            load(const char* path,
                         bool convert_units,
                         FBX_ErrorManager& errors)
                    {
                        LoadOptions options;
                        options.myConvertUnits = convert_units;
                        return load(path, options, errors);
                    }

    bool            save(const char* path,
                         FBX_ErrorManager& errors,
                         bool binary = true,
                         bool animation_only = false) const;

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

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

    /// 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_Director::OrientationMode orientation_mode);
    /// @}

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

    const char*     nodeName(FBX_NodeID node) const;
    FBX_NodeID      findNode(const char* name) 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;

    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;

    int             skinDeformerCount() const;
    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 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;

    /// Returns curve for the blend shape channel's values.
    FBX_AnimCurveID blendshapeChannelCurve(FBX_GeometryID geometry,
                        int blendshape_idx, int channel_idx) const;

    /// 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;

    FBX_AnimCurveID propertyAnimCurve(
                        FBX_PropertyID property,
                        FBX_AnimLayerID layer,
                        int component,
                        bool create = false);

    fpreal          propertyEvalFloat(
                        FBX_PropertyID property,
                        fpreal time_seconds);
    UT_Vector3R     propertyEvalVector(
                        FBX_Property3D property,
                        fpreal time_seconds);

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

    /// 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;

    /// 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;

    /// 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;

    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);
    /// @}

    /// 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);
    }
};

#endif // __FBX_SCENEPROXY_H_INCLUDED__