KERNEL OF THE SYSTEM - CLASS HIERARCHY
Naming conventions
In the kernel of the system names of macros, types and functions start with
the prefix MT_.
In the whole package, class names are of the form XXXClass,
and name XXX denotes the type of a pointer to the class.
Macro MT_INDEX denotes the type used for indexing vertices and
tiles, nodes and arcs in an MT.
Basic Classes: the MT and attributes
MT_PersistentClass
Abstract class.
Meaning
A class of objects that can read / write themselves according to
the standard file format of the MT package.
An object of this class has a keyword (that will depend on the specific
subclass) and an object description used when writing the object on a file.
Functions
- char * MT_ClassKeyword(void): return the keyword of this
class.
- void MT_SetDescription(char * s): set the string describing
this object, string s must be at most MT_DESCR_LEN
characters long.
- vchar * MT_TheDescription(void): return the string describing
this object.
- void MT_TheDescription(char * s): return a copy of the
description string, string s must be long enough.
- int MT_Read(FILE * fd): read this object from given file,
return 1 on success, 0 on failure.
- void MT_Write(FILE * fd, int file_encoding = MT_ASCII_ENCODING):
write this object on given file, file_encoding
determines the file format: MT_ASCII_ENCODING (default) or
MT_BINARY_ENCODING.
MT_TileSetClass
Subclass of MT_PersistentClass.
Meaning
A class of objects made up of vertices and tiles.
Tiles are k-dimensional, and vertices are embedded in
d-dimensional space, for generic k and d.
The implementation sets an upper bound of 10
for k and d.
Constructor
Parameters: the dimension of the embedding space
(= number of coordinates for each vertex), and the dimension of the tiles
(= number of vertices for each tile, minus one).
The resulting tile set has no vertices and no tiles.
A tile set must read its contents from a file.
Functions
This class provides functions to access the geometry of vertices and tiles.
Vertices are described as tuples of coordinates, and tiles as tuples of
vertices.
Elements inside a tuple are indexed starting from zero.
Both vertices and tiles are referenced as MT_INDEXes.
Valid MT_INDEXes start from 1, the value 0
(macro MT_NULL_INDEX) is used for denoting "no vertex" or "no tile".
- Global information:
- int MT_VertexDim(void): return the dimension of the
embedding space.
- int MT_TileDim(void): return the dimension of the tiles.
- int MT_NumTileVertices(void): return the number of vertices
for each tile.
- MT_INDEX MT_VertexNum(void): return the number of vertices
in this object.
- MT_INDEX MT_TileNum(void): return the number of tiles in
this object.
- void MT_BoundingBox(float * min_values, float * max_values):
fill the two given arrays with the minima and the maxima, respectively,
of vertex coordinates; the two
arrays must have at least MT_VertexDim() positions each.
- void MT_CoordRange(int i, float * min_v, float * max_v):
return the minimum and maximum of the i-th coordinate among
all vertices, i must be between 0 and
MT_VertexDim()-1.
- float MT_MinCoord(int i), float MT_MaxCoord(int i):
return the minimum and the maximum value of the i-th
coordinate among all vertices, i
must be between 0 and MT_VertexDim()-1.
- float MT_MinX(void), float MT_MinY(void),
float MT_MinZ(void):
return the minimum of the first, second, and third coordinate,
make sure that to call MT_MinZ only if
MT_VertexDim()>=3.
- float MT_MaxX(void), float MT_MaxY(void), float MT_MaxZ(void):
return the maximum value of the first, second, and third coordinate,
make sure that to call MT_MaxZ only if
MT_VertexDim()>=3.
- Information for vertices:
- void MT_VertexCoords(MT_INDEX v, float ** f),
float * MT_VertexCoords(MT_INDEX v):
return a pointer to the array of coordinates of vertex v.
- void MT_CopyVertexCoords(MT_INDEX v, float * f): copy the
coordinates of vertex v into array f,
f must have at least MT_vertexDim() positions.
- float MT_VertexCoord(MT_INDEX v, int i):
return the i-th coordinate of v, i must be between
0 and MT_TileVertexDim()-1.
- float MT_VertexX(MT_INDEX v), float MT_VertexY(MT_INDEX v),
float MT_VertexZ(MT_INDEX v): return the first, second, and third
coordinate of vertex v, make sure that to call
MT_VertexZ only if MT_VertexDim()>=3.
- Information for tiles:
- void MT_TileVertices(MT_INDEX t, MT_INDEX ** v),
MT_INDEX * MT_TileVertices(MT_INDEX t):
return a pointer to the array of vertices of tile t.
- void MT_CopyTileVertices(MT_INDEX t, MT_INDEX * v):
copy the vertices of tile t into array v, v must
have at least MT_NumTileVertices() positions.
- int MT_TileVertexPosition(MT_INDEX t, MT_INDEX v):
if v is a vertex of t,
return the index of v in tile
t, otherwise, return -1.
- int MT_OppositeVertexPosition(MT_INDEX t,
MT_INDEX t1, int i1):
if tile t1 is adjacent to t along the face opposite
to its i1-th vertex, then return the index in tile t
of the vertex of t which is not in t1;
otherwise, return -1.
MT_MultiTesselationClass
Subclass of MT_TileSetClass.
Meaning
A Multi-Tesselation. It adds a DAG to a tile set.
Constructor
Parameters: the dimension of the embedding space, and the dimension of the
tiles (the same as for class MT_TileSetClass).
The resulting MT is empty. An MT must read its contents from a file.
Functions
Functions to navigate the DAG are used within the extractors, and are
of no interest for the user.
Only the following functions may be of interest:
- MT_INDEX MT_ArcNum(void): return the number of arcs in this MT.
- MT_INDEX MT_NodeNum(void): return the number of nodes in this MT.
MT_AttrTableClass
Abstract class,
subclass of MT_PersistentClass.
Meaning
A table that stores a value (of some type that is not specified at this
level) associated with each entity (vertex, tile) of an MT.
Subclasses of the generic attribute table will be defined for storing
values of a specific type (e.g., float, int, etc.).
Such subclasses will enrich the interface with
access functions for getting and setting the attribute values.
Functions
- MT_INDEX MT_AttrNum(void): return the number of attributes
stored in this table.
- int MT_ReadAttr (FILE * fd, MT_INDEX i, int file_encoding):
read the attribute for the i-th entity.
- void MT_WriteAttr(FILE * fd, MT_INDEX i, int file_encoding):
write the attribute for the i-th entity.
- Functions to set and get the attribute of an entity
will be added in the subclasses.
Classes for extracting tesselations
MT_CondClass
Meaning
A boolean function on the tiles of an MT.
Conditions are used within an extractor for driving the extraction of
tesselations from an MT.
It is an abstract class.
The condition can be interpreted as:
- a resolution condition (deciding when a tile is refined enough,
called a feasible tile)
- a focus condition (deciding when a tile is of interest,
called an active tile).
Subclasses of MT_CondClass implement specific resolution conditions
and focus conditions.
There are two modes for evaluating the condition:
- loose evaluation:
used inside extraction algorithms
- strict evaluation:
used on the tiles of the extracted tesselation
The loose evaluation assumes that the condition is applied to tiles that
are not at full resolution; thus, their spatial location can be slightly
different from the location of the object portion that they approximate.
The strict evaluation assumes that the condition is applied to tiles that
are - if not at full resolution - at a resolution considered as sufficient
by the application; thus, their distance from the represented object
portion is negligible.
For instance, a condition selecting the tiles which contain a given
point, evaluated on an MT where each tile has an associated approximation
error measuring its distance from the object portion it represents:
- loose evaluation tests whether a tile "may contain" the point, taking
also the error into account
- strict evaluation is the standard point-in-tile test
Functions
- int MT_EvalCond(MT_MultiTesselation m, MT_INDEX t, int flag):
evaluate the condition on a tile,
return 1 if tile t satisfies the condition,
0 otherwise.
flag is either MT_LOOSE or MT_STRICT,
and determines the evaluation mode.
- int MT_IsGood(MT_MultiTesselation m):
return 1 if this condition can be applied to MT m,
0 otherwise
(some conditions may require MTs with tiles of a certain
dimension, or embedded in a space of a certain dimension).
MT_ExtractorClass
Abstract class.
Meaning
A class of objects which extract tesselations from an MT given
a resolution filter condition and a focus condition.
MT_ExtractorClass has three subclasses which implement
extraction through specific algorithms:
- MT_StaticExtractorClass: use the global static
extraction algorithm
- MT_DynamicExtractorClass: use the global dynamic
extraction algorithm
- MT_LocalExtractorClass:
use the local (static) extraction algorithm
An extractor may output the extracted tesselation simply as a list of
tiles, or may also generate information about mutually adjacent tiles.
Reconstruction of adjacency links between extracted tiles is a feature
that must be set when creating the extractor. By default, it
is disabled.
An extractor may also generate statistics about the performance of the
extraction algorithm. Such feature may be enabled and disabled at run
time.
Constructor
Parameters: the MT from which tesselations will be extracted, and a boolean
flag specifying if the extractor must generate adjacency information for the
extracted tesselation (default = disabled).
Functions
- Extracting a tesselation:
- MT_MultiTesselation MT_TheMT(void): return the working MT.
- int MT_SetFilter(MT_Cond flt): set the resolution filter
condition; if flt is NULL, then no condition is set
(all tiles are feasible);
return 1 if successful, 0 otherwise.
- int MT_SetFocus(MT_Cond fcs): set the focus condition;
if fcs is NULL, then no condition is set
(all tiles are active);
return 1 if successful, 0 otherwise.
- MT_Cond MT_TheFilter(void): return the current resolution filter
condition.
- MT_Cond MT_TheFocus(void): return the current focus condition.
- int MT_ExtractTesselation(void): extract a tesselation based on the
current resolution filter and focus condition, the algorithm used
depends on the specific class of extractor;
return the number of extracted tiles.
- Access to the extracted tesselation:
- int MT_ExtractedTiles(MT_INDEX ** t_arr):
return a pointer to an internal array of the extractor
containing the extracted active tiles; return the array size.
- MT_INDEX MT_ExtractedTilesNum(void):
return the number of active tiles in the last extracted tesselation.
- MT_INDEX MT_AllExtractedTiles(MT_INDEX ** t_arr): return
a pointer to an internal array of the extractor
containing all the extracted tiles (active tiles first,
followed by non-active ones); return the array size.
- MT_INDEX MT_AllExtractedTilesNum(void): return the total
number of tiles in the last extracted tesselation.
- MT_INDEX MT_AllExtractedTiles(MT_INDEX ** t_arr1, MT_INDEX * size1,
MT_INDEX ** t_arr2, MT_INDEX * size2):
return pointers to two internal arrays of the extractor containing
the extracted active and non-active tiles, respectively, and the sizes
of such arrays; return the total size of the two arrays.
- MT_INDEX MT_TileAdj(MT_INDEX t, int i): if reconstruction of
adjacency links in the extracted tesselation is enabled, return the
tile adjacent to t along the face oppostite to the
i-th vertex of t.
- MT_INDEX * MT_TileAdjs(MT_INDEX t): if reconstruction of
adjacency links in the extracted tesselation is enabled, return a
pointer to the array of tiles adjacent to t (the i-th tile
is the one adjacent along the face oppostite to the
i-th vertex of t).
- void MT_CopyTileAdjs(MT_INDEX tMT_INDEX * ta): as above,
but make a copy of the array into array ta.
- int MT_AdjGenerationEnabled(void): return 1 if
reconstruction of adjacency links in the extracted tesselation is
enabled, 0 otherwise.
- Extraction statistics:
- void MT_EnableStat(void), void MT_DisableStat(void):
enable / disable generation of statistic information
about the extraction algorithm.
- int MT_StatEnabled(void): return 1
if statistics are enabled, 0 otherwise.
- MT_INDEX MT_VisitedNodes(void): return the
number of nodes added to or removed from the consistent
set of updates during the last extraction query.
- MT_INDEX MT_UsedNodes(void): return the
number of nodes in the consistent set of updates resulting from
the last extraction query.
- MT_INDEX MT_TestedNodes(void): return the
number of nodes tested as candidate for being removed
from the consistent set (only for dynamic extractor).
- MT_INDEX MT_VisitedTiles(void): return the
number of tiles in the portion of DAG visited by the extraction
algorithm.
- MT_INDEX MT_TestedTiles(void): return the
number of tiles tested against the extraction conditions.
Classes for building an MT
MT_BuildingBaseClass
Meaning
Base class containing information which must be inherited by the MT
building interface and by the user-defined building interfaces of
MT feaures.
Functions
The following functions connect an attribute building interface
for vertex or tile attributes to this object.
- void ConnectVertexAttrBuilder(MT_AttrBuildingInterface abi):
connect abi as a vertex attribute building interface.
- void ConnectTileAttrBuilder(MT_AttrBuildingInterface abi):
connect abi as a tile attribute building interface.
MT_BuildingInterfaceClass
Subclass of MT_PersistentClass
and of MT_BuildingBaseClass.
Meaning
This class provides functions for recording the sequence updates performed on
a tesselation during a process of refinement or coarsening, and for building
an MT from such a sequence.
An update consists of deleting a set of tiles and creating another
set of tiles. The sequence of all updates is called a history.
Recording a history
The history is not kept in memory, but it is written on disk in some
temporary files. This allows saving memory since it is supposed that the
primary process of refinement or simplification (that generates the updates)
needs quite a lot of memory.
At the end of the recording process, one can convert the history into an MT.
Before that, it may be necessary to free all the auxiliary
data structures of the primary process of refinement/simplification in
order to gain sufficient memory.
Converting a history
First, the user must provide an MT_Multitesselation that
will contain the result of MT construction.
After the MT has been built, the building interface may be
deleted and the constructed MT is ready to be used, or to be written on
a file and used later by other programs.
Constructor
The constructor has no parameters.
Functions
- History recording:
The user program must provide a field of type MT_INDEX
associated with each
vertex and each tile used in the process of refinement or simplification.
Such field must be initialized before starting the process by setting it
to MT_NULL_INDEX.
Then, it must be only managed through the history recording functions below.
- int MT_StartHistory(int d, int k, int history_type):
start a history for a k-dimensional MT embedded in
d dimensions, history_type
is either MT_REFINING or MT_COARSENING;
return 1 on success, 0 on failure.
- MT_INDEX MT_UseVertex(MT_INDEX i, float * coord_array):
record a vertex to be used in the next tile that will be made,
coord_array contains the vertex coordinates,
i is the MT_INDEX field
of the vertex; return a new value to be assigned to the
MT_INDEX field of the vertex.
- MT_INDEX MT_MakeTile(void): record the creation of a new
tile (formed by the vertices on which MT_UseVertex has just
been called); return a value to be assigned to the MT_INDEX
field of the tile.
- int MT_KillTile(MT_INDEX i): record the deletion of a tile.
Called by passing the MT_INDEX field of the tile;
return 1 on success, 0 on failure.
- int MT_EndUpdate(void): record the fact that the update is completed;
called just after the creation of the initial tesselation, and after
each update; return 1 on success, 0 on failure.
- int MT_EndHistory(void): end the history; return 1
on success, 0 on failure.
- History conversion:
- void MT_SetTarget(MT_MultiTesselation m): set the MT to be built; it
must be called before MT_Convert.
- int MT_Convert(void): build the target MT from the history
recorded just now. First an MT must be set with MT_Target;
return 1 on success, 0 on failure.
MT_AttrBuildingInterfaceClass
Abstract class,
subclass of MT_PersistentClass.
Meaning
An interface containing functions that must be added to the MT
building interface in order to record values (of some type that is not
specified at this level) associated with its vertices/tiles.
It provides functions for recording the attributes of tiles or vertices during
the evolution of a tesselation after a sequence of local modifications, and
for building attribute tables from such information.
Subclasses of MT_AttrBuildingInterfaceClass will
record attributes of specific types.
An object of class MT_AttrBuildingInterfaceClass will not be used
alone. It will be used within a subclass of
MT_BuildingInterfaceClass in order to record attributes for the MT
that we want to build.
Recording attributes inside a history
The attribute building interface contains among its internal fields an
auxiliary attribute table, which is used for reading/writing attribute
values, thus abstracting from the specific type of attributes.
Attributes are saved on temporary files in order to
reduce memory requirements.
In subclasses, the auxiliary attribute table will point to an attribute
table, of a subclass of MT_AttrTableClass, corresponding to the
specific type of attribute.
Subclasses of MT_AttrBuildingInterfaceClass will provide functions
of the form MT_MakeAttr (with parameters that depend on the type
of attribute) for recording the attribute of an MT entity.
The attribute for a vertex/tile does not need to be recorded at the same
moment when such vertex/tile is recorded in the MT history (through a
call to MT_UseVertex and MT_MakeTile, respectively).
It can be recorded at any time afterwards (as soon as the applicative
program knows it: for instance, in surface refinement vertex normal may be
known only at the end of the refinement), and it can be recorded more than
once for the same entity.
When converting the recorded attributes, just
one attribute will be kept for each entity (the last recorded one).
Building an attribute table
At the end of attribute recording, we can build an attribute table
from the recorded attributes.
Before this, the user must provide the attribute table to be built.
After having built the attribute table, the attribute building interface
can be deleted.
Public functions
- Attribute recording:
- int MT_StartAttrHistory(void): start recording attributes.
- int MT_EndAttrHistory(void): stop recording attributes.
- A function of the fom MT_MakeAttr
will be added in the subclasses to
record the value of the attribute for an MT entity.
- Attribute table construction:
- void MT_SetTargetAttrTable(MT_AttrTable at): set the attribute
table to be built; it must be called before MT_AttrConvert.
- int MT_AttrConvert(void):
build the target attribute table from the attributes recorded just now.
Classes for Predefined Attributes
The system provides predefined classes for implementing attributes
consisting of values of type int, char, float,
for vectors of one of these types, and for XXX = one bit.
In the following, the symbol XXX denotes a type among the ones
mentioned above.
In order to implement attributes of type XXX
for an MT, we provide:
-
a subclass
of MT_AttrTableClass, storing values of type XXX.
-
a subclass of MT_AttrBuildingInterfaceClass, for recording values
of type XXX and building the XXX attribute table.
Here, we explain the contents of such classes while remaining generic about
the basic type XXX.
MT_XXXTableClass
Subclass of MT_AttrTableClass.
Meaning
An attribute table storing values of type XXX. Here, we assume that
XXX is a basic type.
It adds functions to access the attribute values.
Constructor
The constructor has no parameters. The resulting attribute table is
empty. An XXX attribute table must read its contents from a file.
Functions
- XXX MT_AttrValue(MT_INDEX i): return the attribute value
stored for MT entity (vertex or tile) i.
MT_XXXVectorTableClass
Subclass of MT_AttrTableClass.
Meaning
An attribute table storing values consisting of vectors of elements of
the basic type XXX.
It adds functions to access the attribute values.
Constructor
Parameter: the length of the vector.
The resulting attribute table is empty.
An XXXVector attribute table must read its contents from a file.
Functions
- XXX * MT_TheVector(MT_INDEX i): return a pointer to the array
associated with MT entity (vertex or tile) i.
- XXX MT_TheVectorEntry(MT_INDEX i, int j): return the
j-th entry of
the array associated with MT entity (vertex or tile) i.
MT_XXXBuildingInterfaceClass
Subclass of MT_AttrBuildingInterfaceClass.
Meaning
An attribute building interface for values of type XXX.
Simply an attribute building interface where the internal MT attribute
table points to an object of the class MT_XXXTableClass.
Constructor
The constructor has no parameters.
Functions
- int MT_MakeAttrValue(MT_INDEX i, XXX v): record the value
of the attribute for MT entity (vertex or tile) i.
- void MT_SetTargetAttrTable(MT_XXXTable at): set the
attribute table to be built.
- MT_XXXTable MT_TheAttrTable(void): return the
attribute built table.
MT_XXXVectorBuildingInterfaceClass
Subclass of MT_AttrBuildingInterfaceClass.
Meaning
An attribute building interface for values consisting of
vectors of the basic type XXX.
Simply an attribute building interface where the internal MT attribute
table points to an object of the class MT_XXXVectorTableClass.
Constructor
Parameter: the length of the vector.
Functions
- int MT_MakeAttrVector(MT_INDEX i, XXX *v): record array
v as
the attribute for MT entity (vertex or tile) i.
- void MT_SetTargetAttrTable(MT_XXXVectorTable at): set the
attribute table to be built.
- MT_XXXVectorTable MT_TheAttrTable(void): return the
attribute built table.