Class MeshTempData
See Also: Class Mesh, Class AdjEdgeList, Class FaceClusterList, Template Class Tab.
class MeshTempData : public BaseInterfaceServer
Description:
This class is available in release 3.0 and later only.
This is a class for caching winged edge lists, face adjacency lists, face and edge clusters, vertex normals, and other derived data about a mesh.
There is a SetMesh() method to set the current mesh that the TempData is based on, then there's a series of methods to update the cache and return some sort of derived data. All of these methods follow the form:
DerivedData *MeshTempData::DData (parameters);
DerivedData is the container for the derived data requested (often a simple table, though there are some specialized classes returned from some methods). If the data has already been computed, the parameters are ignored and the cached data is returned. Otherwise, the data is computed from the parameters and the current mesh.
There are no procedures in place to detect changes in parameters or the mesh since the last time a method was called, so it's the calling routine's responsibility to free invalid structures. If you know that only certain pipeline channel, such as GEOM_CHANNEL, have changed, you can use the Invalidate(DWORD partsChanged) method. (GEOM_CHANNEL would free the distances-to-selected-vertices, for example, but not the Adjacent Edge List.)
In particular, there is no way for the MeshTempData to know when its mesh pointer is no longer valid, so it's vital that the calling routine clear the mesh (with SetMesh(NULL)) or stop using the MeshTempData when this happens.
All data members are private. They basically consist of a series of pointers which are initialized to NULL and then filled with allocated derived data as requested. There is also a NULL-initialized, private mesh pointer which is set with SetMesh().
Editable Mesh and Edit Mesh both use this class to hold all the varieties of temporary, cached data they create -- examples are vertex normals and face clusters. This is called "ETTempData" in Editable Mesh and "EMTempData" in Edit Mesh.
To use MeshTempData, just set it to your mesh and start asking for stuff:
MyAlgorithm (Mesh *m) {
MeshTempData mtd(m);
// Get Adjacent Edge List.
AdjEdgeList ae = mtd.AdjEList ();
}
Methods Groups:
The hyperlinks below take you to the start of groups of related methods within the class:
Initialization and Class methods
Data Members:
public:
Initialization and Class methods
Prototype:
MeshTempData();
Remarks:
Constructor. Sets all data members to NULL.
Prototype:
MeshTempData(Mesh *m);
Remarks:
Constructor. Sets the internal mesh pointer to the mesh passed.
Parameters:
Mesh *m
The mesh to set.
Prototype:
~MeshTempData();
Remarks:
Destructor. Frees all cached data.
Prototype:
void SetMesh(Mesh *m);
Remarks:
Sets the internal mesh pointer to m.
Parameters:
Mesh *m
Points to the mesh to set.
Prototype:
AdjEdgeList *AdjEList();
Remarks:
Returns an adjacent edge list. See class AdjEdgeList for more information. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh.
Prototype:
AdjFaceList *AdjFList();
Remarks:
Returns an adjacent face list. See class AdjFaceList for more information. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh.
Prototype:
FaceClusterList *FaceClusters();
Remarks:
Returns a face cluster list, which groups selected faces into "clusters" for transformation. See class FaceClusterList for more information. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh.
Prototype:
EdgeClusterList *EdgeClusters();
Remarks:
Returns an edge cluster list, which groups selected edges into "clusters" for transformation. See class EdgeClusterList for more information. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh.
Prototype:
Tab<DWORD> *VertexClusters(DWORD sl);
Remarks:
Returns an index of which cluster, if any, each vertex is in. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameter.
Parameters:
DWORD sl
Selection level. This should be either MESH_EDGE or MESH_FACE, to indicate whether the vertex cluster information should be based on edge or face clusters. Note that this parameter is ignored if there's already a vertex cluster cache.
Return Value:
A table of DWORD's is returned, one for each vertex. If (*VertexClusters(sl))[i] is UNDEFINED, vertex i is not in any cluster. Otherwise, the value for vertex i is the cluster index.
Prototype:
Tab<Point3> *ClusterNormals(DWORD sl);
Remarks:
Returns average normals for each cluster. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameter. Note that cluster centers and normals are computed and cached at the same time, when you call either method.
Parameters:
DWORD sl
Selection level. This should be either MESH_EDGE or MESH_FACE, to indicate whether the clusters we're talking about are the edge or face clusters. Note that this parameter is ignored if there's already a cluster normal cache.
Return Value:
A table of Point3's is returned, one for each cluster. The values are already normalized to length 1.
Prototype:
Tab<Point3> *ClusterCenters(DWORD sl);
Remarks:
Returns mean centers for each cluster. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameter. Note that cluster centers and normals are computed and cached at the same time, when you call either method.
Parameters:
DWORD sl
Selection level. This should be either MESH_EDGE or MESH_FACE, to indicate whether the clusters we're talking about are the edge or face clusters. Note that this parameter is ignored if there's already a cluster center cache.
Return Value:
A table of Point3's is returned, one for each cluster.
Prototype:
Matrix3 ClusterTM(int clust);
Remarks:
Uses the current cluster center and normal caches to return the "objectspace to clusterspace" transform. This is the tranform of the "local" axis in moving edge or face clusters in Edit(able) Mesh. If the cluster centers & normals have not been cached, the identity matrix is returned; thus the control over whether this is an edge or face cluster is handled by the last call to ClusterCenters or ClusterNormals.
Parameters:
int clust
The cluster you want the transform for.
Prototype:
Tab<Point3> *VertexNormals();
Remarks:
Returns a table of local average normals for vertices. This is equivalent to the average normals computed by the standalone function:
void AverageVertexNormals(Mesh & mesh, Tab<Point3> & vnormals)
If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh.
Prototype:
Tab<float> *VSWeight(BOOL useEdgeDist, int edgeIts, BOOL ignoreBack, float falloff, float pinch, float bubble);
Remarks:
Returns Vertex Selection weights (for affect region). If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameters. Weights are based on an Affect Region type falloff from the current selection.
Parameters:
BOOL useEdgeDist
If useEdgeDist is TRUE, the distance between vertices is computed along edges. If FALSE, it's computed directly through space.
int edgeIts
This indicates the maximum number of edges the algorithm may travel along in finding the distance between vertices. (Maximum path length.)
WARNING: If useEdgeDist is FALSE, this is an n-squared algorithm: it compares every vertex not in the cluster with every vertex in it. If useEdgeDist is TRUE, the time it takes is proportional to the number of verts in the cluster times edgeIts.
BOOL ignoreBack
If TRUE, vertices with a normal (as computed in VertexNormals) that points more than 90 degrees away from the average normal of theselection are not given any partial selections. They're either 1 if selected or 0 otherwise.
float falloff
The limit distance of the effect. If distance > falloff, the function will always return 0.
float pinch
Use this to affect the tangency of the curve near distance=0. Positive values produce a pointed tip, with a negative slope at 0, while negative values produce a dimple, with positive slope.
float bubble
Use this to change the curvature of the function. A value of 1.0 produces a half-dome. As you reduce this value, the sides of the dome slope more steeply. Negative values lower the base of the curve below 0.
Return Value:
Returns a table of float values, one per vertex, that are 1.0 if the vertex is in the current selection, 0.0 if it's more than falloff distance (or more than edgeIts edges, if (useEdgeDist)), and AffectRegionFunction((*SelectionDist(useEdgeDist, edgeIts)), falloff, pinch, bubble) otherwise.
Prototype:
Tab<float> *SelectionDist(BOOL useEdgeDist, int edgeIts);
Remarks:
Computes the current distance of each vertex from the current selection. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameters. The term "Selected verts" below refers to the vertices that are selected in the mesh's current selection level. (See the Mesh method GetTempSel for details.)
Parameters:
BOOL useEdgeDist
If TRUE, the distance between vertices is computed along edges. If FALSE, it's computed directly through space.
int edgeIts
This indicates the maximum number of edges the algorithm may travel along in finding the distance between vertices. (Maximum path length.).
WARNING: If useEdgeDist is FALSE, this is an n-squared algorithm: it compares every nonselected vertex with every selected one. If useEdgeDist is TRUE, the time it takes is proportional to the number of selected vertices times edgeIts.
Return Value:
A table consisting of one float value per vertex. If this value is 0, the vertex is either selected or on top of a selected vertex. Otherwise it represents the distance to the closest selected vertex. If useEdgeDist is TRUE, values of -1.0 are returned for vertices with no edgeIts-length path to a selected vertex.
Prototype:
Tab<float> *ClusterDist(DWORD sl, int clustId, BOOL useEdgeDist, int edgeIts);
Remarks:
Computes the current distance of each vertex from the specifed cluster. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameters.
Parameters:
DWORD sl
Indicates whether we should use edges (MESH_EDGE) or faces (MESH_FACE) to construct the clusters, if needed.
int clustId
The index of the cluster we're weasuring distance from.
BOOL useEdgeDist
If useEdgeDist is TRUE, the distance between vertices is computed along edges. If FALSE, it's computed directly through space.
int edgeIts
This indicates the maximum number of edges the algorithm may travel along in finding the distance between vertices. (Maximum path length.)
WARNING: If useEdgeDist is FALSE, this is an n-squared algorithm: it compares every vertex not in the cluster with every vertex in it. If useEdgeDist is TRUE, the time it takes is proportional to the number of verts in the cluster times edgeIts.
Return Value:
A table consisting of one float value per vertex. If this value is 0, the vertex is either selected or on top of a vertex in the cluster. Otherwise it represents the distance to the closest selected vertex. If useEdgeDist is TRUE, values of -1.0 are returned for vertices with no edgeIts-length path to a vertex in the cluster.
Prototype:
Tab<Point3> *EdgeExtDir(Tab<Point3> *edir, int extrusionType);
Remarks:
Returns the direction each vertex should be going, after a topological edge extrusion, to handle the geometric extrusion. This should be obtained after applying a MeshDelta::ExtrudeEdges() to the mesh to obtain valid results. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameters.
Parameters:
Tab<Point3> *edir
This should be the edge direction table filled out by MeshDelta::ExtrudeEdges. It is necessary.
int extrusionType
This is one of MESH_EXTRUDE_CLUSTER or MESH_EXTRUDE_LOCAL, to indicate whether vertices should move according to cluster or local face normals.
Return Value:
A table of Point3's, one per vertex, representing the direction each vertex should move for further extrusion. The size of each nonzero entry is set to 1.
Prototype:
Tab<Point3> *FaceExtDir(int extrusionType);
Remarks:
Returns the direction each vertex should be going, after a topological face extrusion, to handle the geometric extrusion. This should be obtained after applying a MeshDelta::ExtrudeFaces to the mesh to obtain valid results. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameters.
Parameters:
int extrusionType
This is one of MESH_EXTRUDE_CLUSTER or MESH_EXTRUDE_LOCAL, to indicate whether vertices should move according to cluster or local face normals.
Return Value:
A table of Point3's, one per vertex, representing the direction each vertex should move for further extrusion. The size of each nonzero entry is set to 1.
Prototype:
Tab<Point3> *CurrentExtDir();
Remarks:
This computes nothing; it merely returns the current extrusion direction cache, if any. The extrusion direction is controlled by the first call to EdgeExtDir or FaceExtDir since the last invalidation. If cached, the cache is returned. Otherwise a cache is allocated and computed from the current mesh and the parameters.
Prototype:
Tab<Point3> *OutlineDir(int extrusionType);
Remarks:
This produces the "Outline" direction of all vertices, based on the current face selection. "Outlining" is the direction vertices move to move edges of the current face selection outward at a constant rate. They are not set to length 1, but rather to whatever "rate" best makes the outline edges movemost consistently, without changing their angles.
Parameters:
int extrusionType
This is one of MESH_EXTRUDE_CLUSTER or MESH_EXTRUDE_LOCAL, to indicate whether vertices should move according to cluster or local face normals.
Prototype:
MeshChamferData *ChamferData();
Remarks:
Returns the cache of a ChamferData for use in the MeshDelta methods,
void ChamferEdges (Mesh & m, BitArray eset, MeshChamferData &mcd, AdjEdgeList *ae=NULL);
void ChamferMove (Mesh & m, MeshChamferData &mcd, float amount, AdjEdgeList *ae=NULL);
void ChamferVertices (Mesh & m, BitArray vset, MeshChamferData &mcd, AdjEdgeList *ae=NULL);
Unlike other MeshTempData methods, this method makes no calculations based on the current mesh, but merely supplies a memory cache.
Prototype:
void Invalidate(DWORD part);
Remarks:
Invalidates all data based on the specified part of the mesh. In the following chart, the columns represent the channels GEOM_CHANNEL (G), TOPO_CHANNEL (T), SELECT_CHANNEL (S), and SUBSEL_TYPE_CHANNEL (U).
X's indicate dependency of the specified data cache on the given channel.
Method to get cache G T S U
AdjEList X
AdjFList X
FaceClusters X X
EdgeClusters X X
VertexClusters X X X
ClusterCenters X X X X
ClusterNormals X X X X
VertexNormals X X
SelectionDist X X X X
ClusterDist X X X X
VSWeight X X X X
The extrusion direction methods could also be said to be dependent on all four channels, but is currently handled separately in freeBevelInfo. ChamferData is handled in freeChamferData, and is not based on the
cached mesh.
Sample use: Suppose you use a MeshDelta to modify a mesh, twice:
DoStuffToMesh (Mesh & m) {
MeshTempData foo;
foo.SetMesh (&m);
MeshDelta md(m);
md.Op1 (m, foo.AdjEList()); // insert op of choice here
md.Apply (m);
foo.Invalidate (md.PartsChanged ());
md.ClearAllOps ();
md.Op2 (m, foo.VSWeights ());
md.Apply (m);
foo.Invalidate (md.PartsChanged ());
}
Only the parts of foo that are dependent on what was changed by the first meshdelta are freed. The other parts, if any, remain cached for further operations.
Parameters:
DWORD part
One or more of the following channels:
GEOM_CHANNEL, TOPO_CHANNEL, SELECT_CHANNEL, SUBSEL_TYPE_CHANNEL
Prototype:
void InvalidateDistances();
Remarks:
Uncaches (frees) the distance dependent data returned by VSWeight, SelectionDist, and ClusterDist.
Prototype:
void InvalidateAffectRegion();
Remarks:
Frees the VSWeight data. This is useful, e.g., if the mesh has not changed, but you wish to change the falloff, pinch, or bubble parameters to get new vertex selection weights.
Prototype:
void freeClusterDist();
Remarks:
Mainly for internal use, this frees just the cluster distance data.
Prototype:
void freeBevelInfo();
Remarks:
Frees only the extrusion direction data.
Prototype:
void freeChamferData();
Remarks:
Frees only the chamfer data structure.
Prototype:
void freeAll();
Remarks:
Frees all cached data.