GU_LinearSkinDeformer.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:        GU_LinearSkinDeformer.h (GU Library, C++)
 *
 * COMMENTS:
 */

#ifndef __GU_LINEARSKINDEFORMER_H_INCLUDED__
#define __GU_LINEARSKINDEFORMER_H_INCLUDED__

#include "GU_API.h"
#include "GU_Detail.h"
#include <GEO/GEO_AttributeIndexPairs.h>
#include <GA/GA_Range.h>
#include <UT/UT_Array.h>
#include <UT/UT_Assert.h>
#include <UT/UT_DualQuaternion.h>
#include <UT/UT_IteratorRange.h>
#include <UT/UT_Matrix3.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Quaternion.h>
#include <UT/UT_TaskGroup.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_VectorTypes.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_StaticAssert.h>
#include <SYS/SYS_TypeDecorate.h>
#include <SYS/SYS_Types.h>

#include <stddef.h>



class GA_Attribute;
class GA_ROAttributeRef;
class GEO_AttributeCapturePath;
class GU_Detail;
class GU_LinearSkinDeformer;

struct GU_CaptureElement
{
    GU_CaptureElement() { }
    GU_CaptureElement(int i, float w) : myI(i), myW(w) { }

    bool operator>(const GU_CaptureElement& elem) const
    {
        return (myW > elem.myW);
    }

    int     myI;
    float   myW;
};
SYS_DECLARE_IS_POD(GU_CaptureElement)
typedef UT_Array<GU_CaptureElement> GU_CaptureElementArray;


template <typename T>
struct GU_DualQuatXformT
{
    using ThisType = GU_DualQuatXformT<T>;

    SYS_FORCE_INLINE    GU_DualQuatXformT() = default;
    SYS_FORCE_INLINE    GU_DualQuatXformT(const ThisType&) = default;
    SYS_FORCE_INLINE    GU_DualQuatXformT(ThisType&&) = default;
    SYS_FORCE_INLINE
    ThisType&           operator=(const GU_DualQuatXformT<T>&) = default;
    SYS_FORCE_INLINE
    ThisType&           operator=(GU_DualQuatXformT<T>&&) = default;

    SYS_FORCE_INLINE
    UT_Vector3T<T> transform(const UT_Vector3T<T>& src) const
    {
        UT_Vector3T<T> dst;
        myDQ.transform(src * myStretch, dst);
        return dst;
    }
    SYS_FORCE_INLINE
    UT_Vector3T<T> transformTransposed(const UT_Vector3T<T>& src) const
    {
        UT_Vector3T<T> dst;
        myDQ.transform(src, dst);
        dst *= myStretch;
        return dst;
    }
    SYS_FORCE_INLINE
    UT_Matrix3T<T> transform(const UT_Matrix3T<T>& src) const
    {
        UT_Matrix3T<T> dst;
        myDQ.getRotation().getRotationMatrix(dst);
        dst.leftMult(src * myStretch);
        return dst;
    }
    SYS_FORCE_INLINE
    UT_Matrix4T<T> transform(const UT_Matrix4T<T>& src) const
    {
        UT_Matrix4T<T> dst = src;
        dst *= myStretch;
        dst *= myDQ.convertToXform();
        return dst;
    }
    SYS_FORCE_INLINE
    UT_Vector3T<T> rotate(const UT_Vector3T<T>& src) const
    {
        UT_Vector3T<T> dst;
        myDQ.rotate(src, dst);
        return dst;
    }
    SYS_FORCE_INLINE
    UT_QuaternionT<T> rotate(const UT_QuaternionT<T>& src) const
    {
        return src * myDQ.getRotation();
    }

    UT_DualQuaternionT<T>           myDQ;
    UT_Matrix3T<T>                  myStretch;
};
SYS_DECLARE_IS_POD(GU_DualQuatXformT<fpreal32>)
SYS_DECLARE_IS_POD(GU_DualQuatXformT<fpreal64>)

/// Stores the source geometry and attributes to deform, for
/// GU_LinearSkinDeformer.
class GU_API GU_LinearSkinDeformerSourceAttribs
{
public:
    GU_LinearSkinDeformerSourceAttribs(const GU_Detail *gdp);

    int64 getMemoryUsage(bool inclusive) const;

    /// Clear the list of attributes and rebind to a different detail.
    void reset(const GU_Detail *gdp);

    /// Returns the source detail.
    const GU_Detail *srcGdp() const { return myGdp; }

    /// Append attribute to be deformed. How it is deformed depends on the
    /// attribute's GA_TypeInfo.
    void append(const GA_Attribute &src_attrib);

private:
    const GU_Detail *myGdp;
    UT_Array<const GA_Attribute *> myPosAttribs;
    UT_Array<const GA_Attribute *> myVecAttribs;
    UT_Array<const GA_Attribute *> myNmlAttribs;
    UT_Array<const GA_Attribute *> myQuatAttribs;
    UT_Array<const GA_Attribute *> myMat3Attribs;
    UT_Array<const GA_Attribute *> myMat4Attribs;

    friend class GU_LinearSkinDeformer;
};

/// Class representing source capture weight data for GU_LinearSkinDeformer
class GU_API GU_LinearSkinDeformerSourceWeights : UT_NonCopyable
{
public:
                                    GU_LinearSkinDeformerSourceWeights();

    int64                           getMemoryUsage(bool inclusive) const;

    /// Reset all state
    void                            reset();

    /// Set up from the source geometry. Returns the number of transforms
    /// required to deform using the capture weight attribute. If in error,
    /// then 0 is returned.
    /// If max_pt_weights > 0, then it will limit the number of weight entries
    /// to use per point.
    int                             init(
                                        const GU_Detail& src,
                                        const GA_Range& pt_range,
                                        int max_pt_weights = 0);

    const GU_Detail*                srcGdp() const
                                        { return myGdp; }
    void                            setSrcGdp(const GU_Detail &src)
                                        { myGdp = &src; }

    /// Set new region transforms from point skeleton geometry with P, name,
    /// and transform. It will invert transform to match what getCaptureParms()
    /// returns.
    bool                            setRegionXformsFromGeo(
                                        const GU_Detail& rest_skel,
                                        const GA_Attribute& P,
                                        const GA_Attribute& name,
                                        const GA_Attribute& transform);

    /// Number of points in the range given to init().
    exint                           numPoints() const { return myNumPoints; }

    /// Return the number of regions found by initSrc()
    int                             numRegions() const
                                        { return myRegionXforms.entries(); }

    /// Return the name given the region index. init() must have been
    /// called first.
    const UT_StringHolder &         regionName(int i) const
                                        { return myRegionNames[i]; }

    /// Return the transform given the region index. init() must have been
    /// called first.
    const UT_Matrix4F&              regionXform(int i) const
                                        { return myRegionXforms[i]; }

    /// Returns whether the region is referenced by at least one capture
    /// element.
    bool                            usesRegion(int i) const
                                        { return myUsedRegions.getBitFast(i); }

    /// Static utility method to get capture parameters
    static bool                     getCaptureParms(
                                        const GU_Detail& src,
                                        GA_ROAttributeRef& pcapt,
                                        GEO_AttributeCapturePath& attr_cap_path,
                                        UT_Array<UT_Matrix4F>& xforms,
                                        int& max_pt_regions);

    using CaptureElementRange =
        UT_IteratorRange<GU_CaptureElementArray::const_iterator>;

    /// Returns the range of capture elements for the given point index.
    CaptureElementRange             captureElementRange(exint ptidx) const;

private:
    const GU_Detail*                myGdp;
    GA_OffsetArray                  myPointOffsets;
    UT_ExintArray                   myPointStarts;
    GU_CaptureElementArray          myCaptureElements;
    /// Number of points in the range passed to init(). This may not be the same
    /// as myPointOffsets.size() if the range is not contiguous.
    exint                           myNumPoints;
    /// Primitives in the source detail that we will update transforms for.
    GA_OffsetArray                  myPrimOffsets;
    /// Index of the first primitive from the point range.
    GA_Index                        myPrimStartIdx;

    UT_StringArray                  myRegionNames;
    UT_Array<UT_Matrix4F>           myRegionXforms;
    UT_BitArray                     myUsedRegions;

    friend class GU_LinearSkinDeformer;
};

inline GU_LinearSkinDeformerSourceWeights::CaptureElementRange
GU_LinearSkinDeformerSourceWeights::captureElementRange(exint ptidx) const
{
    return UTmakeRange(myCaptureElements.begin() + myPointStarts[ptidx],
                       myCaptureElements.begin() + myPointStarts[ptidx + 1]);
}

/// Performs linear blend skinning of geometry
class GU_API GU_LinearSkinDeformer : UT_NonCopyable
{
public:
                                    GU_LinearSkinDeformer();

    /// Reset all state
    void                            reset();

    enum Method
    {
        DEFORM_LINEAR,
        DEFORM_DUALQUAT,
        DEFORM_DUALQUAT_BLEND,
    };

    /// Setup the destination geometry. Fails if the destination is missing
    /// attributes that were appended to deform. A reference to the src is
    /// maintained until reset() is called.
    bool                            init(
                                        GU_Detail& dst,
                                        const GA_Range& pt_range,
                                        const GU_LinearSkinDeformerSourceWeights& src_weights,
                                        const GU_LinearSkinDeformerSourceAttribs& src_attribs,
                                        Method method = DEFORM_LINEAR,
                                        bool create_missing_attribs = false,
                                        const char *blend_attrib = nullptr);

    int                             numRegions() const
                                    { return mySrcWeights->myRegionXforms.entries(); }

    const UT_StringHolder &         regionName(int i) const
                                    { return mySrcWeights->regionName(i); }

    /// For debugging purposes, call this before making your
    /// setRegionTransform() calls to avoid asserts about missing transforms.
    void                            clearNumTransformsSet()
                                        { UT_IF_ASSERT(myNumTransformsSet=0;) }

    /// Set deforming transform for region_idx, which matches indices found in
    /// the capture weight attribute. init() must have been called first.
    void                            setRegionTransform(
                                        int region_idx,
                                        const UT_Matrix4F& xform);

    /// Set deforming transform for region_idx. To apply the capture region's
    /// transform use setRegionTransform(). init() must have been called first.
    void                            setFullRegionTransform(
                                        int region_idx,
                                        const UT_Matrix4F& xform);

    /// Set transforms relative to capture region transforms from
    /// P,name,transform attributes. This matches with
    /// GU_LinearSkinDeformerSourceWeights::setRegionXformsFromGeo()
    bool                            setRegionTransformsFromGeo(
                                        const GU_Detail& anim_skel);

    /// Spawn tasks that will perform the deformation. The tasks will have
    /// references to this object, so they must be executed before this object
    /// is destroyed.
    ///
    /// The necessary steps in this specific order:
    /// 1. N = GU_LinearSkinDeformerSource::init() for the point geometry you 
    ///    want to deform
    /// 2. GU_LinearSkinDeformerSource::appendAttrib() for each src attribute
    ///    you want to deform
    /// 3. GU_LinearSkinDeformer::init() to set up where to put the results
    /// 4. Call setRegionTransform() N times for each of the cregions
    /// 5. Call spawnDeformTasks()
    /// 6. When done with the task list, spawn them: tasks.spawnRootAndWait();
    ///
    /// @{
    void                            spawnDeformTasks(
                                        UT_TaskGroup& tasks);
    void                            spawnInverseDeformTasks(
                                        UT_TaskGroup& tasks);
    /// @}

    /// Do the deform.
    ///
    /// The necessary steps in this specific order:
    /// 1. N = GU_LinearSkinDeformerSource::init() for the point geometry you 
    ///    want to deform
    /// 2. GU_LinearSkinDeformerSource::appendAttrib() for each src attribute
    ///    you want to deform
    /// 3. GU_LinearSkinDeformer::init() to set up where to put the results
    /// 4. Call setRegionTransform() N times for each of the cregions
    /// 5. Call deform()
    ///
    /// @{
    void                            deform();
    void                            inverseDeform();
    /// @}

public:
    typedef UT_Array<GA_AttributeUPtr>           AttribPtrArray;
    typedef GU_DualQuatXformT<float>             DualQuatXformF;

    static const char* SKIN_LINEAR;
    static const char* SKIN_DUAL_QUATERNION;
    static const char* SKIN_BLEND_DUAL_QUATERNION_AND_LINEAR;

    static bool                     getGlobalAttribMethod(const GU_Detail *igdp, Method &type);
    static bool                     getGlobalAttribBlendAttrib(const GU_Detail *igdp,
                                                               UT_StringHolder &blend_attrib);

private:

    void                            clearXforms();

    void                            deformInParallel();

    template <bool ALIGNED, bool INVERT>
    void                            spawnLinearTasks(
                                        UT_TaskGroup& tasks);
    template <bool ALIGNED, bool INVERT>
    void                            spawnDualQuatTasks(
                                        UT_TaskGroup& tasks);
    template <bool ALIGNED, bool INVERT>
    void                            spawnBlendedDualQuatTasks(
                                        UT_TaskGroup& tasks);

private:
    Method                          myMethod;

    GU_Detail*                      myDstGdp;
    GA_Range                        myDstRange;
    UT_Array<GA_Attribute*>         myDstPosAttribs;
    UT_Array<GA_Attribute*>         myDstVecAttribs;
    UT_Array<GA_Attribute*>         myDstNmlAttribs;
    UT_Array<GA_Attribute*>         myDstQuatAttribs;
    UT_Array<GA_Attribute*>         myDstMat3Attribs;
    UT_Array<GA_Attribute*>         myDstMat4Attribs;

    const GU_LinearSkinDeformerSourceWeights* mySrcWeights;
    const GU_LinearSkinDeformerSourceAttribs* mySrcAttribs;

    GA_ROHandleF                    mySrcBlendAttrib;

    AttribPtrArray                  mySrcPromotedAttribs;

    // Linear blending
    UT_Array<UT_Matrix4F>           myPosXforms;
    UT_Array<UT_QuaternionF>        myQuatXforms;

    // DualQuaternion blending
    UT_Array<DualQuatXformF>        myDualQuatXforms;

    // This is only used when assertions are enabled
    exint                           myNumTransformsSet;
};

#endif // __GU_LINEARSKINDEFORMER_H_INCLUDED__