GEO/GEO_Primitive.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.
 *
 * Produced by:
 *      Mark Elendt
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        Geometry Library (C++)
 *
 * COMMENTS:
 *      The className method is used for saving/loading so there should
 *        be no spaces in the name.
 *
 */

#ifndef __GEO_Primitive_H__
#define __GEO_Primitive_H__

#include "GEO_API.h"
#include <iostream.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_BoundingBox.h>
#include <UT/UT_BoundingSphere.h>
#include <GA/GA_Primitive.h>
#include "GEO_PrimType.h"
#include "GEO_Vertex.h"

class   GA_Edge;
class   GA_PrimitiveWrangler;
class   GEO_Detail;
class   GEO_Vertex;
class   GEO_VertexAttribDict;
class   GEO_MetaPrim;
class   GEO_AttributeHandleList;

typedef void (* GEO_EdgeApplyFunc)(GEO_Primitive &prim, GA_Offset pt_a,
                                   GA_Offset pt_b, void *data);
typedef void (* GEO_EdgeApplyElementFunc)(GEO_Primitive &prim, GEO_Point &a,
                                          GEO_Point &b, void *data);
typedef void (* GEO_EdgeApplyIndexFunc)(GEO_Primitive &prim, int v1,
                                        int v2, void *data);

class GEO_API GEO_Primitive : public GA_Primitive
{
public:
    GEO_Primitive(GEO_Detail *d, GA_Offset offset = GA_INVALID_OFFSET);
    virtual ~GEO_Primitive();

    virtual GA_PrimCompat::TypeMask      getPrimitiveId() const;

    /// Copy attribute data from the source primitive.  Also, copy over all the
    /// group membership information from the source primitive.
    void        copyAttributesAndGroups(const GEO_Primitive &src,
                                    bool copy_groups=true)
                {
                    copyAttributeData(src);
                    if (copy_groups)
                        copyGroupMembership(src);
                }
    void        copyAttributesAndGroups(const GEO_Primitive &src,
                                    GA_AttributeRefMap &gah,
                                    bool copy_groups=true)
                {
                    copyAttributeData(src, gah);
                    if (copy_groups)
                        copyGroupMembership(src);
                }
    void        copyAttributesAndGroups(const GEO_Primitive &src,
                                    GA_PrimitiveWrangler &wrangler,
                                    bool copy_groups=true)
                {
                    copyAttributeData(src, wrangler);
                    if (copy_groups)
                        copyGroupMembership(src);
                }

    /// Copy the attribute data over from the source primitive.  Often you will
    /// want to call copyAttributesAndGroups() instead.
    void        copyAttributeData(const GEO_Primitive &src);
    void        copyAttributeData(const GEO_Primitive &src,
                                  GA_AttributeRefMap &gah);
    void        copyAttributeData(const GEO_Primitive &src,
                                  GA_PrimitiveWrangler &wrangler);

    using       GA_Primitive::copyAttributeValues;
    void        copyAttributeValues(const GEO_Primitive &src,
                                    GA_PrimitiveWrangler &wrangler);

    /// Copy the group membership from the source primitive to the current
    /// primitive.  Both primitives must be in the same detail.
    void        copyGroupMembership(const GEO_Primitive &src);
            
    // The ptredirect array is allocated to the number of points in the gdp 
    // which src belongs to.  It maps point numbers in src's gdp to
    // point numbers in this' gdp.
    // If src->getVertex(0) has point number 10, this->getVertex(0)
    // will have point number ptredirect[10].
    // copyPrimitive is used internally in the copy/merge methods,
    // thus has support for a non-uniform relationship.
    //
    // copyPrimitive(), unlike copy(), will not copy the primitive attributes.
    // (see copyAttributeData() or copyAttributesAndGroups()).
    virtual void         copyPrimitive(const GEO_Primitive *src, 
                                        GEO_Point **ptredirect)=0;
    virtual GEO_Primitive       *copy(int preserve_shared_pts = 0) const;

    // Transforms the matrix associated with this primitive.  The
    // translate component is ignored: Translate the vertices of
    // the primitive to translate the primitive.
    // This only works with quadrics (sphere, tube, metaballs) and volumes.
    virtual void         transform(const UT_Matrix4 &);

    // Convert the real domain values of the primitive to unit values to be
    // used in the evaluation methods below:
    virtual void         realToUnitPair(float  ureal, float  vreal,
                                        float &uunit, float &vunit) const;

    // Convert the unit values of the primitive to the real domain values
    virtual void         unitToRealPair(float  uunit, float  vunit,
                                        float &ureal, float &vreal) const;

    // Map the normalized length (distance value [0,1]) parameter to the unit 
    // parameterization of the primitve
    virtual void         unitLengthToUnitPair(float  ulength, float  vlength,
                                              float &uparm,  float &vparm)const;

    virtual void         unitToUnitLengthPair(float  uparm,   float  vparm,
                                              float &ulength, float &vlength)
                                                                        const;

    // Evaluate a set of attributes at the bary center of the primitive,
    // returning true on success, false on failure.
    SYS_DEPRECATED bool  evaluateBaryCenter(GEO_Vertex result,
                                            GEO_AttributeHandleList &gah) const;

    bool         evaluateBaryCenter(GA_Offset result, 
                                    GA_AttributeRefMap &map) const
                                    { return evaluateBaryCenterRefMap
                                                                (result, map); }
 
    // Evaluate a set of attributes at a u,v position.  Optionally, evaluate
    // the derivative in the u or v direction.
    // The method returns true if the point could be evaluated
    SYS_DEPRECATED bool  evaluatePoint(GEO_Vertex result,
                                        GEO_AttributeHandleList &gah,
                                        fpreal u, fpreal v=0,
                                        uint du=0, uint dv=0) const;

    bool         evaluatePoint(GA_Offset result,
                                GA_AttributeRefMap &map,
                                fpreal u, fpreal v=0,
                                uint du=0, uint dv=0) const
                                { return evaluatePointRefMap
                                    (result, map, u, v, du, dv); }
   
    // Evaluate the position, the derivative or the normal at domain point
    // (u,v), where u and v MUST be in [0,1]. "v" and "dv" will be ignored
    // when dealing with one-dimensional types such as circles and polygons.
    // Return 0 if OK and -1 otherwise. The normal is not normalized.
    int          evaluatePoint( UT_Vector4 &pos, float u, float v = 0,
                                        unsigned du=0, unsigned dv=0) const
                                        { return evaluatePointV4(pos, u, v, du, dv); }

    virtual int          evaluateNormalVector(UT_Vector3 &nml, float u,
                                        float v = 0) const;
    
    // Evaluate the position at domain point (u,v) in the interior of the
    // geometry.  This calls evaluatePoint by default, but has a different
    // implementation for triangles and quadrilaterals, where barycentric
    // coords or bilinear interpolants are used to get an interior point,
    // rather than a point on the perimeter of the poly.  This was added
    // so particles can stick to triangles and quads.
    SYS_DEPRECATED bool evaluateInteriorPoint(GEO_Vertex result,
                                        GEO_AttributeHandleList &hlist,
                                        fpreal u, fpreal v, fpreal w = 0) const;
    bool            evaluateInteriorPoint(GA_Offset result,
                                        GA_AttributeRefMap &map,
                                        fpreal u, fpreal v, fpreal w = 0) const
                            { return evaluateInteriorPointRefMap(result, map,
                                        u, v, w); }
    int             evaluateInteriorPoint(UT_Vector4 &pos, 
                                       fpreal u, fpreal v, fpreal w = 0) const
                            { return evaluateInteriorPointV4(pos, u, v, w); }

    GEO_Detail          *getParent() const;
    static GA_PrimCompat::TypeMask       getPrimitiveMaskH9(const char *maskstr);

    virtual void        *castTo() const;

    /// Compute the bounding box of the primitive.  Return 0 if unable to
    /// compute bounds (1 on successful computation)
    virtual int          getBBox(UT_BoundingBox *bbox) const = 0;

    /// @{
    /// If the attribute is "P" the base-class will call getBBox()
    virtual bool        enlargeBoundingBox(UT_BoundingRect &b,
                                        const GA_Attribute *P) const;
    virtual bool        enlargeBoundingBox(UT_BoundingBox &b,
                                        const GA_Attribute *P) const;
    /// @}

    /// Return a normal vector for the primitive
    virtual UT_Vector3   computeNormal() const = 0;

    /// Reverse the order of vertices
    virtual void         reverse() = 0;

    /// Return the center of the primitive.  This defaults to the center of the
    /// bounding box.  A better approximation might be the average value of the
    /// vertex positions (which could be different).
    virtual UT_Vector3   baryCenter() const;

    /// Enlarge the bounding sphere with the primitive's bounds.
    /// By default, this will enlarge the bounding sphere by the primitive's
    /// bounding box (i.e. getBBox()).  It may be possible to have a tighter
    /// bound (i.e. the vertex hull for many primitives is a much better
    /// metric).
    virtual void         addToBSphere(UT_BoundingSphere *bsphere) const;

    /// Method to isolate a pasted surface
    virtual void         isolate() { /* No implementation here. */ }

    /// Add all points referenced by the primitive to the given group.  This
    /// defaults to iterating over the vertices and adding their referenced
    /// points.
    virtual void         addPointRefToGroup(GA_PointGroup &grp) const;

    // Take the whole set of points into consideration when applying the
    // point removal operation to this primitive. The method returns 0 if
    // successful, -1 if it failed because it would have become degenerate,
    // and -2 if it failed because it would have had to remove the primitive
    // altogether.
    virtual int          detachPoints (GA_PointGroup &grp) = 0;

    virtual int          hasEdge(const GEO_Point &a, const GEO_Point &b) const;
    virtual int          hasEdge(const GA_Edge &edge) const;
    virtual int          hasGuideEdge(int edgeid, UT_Vector4 &a, 
                                                  UT_Vector4 &b) const;
    virtual int          hasXsectPoint(int pointid, UT_Vector4 &p) const; 

    virtual void         edgeApply(GEO_EdgeApplyFunc apply, void  *data = 0);
    virtual void         edgeApply(GEO_EdgeApplyElementFunc apply,
                                   void  *data = 0);
    virtual void         edgeApplyIndex(GEO_EdgeApplyIndexFunc apply,
                                        void  *data = 0);

    // Apply the function to each vertex of the primitive.  Break
    // when the function returns a non-zero value.  Return the value
    // of the last function applied (0 if never called).
    virtual int          vertexApply(int (*apply)(GEO_Vertex vtx, void *),
                                     void  *data = 0);
    virtual int          vertexApply(int (*apply)(const GEO_Vertex &vtx, void*),
                                     void  *data = 0) const;

    /// Return whether a point is referenced by a primitive.  This simply
    /// iterates over the vertices, checking if any vertices reference the
    /// point.
    bool        isPointUsed(const GEO_Point *ppt) const;

    /// @deprecated Call getVertexElement() instead.  getVertexOffset() will
    /// take this name in the future.
    SYS_DEPRECATED const GEO_Vertex     getVertex(unsigned i = 0) const
                                                { return getVertexElement(i); }
    SYS_DEPRECATED GEO_Vertex           getVertex(unsigned i = 0)
                                                { return getVertexElement(i); }
    GEO_Vertex           getVertexElement(unsigned i) const;

//
//  Method to get the tessera data for meta-primitives
    virtual GEO_MetaPrim        *castToMetaPrim(void);
    virtual const GEO_MetaPrim  *castToMetaPrim(void) const;

    // Return the surrounding values of the real-space u,v parameters.
    // Returns 1 if succesful, 0 if out-of-range.

    virtual int          parametricBBox(float u, float v, 
                                        float *u0, float *u1,
                                        float *v0, float *v1);

    // Returns distance between two points in parameter space, aware
    // of any possible wrapping.
    virtual float        uvDist(float u1, float v1, float u2, float v2) const;

    /// Stash (deactivate) or unstash (reactivate) the primitive.
    ///
    /// Stashing a primitive will set its offset to that specified, typically
    /// GA_INVALID_OFFSET.  Primitives are only stashed as part of clearing a
    /// detail, so there is no need to explicitly deallocate vertices.  It is
    /// safe to delete a stashed primitive.
    ///
    /// Unstashing a primitive will re-register that primitive with its parent
    /// detail at the specified offset (or a new offset if GA_INVALID_OFFSET).
    virtual              void   stashed(int onoff,
                                        GA_Offset offset = GA_INVALID_OFFSET);

    // Intersects a ray with the bounding box, iteratively growing it until
    // an intersection is found or maxtries is reached.
    int                  bboxIntersectRay(const UT_Vector3 &rayorig,
                                          const UT_Vector3 &raydir,
                                          int   maxtries = 10,
                                          float tmax = 1E17F,
                                          float *distance = 0,
                                          UT_Vector3 *nml=0) const;

    /// @{
    /// If the method isn't known, or doesn't make sense, we return 0.
    virtual fpreal       calcVolume(const UT_Vector3 &) const { return 0; }
    virtual fpreal       calcArea() const { return 0; }
    virtual fpreal       calcPerimeter() const { return 0; }
    /// @}

    // Is this primitive a GEO_Quadric?
    virtual bool         isQuadric() const { return false; }

    /// Convience objects to pass as arguments to saveH9()/loadH9().
    static const UT_RefArray<GA_AttribLoadDataH9> &theEmptyLoadAttribs;
    static const UT_RefArray<GA_AttribSaveDataH9> &theEmptySaveAttribs;

protected:
    /// All subclasses should call this method to register the primitive
    /// intrinsics.
    /// @see GA_IntrinsicManager
    static GA_IntrinsicManager::Registrar
                registerIntrinsics(GA_PrimitiveDefinition &defn)
                        { return GA_Primitive::registerIntrinsics(defn); }

    virtual void         copyOffsetPrimitive(const GEO_Primitive *src,
                                            int basept) = 0;
    void                 copyBasePrimitive(const GEO_Primitive *src,
                                            GEO_Point **ptredirect);
    void                 copyOffsetBasePrimitive(const GEO_Primitive *src,
                                            int basept);

    GEO_Vertex           buildVertexElement(GA_Offset vertex_offset) const;

    virtual bool         evaluatePointRefMap(GA_Offset result,
                                        GA_AttributeRefMap &map,
                                        fpreal u, fpreal v=0,
                                        uint du=0, uint dv=0) const = 0;
   
    /// Evaluate the position for the given parametric coordinates (with the
    /// given derivatives).  Return 0 if successful, or -1 if failure.
    /// The default implementation returns {0,0,0,0};
    virtual int          evaluatePointV4( UT_Vector4 &pos, float u, float v = 0,
                                        unsigned du=0, unsigned dv=0) const;

    /// By default, this will call evaluateInteriorPointRefMap with u=.5 and
    /// v=.5.  This is likely not the perfect solution.  At the current time,
    /// this is only used in POPs to birth points at primitive centers.
    virtual bool         evaluateBaryCenterRefMap(GA_Offset result, 
                                    GA_AttributeRefMap &map) const;

    virtual bool         evaluateInteriorPointRefMap(GA_Offset result,
                                        GA_AttributeRefMap &map,
                                        fpreal u, fpreal v, fpreal w = 0) const;
    virtual int          evaluateInteriorPointV4(UT_Vector4 &pos, 
                                       fpreal u, fpreal v, fpreal w = 0) const;

private:
    friend class         GEO_Detail;    // Allow detail to get at private stuff

    // TODO: Eliminate, deprecate, or switch to saving json format.
    friend ostream      &operator<<(ostream &os, const GEO_Primitive &d)
                        {
                            d.saveH9(os, 0,
                                     GEO_Primitive::theEmptySaveAttribs,
                                     GEO_Primitive::theEmptySaveAttribs);
                            return os;
                        }
};
#endif

---