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

#ifndef __GU_PolyFrame__
#define __GU_PolyFrame__

#include "GU_API.h"

#include <GA/GA_Handle.h>
#include <GEO/GEO_PrimPolySoup.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_Vector3.h>
#include <string.h>

// GU_PolyFrame::theMinVertices[] depends on the ordering of this enumeration.
enum GU_PolyFrameStyle
{
    GU_POLYFRAME_FIRST_EDGE,
    GU_POLYFRAME_TWO_EDGES,
    GU_POLYFRAME_CENTROID,
    GU_POLYFRAME_TEXTURE_COORDS,
    GU_POLYFRAME_TEXTURE,
    GU_POLYFRAME_STYLE__count
};

enum GU_PolyFrameVector
{
    GU_POLYFRAME_TANGENT = 1,
    GU_POLYFRAME_BITANGENT = 1 << 1,
    GU_POLYFRAME_NORMAL = 1 << 2,
};

enum GU_PolyFrameError
{
    GU_POLYFRAME_NO_ERROR,
    GU_POLYFRAME_CREATE_ATTRIBUTE_FAILED,
    GU_POLYFRAME_MISSING_DETAIL,
    GU_POLYFRAME_MISSING_TEXTURE_COORDS,
    GU_POLYFRAME_ERROR__count
};

class GU_API GU_PolyFrameParms
{
public:
    GU_PolyFrameParms()
        : style(GU_POLYFRAME_FIRST_EDGE)
        , which(GU_POLYFRAME_NORMAL)
        , orthogonal(false)
        , left_handed(false)
        , uv_name(0)
    {
        ::memset(names, 0, sizeof(const char *) * 3);
    }

    GU_PolyFrameStyle style; // Specifies how the frame vectors are
                             // to be calculated.

    int which; // A bit mask that specifies which basis
               // vectors are to be evaluated.  Bits
               // can be set using members of the
               // GU_PolyFrameVector enumeration.

    bool orthogonal; // Indicates that the frame vectors
                     // must be made orthogonal.

    bool left_handed; // When false (default), it produces a
                      // right-handed frame, else left-handed.
                      // This only applies when orthogonal is
                      // true.

    const char *names[3]; // Specifies the names of the frame
                          // vector attributes that are being
                          // computed.  names[0] points to the
                          // name of the tangent vector.  names[1]
                          // points to the name of the bitangent
                          // vector.  names[2] points to the name
                          // of the normal.  names[0] and/or
                          // names[1] will be ignored if the
                          // corresponding bit in 'which' is not
                          // set.

    const char *uv_name; // Optionally overrides the texture
                         // attribute name used when style is
                         // GU_POLYFRAME_TEXTURE_COORDS
};

class GA_PointGroup;
class GA_PrimitiveGroup;
class GEO_Hull;
class GEO_Face;
class GU_Detail;
class UT_BitArray;
class UT_String;

class GU_API GU_PolyFrame
{
public:
    GU_PolyFrame(GU_Detail *gdp);
    virtual ~GU_PolyFrame();

    GU_Detail *getDetail() const { return myGdp; }
    void setDetail(GU_Detail *gdp) { myGdp = gdp; }

    // Computes the frame attributes specified in parms on the gdp supplied to
    // the constructor or set via setDetail()
    //
    // If a point_group is given, this will still set default values for any
    // newly created attributes (i.e. ones that didn't pre-exist on myGdp),
    // on points that are not in point_group.
    GU_PolyFrameError computeFrames(
            const GU_PolyFrameParms &parms,
            const GA_PointGroup *point_group = nullptr,
            const GA_PrimitiveGroup *prim_group = nullptr);

    static GU_PolyFrameError computeFrames(
            GA_AttributeUPtr &tangent,
            GA_AttributeUPtr &bitangent,
            GA_AttributeUPtr &normal,
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GU_PolyFrameParms &parms,
            const GA_PointGroup *point_group = nullptr,
            const GA_PrimitiveGroup *prim_group = nullptr,
            const GA_Attribute *existing_normal = nullptr);

    void setSaveAttribFlag(bool val) { storeAttribs = val; }
    void getAttribNormals(GA_RWHandleV3 &handle)
    {
        if (storeAttribs)
            handle = myAttribs->normal();
    }
    void getAttribTangents(GA_RWHandleV3 &handle)
    {
        if (storeAttribs)
            handle = myAttribs->tangent();
    }
    void getAttribBitangents(GA_RWHandleV3 &handle)
    {
        if (storeAttribs)
            handle = myAttribs->bitangent();
    }

private:
    struct Frame
    {
        UT_Vector3 tangent;
        UT_Vector3 bitangent;
        UT_Vector3 normal;

        const UT_Vector3 &getVector(int i) const
        {
            UT_ASSERT(i >= 0 && i <= 2);

            if (i == 0)
                return tangent;
            else if (i == 1)
                return bitangent;
            else
                return normal;
        }
    };

    enum class NormalMethod
    {
        COMPATIBLE,
        GEOCOMPUTENORMAL
    };

    // Utility class for creating and passing around attributes.
    //
    // Holds ownership of any created detached attributes.
    class FrameAttribHandles
    {
    public:
        FrameAttribHandles() = default;

        const GA_RWHandleV3 &handle(int index) const
        {
            UT_ASSERT(index >= 0 && index < 3);
            return myHandles[index];
        }

        void findOrAddAttrib(
                int index,
                GU_Detail &gdp,
                const UT_StringRef &name,
                GA_AttributeOwner owner,
                GA_TypeInfo type);

        bool createDetachedOutputAttrib(
                const GU_Detail &gdp,
                int index,
                GA_AttributeOwner owner,
                GA_AttributeUPtr &attrib);

        // Creates any temporary attributes required for computing the output
        // attribs explicitly requested by the caller of computeFrames(). We
        // take ownership of these attributes.
        void createTempAttrib(
                const GU_Detail &gdp,
                int index,
                GA_AttributeOwner owner);

        bool createdOnGdp(int index) const { return myCreatedOnDetail[index]; }

        const GA_RWHandleV3 &tangent() const { return myHandles[0]; }

        const GA_RWHandleV3 &bitangent() const { return myHandles[1]; }

        const GA_RWHandleV3 &normal() const { return myHandles[2]; }

    private:
        GA_AttributeUPtr myTempAttribs[3];
        GA_RWHandleV3 myHandles[3];
        bool myCreatedOnDetail[3];
    };

    static GU_PolyFrameError computeFrames(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GU_PolyFrameParms &parms,
            const GA_PointGroup *point_group,
            const GA_PrimitiveGroup *prim_group,
            const GA_Attribute *existing_normal,
            FrameAttribHandles &attribs,
            NormalMethod normalmethod,
            UT_BitArray *uncomputed);

    static void computeFrames(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &pattrib,
            const GU_PolyFrameParms &parms,
            const GA_PointGroup *point_group,
            const GA_PrimitiveGroup *prim_group,
            const GEO_Face &prim,
            UT_BitArray *uncomputed,
            GA_Size &nleft,
            bool pervertex,
            const GA_ROHandleV2 &uv,
            const FrameAttribHandles &attribs);

    // depending on parms, this creates output attributes on myGdp.
    static bool createOutputAttribsOnDetail(
            GU_Detail &gdp,
            const GU_PolyFrameParms &parms,
            FrameAttribHandles &attribs);

    static bool createDetachedOutputAttribs(
            const GU_Detail &gdp,
            const GU_PolyFrameParms &parms,
            FrameAttribHandles &attribs,
            GA_AttributeUPtr &tangent,
            GA_AttributeUPtr &bitangent,
            GA_AttributeUPtr &normal);

    // creates any temporary attributes which are not requested by
    // parms but required for computing the specified parms.style of frame.
    static bool createTempAttribs(
            const GU_Detail &gdp,
            const GU_PolyFrameParms &parms,
            FrameAttribHandles &attribs);

    static const GA_ROHandleV2 getUVHandle(
            const GU_Detail &gdp,
            const UT_StringRef &uvname);

    static void setFrame(
            const GU_Detail &gdp,
            const GU_PolyFrameParms &parms,
            const GA_PointGroup *point_group,
            const FrameAttribHandles &attribs,
            const GEO_Face *face,
            GA_Index pointIndex,
            GA_Size vertexIndex,
            bool pervertex,
            const Frame &frame);

    // Frame computation methods for each style in GU_PolyFrameStyle.
    static Frame computeFirstEdgeFrame(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GEO_Face &prim,
            GA_Index pointIndex,
            GA_Size vtx,
            const GA_ROHandleV3 &normal);
    static Frame computeTwoEdgesFrame(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GEO_Face &prim,
            GA_Index pt,
            GA_Size vtx,
            const GA_ROHandleV3 &normal);
    static Frame computeCentroidFrame(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GEO_Face &prim,
            GA_Index pt,
            GA_Size vtx,
            const UT_Vector3 &centroid,
            const GA_ROHandleV3 &normal);
    static Frame computeTexCoordsFrame(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GEO_Face &prim,
            GA_Index pt,
            GA_Size vtx,
            const GA_ROHandleV2 &uv,
            const GA_ROHandleV3 &normal);
    static void computeTexFramePrim(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            GA_Offset primoff,
            const GA_ROHandleV2 &uv,
            const FrameAttribHandles &attribs);
    static void computeTexFrameSoup(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            GA_Offset primoff,
            GEO_PrimPolySoup::PolygonIterator &it,
            const GA_ROHandleV2 &uv,
            const FrameAttribHandles &attribs);
    static Frame computeTexFrame(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            GA_Index pt,
            const FrameAttribHandles &attribs);
    static GU_PolyFrame::Frame computeDefaultFrame(
            const GEO_Face *prim = nullptr);
    static GU_PolyFrame::Frame computeDefaultFrame(
            const GEO_PrimPolySoup::PolygonIterator *it = nullptr);

    // Utility methods.
    static void computeMeshCentroid(
            const GEO_Hull *hull,
            const GA_ROHandleV3 &Pattrib,
            GA_Size vertex_no,
            UT_Vector3 &centroid);
    static void createPointNormals(
            const GU_Detail &gdp,
            const GA_ROHandleV3 &Pattrib,
            const GA_RWHandleV3 &offset,
            const GA_Attribute *normalattrbefore,
            const NormalMethod normalmethod);
    static const char *getLayeredAttribName(
            const GU_Detail *gdp,
            const char *name);
    static bool isStylePerVertex(GU_PolyFrameStyle style);
    static void makeOrthogonal(Frame &frame, bool left_handed);

    static int theMinVertices[];

    GU_Detail *myGdp;

    // // Introduced to compare values for unit tests
    bool storeAttribs;
    UT_SharedPtr<FrameAttribHandles> myAttribs;
};

#endif