vcglib/docs/Doxygen/optional_component.dxy

50 lines
2.4 KiB
Plaintext
Raw Normal View History

/** \page optional_component
Optional Component
===
There are many cases where some vertex or face attributes (like for example the Face-Face adjacency) are not necessary all the time.
VCG Lib gives you a way to specify optional components, i.e. attributes that are not statically stored within the simplex but can be
dynamically allocated only when you need them. Their use is totally transparent with respect to the standard, statically allocated components.
To 'define' optional component you need to do two things:
- to use a special type of container (derived from std::vector) in the mesh definition
- to specify the right type of component in the simplex definition
An optional component can be used only when it is 'enabled', e.g. when the memory for it has been allocated.
An optional component can be enable by calling the function Enable.
VCG Lib handles optional components with two alternative mechanisms: the first is called 'Ocf' (for Optional Component Fast)
which uses one pointer for each simplex but it makes accessing optional attribute almost as fast as non-optional ones;
the second is called 'Occ' (for Optional Component Compact) which only requires a little extra space for each mesh
(unrelated to its size in terms of number of simplicies) but which can result in a slower access.
In the following, only their use is discussed. The implementation detail can be found here.
Optional Component Fast
---
The following definition of MyMesh specifies that a few components of the vertex and face types are optional.
Note that the special attribute vcg::vertex::InfoOcf and vcg::face::InfoOcf are the first attribute of vertex and face types and that we
use the vcg::vertex::vector_ocf and vcg::face::vector_ocf as containers;
\dontinclude trimesh_optional.cpp
\skip MyVertexOcf
\until MyMeshOcf
Before accessing the data contained in the optional component you must enable that attribute by calling EnableXXX() corresponding function;
afterwards the space for the component will be allocated and accessible until you call again DisableXXXX().
\dontinclude trimesh_optional.cpp
\skip cmof
\until cmof
\skip HasFFAdjacency
\until true
Trying to access the value of a unallocated component before enabling or after disabling the corresponding component
will throw an assertion.
\dontinclude trimesh_optional.cpp
\skip EnableNormal
\until UpdateNormal
\sa trimesh_optional.cpp
*/