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 <CE/CE_BufferDevice.h>

#include <GA/GA_CEAttribute.h>
#include <GA/GA_Range.h>
#include <GA/GA_Types.h>

#include <GEO/GEO_AttributeIndexPairs.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_StringHolder.h>
#include <UT/UT_StringMap.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
    {
        // Note that we have to apply this in the REVERSE order here
        // because src and m here are both quaternions.
        //
        //       (q1 * q2) * v * (q1 * q2)^*
        //   ==>  q1 *  q2 * v * q2^*  * q1^*
        //   ==>  q1 * (q2 * v * q2^*) * q1^*
        //
        // This implies that q2 is applied to v, followed by q1.
        // Meaning => matrix(q1 * q2) = matrix(q2) * matrix(q1).
        // Fixes bad results from bug 156035.
        //
        return myDQ.getRotation() * src;
    }

    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,
                                        bool use_opencl = false,
                                        int max_pt_weights = 0);
    int                             init(
                                        const GU_Detail& src,
                                        const GA_Range& pt_range,
                                        const UT_StringRef &capt_attrib_name,
                                        bool use_opencl = false,
                                        int max_pt_weights = 0);
    /// @}

    const UT_StringHolder&          captAttribName() const
                                        { return myCaptAttribName; }

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

    /// Return if myRegionXforms has been initialized
    bool                            haveRegionXforms() const
                                        { return myHaveRegionXforms; }

    /// 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,
                                        bool& have_region_xforms);
    static bool                     getCaptureParms(
                                        const GU_Detail& src,
                                        const UT_StringRef &capt_attrib_name,
                                        GA_ROAttributeRef& pcapt,
                                        GEO_AttributeCapturePath& attr_cap_path,
                                        UT_Array<UT_Matrix4F>& xforms,
                                        int& max_pt_regions,
                                        bool& have_region_xforms);
    /// @}

    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:
    /// Return the array of indices(int) and weights(float) from myCaptureElements for OpenCL kernel
    template <typename ELEMENT_TYPE>
    UT_Array<ELEMENT_TYPE>          getCaptureElementsArray() const;

    /// Set the static arguments which will not be changed per frame
    void                            setupStaticBufferOCL();
    
    /// Clear up OpenCL buffers
    void                            clearOCL();

private:
    const GU_Detail*                myGdp;
    UT_StringHolder                 myCaptAttribName;
    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;

    /// Topology CE Attribute
    GA_CEAttributePtr               myPtToVtxCEAttrib;

    /// Buffers are updated during init(), not every frame.
    CE_BufferDevice<exint>          myPtStartBuf;
    CE_BufferDevice<int>            myCaptureElementsIndexBuf;
    CE_BufferDevice<float>          myCaptureElementsWeightBuf;

    bool                            myUseOpenCL;
    bool                            myHaveRegionXforms; 

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


    enum AttributeType
    {
        POS,
        NML,
        VEC,
        QUAT,
        MAT3,
        MAT4,
        MAT4D
    };

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

    /// OpenCL
    void                            initializeOpenCL();
    void                            deformOCL();
    /// clear up OpenCL buffers
    void                            clearOCL();

    template <Method METHOD>
    void                            processDeformOCL();

    template <Method METHOD, AttributeType ATTRIB_TYPE>
    void deformAttribOCL(
            const UT_Array<const GA_Attribute*>& src_attribs,
            UT_Array<GA_Attribute*>& dst_attribs,
            GA_Size total_point,
            GA_Size deform_point,
            GA_Index dst_start,
            GA_Index dst_end);

    template <Method METHOD>
    void                            deformPrimCPU(GA_Index dst_start);

    void                            setupFrameSharedBufferOCL();

    template <typename BLEND_TYPE>
    void                            setBlendKernelArgOCL(GA_Size point_num);
    template <typename BLEND_TYPE>
    void                            blendDeformOCL(GA_Size point_num);

    template < Method METHOD, GA_AttributeOwner ATTRIB_OWNER, AttributeType ATTRIB_TYPE>
    void                            setApplyKernelArgOCL(
                                        const GA_Attribute* src_attrib,
                                        GA_Attribute* dst_attrib,
                                        GA_Size point_num, 
                                        GA_Index dst_start, GA_Index dst_end);

    template <Method METHOD, GA_AttributeOwner ATTRIB_OWNER, AttributeType ATTRIB_TYPE>
    void                            applyDeformOCL(
                                        const GA_Attribute* src_attrib, 
                                        GA_Attribute* dst_attrib,
                                        GA_Size point_num, 
                                        GA_Index dst_start, GA_Index dst_end);

    void                            splitDualQuatArray();

    /// Helper functions for getting kernel name
    template<Method METHOD>
    UT_StringHolder                 getMethodString();
    
    template<AttributeType ATTRIB_TYPE>
    UT_StringHolder                 getAttributeTypeString();

    template<GA_AttributeOwner ATTRIB_CLASS>
    UT_StringHolder                 getAttributeClassString();

    template<typename BLEND_TYPE>
    UT_StringHolder                 getBlendTypeString();

    template <typename BLEND_TYPE>
    UT_StringHolder                 getBlendKernelName();

    template <
            Method METHOD,
            GA_AttributeOwner ATTRIB_CLASS,
            AttributeType ATTRIB_TYPE>
    UT_StringHolder getApplyKernelName(bool is_pt_attrib = true);

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;

    exint                           mySrcBlendAttribId;
    // OpenCL data
    bool                            myCEInitialized;
    cl::Program                     myProgram;
    UT_StringMap<cl::Kernel>        myKernelMap;

    CE_BufferDevice<float>          myBlendFactorBuf;

    CE_BufferDevice<UT_Matrix4F>    myXformMatsBuf;
    CE_BufferDevice<UT_QuaternionF> myXformQuatsBuf;

    UT_Array<UT_QuaternionF>        myXformRealQuats;
    UT_Array<UT_QuaternionF>        myXformDualQuats;
    UT_Array<UT_Matrix3F>           myXformMat3Stretch;

    CE_BufferDevice<UT_QuaternionF> myXformRealQuatsBuf;
    CE_BufferDevice<UT_QuaternionF> myXformDualQuatsBuf;
    CE_BufferDevice<UT_Matrix3F>    myXformMat3StretchBuf;

    CE_BufferDevice<UT_Matrix4F>    myBlendMatsBuf;
    CE_BufferDevice<UT_QuaternionF> myBlendQuatsBuf;

    CE_BufferDevice<UT_QuaternionF> myBlendRealQuatsBuf;
    CE_BufferDevice<UT_QuaternionF> myBlendDualQuatsBuf;
    CE_BufferDevice<UT_Matrix3F>    myBlendMat3StretchBuf;

};

#endif // __GU_LINEARSKINDEFORMER_H_INCLUDED__