The ITAPS Mesh Interface iMesh
The ITAPS Mesh Interface iMesh provides a common interface for accessing mesh and data associated with a mesh. Applications written to use this interface can use a variety of implementations, choosing the one that best meets its needs. They can also use tools written to this interface, for example mesh smoothing, adaptive mesh refinement, and parallel mesh support.
The ITAPS interfaces use a data model composed of four basic data types:
basic topological entities in a mesh, e.g. vertices, triangles, hexahedra.
arbitrary grouping of other entities and sets. Entity sets also support parent/child relations with other sets which are distinct from entities contained in those sets. Parent/child links can be used to embed graph relationships between sets, e.g. to represent topological relationships between the sets.
the object with which mesh is associated and on which functions in iMesh are called.
application data associated with objects of any of the other data types. Each tag has a designated name, size, and data type.
Each entity has a specific Entity Type and Entity Topology. The Entity Type is one of VERTEX, EDGE, FACE, and REGION, and is synonymous with the topological dimension of the entity. The Entity Topology denotes the specific shape, for example TRIANGLE, QUADRILATERAL, TETRAHEDRON, and HEXAHEDRON. Entity Type and Entity Topology exist as enumerated types, Entity Type in the iBase_EntityType enumeration, and Entity Topology in the iMesh_EntityTopology enumeration.
The iMesh interface provides functions for accessing entities individually, as arrays of entities, or using iterators. These access methods have different memory versus execution time tradeoffs, depending on the implementation.
Many of the functions in iMesh have arguments corresponding to lists of objects. In-type arguments for lists consist of a pointer to an array and a list size. Lists returned from functions are passed in three arguments, a pointer to the array representing the list, and pointers to the allocated and occupied lengths of the array. These three arguments are inout-type arguments, because they can be allocated by the application and passed into the interface to hold the results of the function. Lists which are pre-allocated must be large enough to hold the results of the function; if this is not the case, an error is generated. Otherwise, the occupied size is changed to the size output from the function. If a list argument is unallocated (the list pointer points to a NULL value) or if the incoming value of the allocated size is zero, the list storage will be allocated by the implementation. IN ALL CASES, MEMORY ALLOCATED BY ITAPS INTERFACE IMPLEMENTATIONS IS DONE USING THE C MALLOC FUNCTION, AND CAN BE DE-ALLOCATED USING THE C FREE FUNCTION.
Many of the functions in iMesh can return arrays of tuples; that is, arrays of multi-valued type. For example, the function iMesh_getVtxArrCoords, returns an array of xyz coordinate 3-tuples (or, perhaps for geometrically 2D meshes, xy 2-tuples). In these situations, there are multiple ways the data can be organized in memory. For example, it could be stored xyz,xyz,xyz or xxx...,yyy...,zzz.... These two different storage orders are referred to as INTERLEAVED and BLOCKED, repsectively. For some functions in iMesh, the storage order is explicitly specified as an argument to the function. For other functions, the storage order is not explicitly specified. And, in these cases, it shall always be implicitly assumed to be INTERLEAVED. This fact will be mentioned in the documentation for each specific function where it applies. For example, in the case of iMesh_getEntArrAdj, the returned array of adjacent entities is multi-valued in that it stores for each entity queried, all its adjacent entities. Such an array will be stored INTERLEAVED with all adjacent entities for the first entity in the query followed by all adjacent entities for the second entity in the query and so forth.