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

#pragma once

#ifndef __GA_AttributeInstanceMatrix__
#define __GA_AttributeInstanceMatrix__

#include "GA_API.h"
#include "GA_Attribute.h"
#include "GA_Handle.h"
#include "GA_Names.h"
#include "GA_Types.h"

#include <UT/UT_SharedPtr.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_VectorTypes.h>
#include <SYS/SYS_Types.h>

class GA_AttributeDict;

/// @brief Compute an instance transform given a set of attributes
///
/// Given a normal (or velocity) attribute, along with attributes for the up
/// vector, a translation offset, a uniform scale, a 3-tuple scale, a rotation
/// quaternion and an orientation quaternion, compute a 4x4 transform matrix
/// for a given position.
///
/// This transform is the same as the one generated by the copy SOP or by SOHO
/// instancing.
///
/// @see UT_Matrix4::instance()
class GA_API GA_AttributeInstanceMatrix
{
public:
    /// Default c-tor
    GA_AttributeInstanceMatrix()
        : myRemoveScales(false)
    {}

    /// Construct given the explicit attributes
    ///
    /// All attributes must be bound to the same owner (GA_AttributeOwner).
    /// The offset passed into @c getMatrix() determines which element is used
    /// to build the matrix.  The owner does not have to be GA_ATTRIB_POINT,
    /// though that is the most common case.
    GA_AttributeInstanceMatrix(
            const GA_Attribute *N,
            const GA_Attribute *v,
            const GA_Attribute *up,
            const GA_Attribute *trans,
            const GA_Attribute *pscale,
            const GA_Attribute *pscale3,
            const GA_Attribute *rot,
            const GA_Attribute *orient,
            const GA_Attribute *pivot,
            const GA_Attribute *xform3,
            const GA_Attribute *xform4
                            )
        : myN(N ? N : v)
        , myPscale(pscale)
        , myPscale3(pscale3)
        , myUp(up)
        , myTrans(trans)
        , myRot(rot)
        , myOrient(orient)
        , myPivot(pivot)
        , myXform3(xform3)
        , myXform4(xform4)
        , myRemoveScales(false)
    {
        validate();
    }

    GA_AttributeInstanceMatrix(const GA_AttributeDict &dict,
                    const UT_StringRef &N_name = GA_Names::N,
                    const UT_StringRef &v_name = GA_Names::v)
    {
        initialize(dict, N_name, v_name);
    }

    GA_AttributeInstanceMatrix(const GA_AttributeDict &dict,
                    const GA_Attribute *N)
    {
        initialize(dict, N);
    }

    ~GA_AttributeInstanceMatrix() {}

    /// Initialize attribute lookups based on an attribute dictionary
    /// This method scans for:
    /// - "vector v" or "vector N"      (z-axis)
    /// - "vector up"                   (up vector for orientation)
    /// - "vector trans"                (translation offset)
    /// - "vector scale"                (per-axis scale)
    /// - "float pscale"                (uniform scale)
    /// - "vector4 rot"                 (quaternion)
    /// - "vector4 orient"              (quaternion)
    /// - "vector pivot"                (pivot)
    /// @c N_name defines the name of the attribute to look up to determine
    /// orientation.  If there is no attribute of the given name, then an
    /// attribute named @c v_name will be searched for.
    ///
    void        initialize(const GA_AttributeDict &dict,
                        const UT_StringRef &N_name = GA_Names::N,
                        const UT_StringRef &v_name = GA_Names::v);
    /// Initialize with a provided, possilby detached N.
    void        initialize(const GA_AttributeDict &dict,
                        const GA_Attribute *N);


    /// Clear out any attribute handles
    void        reset();

    /// Resets only the scale attributes.
    void        resetScales();

    /// Make invalid
    void        makeInvalid()   { reset(); }

    /// @{
    /// Create a 4x4 transform matrix given a position (@c P) and an attribute
    /// element for which the GA_ROHandle objects are valid.
    ///
    /// If the "pscale" attribute is invalid, the @c default_pscale will be
    /// used.
    ///
    /// @note The position (@c P) is passed in since the attribute handles may
    /// not be bound to point attributes.
    void        getMatrix(UT_Matrix4 &xform,
                            const UT_Vector3 &P,
                            GA_Offset offset,
                            float default_pscale=1) const;
    void        getMatrix(UT_Matrix4D &xform,
                            const UT_Vector3D &P,
                            GA_Offset offset,
                            fpreal default_pscale=1) const;
    void        getInverseMatrix(UT_Matrix4 &xform,
                            const UT_Vector3 &P,
                            GA_Offset offset,
                            float default_pscale=1) const;
    void        getInverseMatrix(UT_Matrix4D &xform,
                            const UT_Vector3D &P,
                            GA_Offset offset,
                            fpreal default_pscale=1) const;
    /// @}

    /// Create a 3x3 transform matrix ignoring translate components
    /// Will include scale if still present!
    void        getMatrix(UT_Matrix3 &xform,
                            GA_Offset offset) const;
    void        getMatrix(UT_DMatrix3 &xform,
                            GA_Offset offset) const;
    void        getInverseMatrix(UT_Matrix3 &xform,
                            GA_Offset offset) const;
    void        getInverseMatrix(UT_DMatrix3 &xform,
                            GA_Offset offset) const;

    /// @{
    /// Create a 4x4 transform matrix given a position (@c P),
    /// an orientaiton (@c orient), and an attribute
    /// element for which the GA_ROHandle objects are valid.
    ///
    /// The provided orientation will be used instead of any rotation
    /// attributes on the geometry, but the translation and pivot attributes
    /// will still be used.
    ///
    /// If the "pscale" attribute is invalid, the @c default_pscale will be
    /// used.
    ///
    /// @note The position (@c P) is passed in since the attribute handles may
    /// not be bound to point attributes.
    void        getMatrix(UT_Matrix4 &xform,
                            const UT_Vector3 &P,
                            const UT_Quaternion &orient,
                            GA_Offset offset,
                            float default_pscale=1) const;
    void        getMatrix(UT_Matrix4D &xform,
                            const UT_Vector3D &P,
                            const UT_QuaternionD &orient,
                            GA_Offset offset,
                            fpreal default_pscale=1) const;
    void        getInverseMatrix(UT_Matrix4 &xform,
                            const UT_Vector3 &P,
                            const UT_Quaternion &orient,
                            GA_Offset offset,
                            float default_pscale=1) const;
    void        getInverseMatrix(UT_Matrix4D &xform,
                            const UT_Vector3D &P,
                            const UT_QuaternionD &orient,
                            GA_Offset offset,
                            fpreal default_pscale=1) const;
    /// @}

    /// Returns true if there are any attributes bound
    bool        hasAnyAttribs() const;

    /// Returns true if there are any attributes bound to
    /// anything other than myPscale or myPscale3
    bool        hasNonScales() const;

    /// Returns true if myPscale or myPscale3 is bound
    bool        hasScales() const;

    /// Returns just the product of myPscale and myPscale3
    UT_Vector3D getScales(GA_Offset offset) const;

    /// @{
    /// Accessors
    const GA_ROHandleV3D        &getN() const { return myN; }
    const GA_ROHandleV3D        &getUp() const { return myUp; }
    const GA_ROHandleV3D        &getTrans() const { return myTrans; }
    const GA_ROHandleD          &getPscale() const { return myPscale; }
    const GA_ROHandleV3D        &getPscale3() const { return myPscale3; }
    const GA_ROHandleQD         &getRot() const { return myRot; }
    const GA_ROHandleQD         &getOrient() const { return myOrient; }
    const GA_ROHandleV3D        &getPivot() const { return myPivot; }
    const GA_ROHandleM3D        &getXform3() const { return myXform3; }
    const GA_ROHandleM4D        &getXform4() const { return myXform4; }
    bool                 getRemoveScales() const { return myRemoveScales; }
    /// @}

    /// Overrides the N attribute with the specified attribute.
    void setN(const GA_Attribute *N)
    { myN.bind(N); }

    /// The number of attributes cached for use with transforms by this class.
    /// If an attribute gets added, be sure to update this and the getDataIds
    /// function implementation.
    static constexpr int theNumAttribs = 10;

    /// This uses GA_DataId(-2) to indicate an attribute not being present,
    /// to distinguish it from GA_DataId(-1), which is usually considered
    /// unequal even to itself.
    static constexpr GA_DataId theAttribNotPresentDataId = GA_DataId(-2);

    /// Get all data IDs of attributes used by this class.
    /// This uses a value of theAttribNotPresentDataId for attributes
    /// that aren't present.
    void getDataIds(GA_DataId data_ids[theNumAttribs]) const;

private:
    void        validate();

public:
    GA_ROHandleV3D      myN;
    GA_ROHandleV3D      myUp;
    GA_ROHandleV3D      myTrans;
    GA_ROHandleD        myPscale;
    GA_ROHandleV3D      myPscale3;
    GA_ROHandleQD       myRot;
    GA_ROHandleQD       myOrient;
    GA_ROHandleV3D      myPivot;
    GA_ROHandleM3D      myXform3;
    GA_ROHandleM4D      myXform4;
    bool                myRemoveScales;
};

typedef UT_SharedPtr<GA_AttributeInstanceMatrix> GA_AttributeInstanceMatrixPtr;

#endif