vcglib/docs/Doxygen/attributes.dxy

45 lines
2.8 KiB
Plaintext
Raw Normal View History

/** \page attributes
User-defined attributes
=======================
VCG Lib also provides a simple mechanism to associate user-defined 'attributes' to the simplicies and to the mesh.
Note that both 'attributes' and 'components' are basically accessory data that are bound to a simplex.
Conceptually the difference is that with the term component VCGLib indicates those values that are considered to 'define' the simplex (its position, its normal its connectivity information), while the user defined attribute is an accessory data which make sense to some specific algorithm, like "the number of time a vertex has been moved" or "a pointer to a string containing a description of the vertex".
Practically the difference is that every optional component has its non optional counterpart and is accessed through a member function of the simplex, so that when you write your algorithm you use v.N() to access the normal both it is has been declared as optional or not, while the attributes are accessed by a handle which is returned at the creation of the attribute.
The following code snippet shows an example:
\dontinclude trimesh_attribute.cpp
\skip include
\until main
\until }
You also have functions to check if a given attribute exists, retrieve an handle for it and eventually deleting it (using the handle or by name).
Do not get mix up the scope of the handle with the memory allocation of the attribute. If you do not delete an attribute explicitly, it will be allocated until the mesh itself is destroyed, even if you do not have handles to it.
\until }
The same can be done for the faces, just replace the occurences of PerVertex with PerFace.
Note that if you call add an attribute without specifying a name and you lose the handle, you will not be able to get your handle back.
Note:
C++ type of a mesh and reflection
---------------------------------
VCG Lib provides a set of functions to implement reflection, i.e. to investigate the type of a mesh at runtime. These functions follow the format Has[attribute](mesh) and return a boolean stating if that particular attribute is present or not.
\code
template<class ComputeMeshType>
static void UpdateNormals<ComputeMeshType>::PerVertex(ComputeMeshType &m)
{
if( !HasPerVertexNormal(m)) return;
...
}
\endcode
You may wonder why those functions are not statically typed and why they needs the mesh object, i.e. why can't you just write ComputeMeshType::HasPerVertexNormal()? The reason is that VCG Lib reflection takes into account optional components, therefore HasPerVertexNormal(m) will return true if the type of the vertex contains the attribute as permanent (e.g. vcg::vertex::Normal3f) OR if it contains the attribute as optional (e.g. vcg::vertex::Normal3fOcf) AND it is enabled, i.e. the relative Enable function has been called.
*/