GEO/GEO_Face.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_Face_H__
#define __GEO_Face_H__

#include "GEO_API.h"
#include <UT/UT_RefArray.h>
#include "GEO_Vertex.h"
#include "GEO_TriMesh.h"

class   GB_Edge;
class   GD_Face;
class   GD_Detail;
class   GEO_Detail;

class GEO_API GEO_FaceFlags {
public:
        GEO_FaceFlags() { closed = 0; }
        unsigned        closed:1;
};

#define GEO_FOR_FACE_VERTICES(face, vtx, cnt) \
        for (cnt=0; (cnt < face->getFastVertexCount()) && \
                    (vtx = &((*face)(cnt))); cnt++)

class GEO_API GEO_Face : public GEO_TriMesh {
public:
    GEO_Face(GEO_Detail *d);
    virtual ~GEO_Face();

    virtual unsigned    getPrimitiveId() const = 0;
    virtual UT_Vector3  computeNormal() const;

    virtual int         save(ostream &os, int binary) const;
    virtual bool        load(UT_IStream &is);

    virtual void        copyPrimitive(const GEO_Primitive *src, 
                                    GEO_Point **ptredirect);
    virtual GEO_Primitive       *copy(int preserve_shared_pts = 0) const;

    virtual int         isDegenerate() const;

    virtual unsigned    getOrder(void) const = 0;

    // 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;
    // and vice versa
    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 one point (when du=0), or the du-th derivative.
    // Return 0 if successful, and -1 otherwise.
    virtual bool        evaluate(fpreal u, GEO_Vertex &result,
                                 GEO_AttributeHandleList &gah,
                                 int du=0, int uOffset=-1) const;
    virtual int         evaluate(float u, UT_Vector4 &pos,
                                 unsigned du=0, int uOffset=-1) const;
    virtual int SYS_DEPRECATED evaluateWAttrib(float u, UT_Vector4 &pos,
                                     GB_AttributeData &adata,
                                     const GB_FloatOffsets &foffsets,
                                     unsigned du=0, int uOffset=-1) const;

    // Evaluate the position or the derivative at domain point (u,v), where
    // u and v MUST be in [0,1]. "v" and "dv" will be ignored here. Return 0 if
    // OK and -1 otherwise.
    // NB: evaluatePoint will return the normal to the face if dv is set.
    virtual bool         evaluatePoint(GEO_Vertex &result,
                                        GEO_AttributeHandleList &vtxdata,
                                        fpreal u, fpreal v=0,
                                        uint du=0, uint dv=0) const;
    virtual int         evaluatePoint( UT_Vector4 &pos, float u_unit, float=0,
                                       unsigned du=0, unsigned dv = 0) const;

    // NB: This will not calculate the derivitive of attributes.  Indeed,
    // if either du or dv is set, it won't alter the adata values.
    virtual int SYS_DEPRECATED evaluatePointWAttrib(UT_Vector4 &pos,
                                        GB_AttributeData &adata,
                                        const GB_FloatOffsets &foffsets,
                                        float u_unit, float=0, unsigned du = 0,
                                        unsigned = 0) const;

    virtual int          evaluateNormalVector(UT_Vector3 &nml, float u,
                                        float = 0) const;

    // Evaluaes the frenet frame at the u parameter given.  If accurate
    // is zero, the normal of the face is used for the binormal as opposed
    // to the correct value.
    virtual int         evaluateFrenetFrame(UT_Vector3 &x, 
                                UT_Vector3 &t, UT_Vector3 &m, UT_Vector3 &b, 
                                float u, int accurate = 1, int uoffset = -1) 
                                    const;

    // Another pair of face evaluators. These take a start and a stop index
    // in the valid domain and an lod representing number of points to
    // be interpolated between every two breakpoints. The methods ALWAYS
    // interpolate the encountered breakpoints (aka CVs for polys).They return
    // the number of points in the list or -1 if unsuccessful. Please save
    // yourself headaches and pass VALID start and end indices (see the
    // method validInterval()).
    virtual int         evaluateBreakSegm(int ustartidx, int ustopidx,
                            int lod, GEO_Vertex **results,
                            GEO_AttributeHandleList &hlist, unsigned du=0) const;
    virtual int         evaluateBreakSegm(int ustartidx, int ustopidx,
                            int lod, UT_Vector4 *pos, unsigned du=0) const;
    virtual int SYS_DEPRECATED evaluateBreakSegmWAttrib(int ustartidx, int ustopidx,
                            int lod, UT_Vector4 *pos,
                            GB_AttributeData *adata,
                            const GB_FloatOffsets &foffsets,
                            unsigned du=0) const;

    // Compute the location of the breakpoint. Return 0 if OK, else -1.
    virtual int         evaluateBreakpoint(int uidx, UT_Vector4 &pos,
                                           int du=0) const = 0;

    // This method takes a start and a stop index in the valid domain, a lod
    // representing number of points between every two breakpoints, an integer
    // index, and return the value of the DOMAIN of point index after the
    // domain has lod points inserted between breakpoints.
    virtual float       breakSegmIndexToDomain(int ustartidx, int ustopidx,
                            int lod, int index) const;

    //  Remove all repeated vertices - (only gets consecutive vertices)
    // checkorder refers to inspecting getOrder() and not removing repeated
    // vertices until they exceed order in count.  It has nothing to do
    // with whether the vertices are checked in order.  count_only means
    // that we return the number of repeated vertices without removing them.
    virtual int          removeRepeatedVertices(int check_order = 0,
                                                int count_only = 0);
    virtual int          removeRepeatedPoints(float tol = 0.001F,
                                              int check_order = 0,
                                              int count_only = 0);

    // Assuming the face is closed, "unroll" it so that the CVs that are
    // shared to form a wrapped curve are made unique. Also, the face becomes
    // open. The base class method only flips the open flag. If the face is
    // not closed, the method returns -1. Otherwise it returns 0.
    virtual int         unroll(int append_pts = 1);


    // Raise the number of CVs to match the newcount. The shape of the face
    // (especially if parametric) should NOT change. Return 0 upon success
    // and -1 otherwise.  start and stop define which indices to examine
    // if newcount is negative it is taken as a relative value.
    virtual int         loft(int newcount, int start=-1, int stop=-1) = 0;


    // Given a parameter in the face domain, insert as many CVs as necessary 
    // to create a discontinuity at the corresponding point on the face. The 
    // shape of the face should NOT change. Return u's index upon success 
    // and -1  otherwise.
    virtual int         subdivide(float u, GEO_AttributeHandleList &hl);
    virtual int         subdivide(float u);
    virtual int SYS_DEPRECATED subdivideWAttrib(float u,
                                         const GB_FloatOffsets &foffsets);

    // Warp the curve at u by the given delta. Change 1 or 2 Cvs and possibly
    // insert a knot once or more as well. If a knot is inserted or we happen
    // to land exactly on a knot, we change only one CV. The bias makes sense
    // only when changing 2 CVs, and will be ignored altogether if < 0.
    // We return the index of the affected knot in the sequence, or -1 if
    // there's an error.
    virtual int          warp(float u, const UT_Vector3 &delta,
                              GEO_AttributeHandleList &hlist,
                              float sharpness = 0.0f, float bias = -1.0f) = 0;
    virtual int SYS_DEPRECATED warp(float u, const UT_Vector3 &delta,
                              GB_FloatOffsets *foffsets = 0,
                              float sharpness = 0.0f, float bias = -1.0f) = 0;

    // Warp the face along its normal at u. Return the index of the afected
    // knot in the sequence, or -1 if there's an error.
    int                 warpAlongNormal(float u, float distance,
                                GEO_AttributeHandleList &hlist,
                                float sharpness, float bias);
    int SYS_DEPRECATED warpAlongNormal(float u, float distance,
                                         GB_FloatOffsets *foffsets,
                                         float sharpness, float bias);

    // Append another face to us in one of two ways: blend the two endpoints
    // or connect them straight or rounded. The bias ranges from 0 to 1 and is
    // relevant only to blending. The tolerance for blending: if 0, the two
    // endpoints will merge into one point with a discontinuity; if less than
    // 1, we insert knots into the curves to minimize the affected areas; if 1,
    // no refinement is done. For the non-blend case, the tolerance will
    // generate a span whose shape goes from round to straight; 0 tolerance
    // means straight connection. If unrefine is on, we'll try to reduce the
    // complexity of the face if we're connecting rounded. We return 0 if OK
    // and -1 if error. Both curves must be open and have the same order.
    virtual int         attach(const GEO_Face &face, int blend = 1,
                               float bias = 0.5f, float tolerance = 1.0f,
                               int unrefine=1, GB_PointGroup *ptgroup=0) = 0;

    // Build a planar (domain) face of the same type as us and with the same
    // number of vertices. Copying the (x,y) values of our points to the planar
    // face is optional.
    virtual GD_Face     *planar(GD_Detail &dgdp, int copyxy = 0) const = 0;

    // Go from a normalized domain ([0,1]) to the real domain or vice versa.
    virtual float       unitToRealDomain(float u_unit) const;
    virtual float       realToUnitDomain(float u_real) const;
    
    // Map the normalized length (distance value [0,1]) parameter to the unit 
    // parameterization of the primitve. The tolerance specifies max
    // error of the returned value (cannot be 0.0f).
    virtual float        unitLengthToUnitDomain(float  ulength,
                                                float tolerance = 1e-04F) const;

    virtual float        unitToUnitLengthDomain(float  uparm ) const;


    // Calculate the real domains for n consecutive operations on the domain
    // given n normalized domains and the operation
    // Here the real domain ranges from 0 to vertexcount - 1 + isClosed().
    virtual void        unitToRealSequence(float *uunit, float *ureal, 
                                int ulen) const;
    static void         unitToRealAdjust(float *uunit, float *ureal, 
                                int ulen, int num);

    // Return the bounds of the valid evaluation interval in domain space:
    // For polygons this refers to cv indices.
    virtual void        validInterval(int &a, int &b) const;
    virtual void        validRange(float &ua, float &ub) const;

    unsigned             isClosed() const { return flags.closed; }
    virtual void         close(int rounded = 1, int preserveShape = 0);
    virtual void         open(int preserveShape = 0, int safe = 0);

    virtual int          hasEdge(const GEO_Point &a, const GEO_Point &b) const;
    virtual int          hasEdge(const GB_Edge &edge) const;

    // Methods to handle vertex attributes for the attribute dictionary
    virtual void         edgeApply(GEO_EdgeApplyFunc apply, void  *data = 0);
    virtual void         edgeApplyIndex(GEO_EdgeApplyIndexFunc apply,
                                        void  *data = 0);

    // Returns the number of edges on this face.
    int                  getEdgeCount() const;

    // Reverses the vertices of a given face. It's virtual because some faces,
    // such as rational splines, need to be aware of it.
    virtual void         reverse();

    // Append n points equally spaced between the 1st and last vertex.
    void                 sampleEnds(int n);

    // Shift the array of vertices by an offset and wrap around. The offset
    // can be either negative or positive.
    virtual int          cycle(int amount, int = 1);

    // Find the center and radius of the face
    float                radius() const;

    // Finds which vertex#'s the given points have.  The points should make
    // an edge.
    // Returns 0 if the points do not define an edge on this face,
    // 1 if they do (in which case pidx0 and pidx1 are the vertex#'s)
    virtual int          findEdgePoints(const GEO_Point &a, const GEO_Point &b,
                                        int *pidx0, int *pidx1) const;
    virtual int          findEdgePoints(const GB_Edge &edge,
                                        int *pidx0, int *pidx1) const;


    // True if the directed edge a->b is in this face.
    bool                 hasDEdge(const GEO_Point &a, const GEO_Point &b) const;

    /// True if both the directed edges a->b and b->a are inside this
    /// face
    bool                 isBridge(const GEO_Point &a, const GEO_Point &b) const;

    // Change the multiplicity of the domain value by inserting it after
    // checking its current multiplicity.  Return -1 if invalid, otherwise
    // return the index of the inserted knot

    virtual int         refine(fpreal k, GEO_AttributeHandleList &gah, int i=0);
    virtual int         refine (float k, int=0);
    virtual int SYS_DEPRECATED refineWAttrib (float k,
                                const GB_FloatOffsets &foffsets, int=0);


    // Find enclosing integral values(c1, c2) which validly enclose c
    // and return the distance to c1
    static fpreal       getIndices(fpreal c, int &c1, int &c2, 
                                   int maxIndex, int wrap);


    /// This method determines whether the point is inside or outside the
    /// polygon.  The point is assumed to be on the plane of the polygon.
    /// Note that normal is a pointer to this primitive's normal which cannot
    /// be NULL.
    /// If the point is on the boundary of the face, it is reported as being
    /// inside the face with -1 return.
    virtual int         pointInFace(const UT_Vector3 &pos,
                                    const UT_Vector3 *normal) const;

    // Find distance in parameter space, aware of wrapping.
    virtual float        uvDist(float u1, float v1, float u2, float v2) const;

    // Do nothing for poly's
    virtual void        weights(unsigned short onOff);
    virtual int         breakCount() const = 0;

    virtual float       calcVolume(UT_Vector3 &refpt) const;
    virtual float       calcArea() const;
    virtual float       calcPerimeter() const;

protected:
    virtual void        copyOffsetPrimitive(const GEO_Primitive *src, int base);

    // Methods for finding out about point references
    virtual int  savePrivate(ostream &os, int binary) const = 0;
    virtual bool loadPrivate(UT_IStream &is) = 0;
    virtual int  pointCanDelete(GB_Element *) const;
    virtual void pointDeleted(GB_Element *pt);

    // Check the validity of the data. Meant to be called especially at loading
    // time. The method returns 1 if OK and 0 if trouble.
    virtual bool         validate(void) const;

    GEO_FaceFlags               flags;


private:

    friend ostream      &operator<<(ostream &os, const GEO_Face &d)
                        {
                            d.save(os, 0);
                            return os;
                        }
};
#endif

---