* in the interior of the unit line, square, or cube.
* </dd>
*
+ *
+ * <dt class="glossary">@anchor GlossUserFlags <b>User flags</b></dt>
+ * <dd>
+ * A triangulation offers one bit per line, quad, etc for user flags.
+ * This field can be
+ * accessed as all other data using iterators, using the syntax
+ * @code
+ * cell->set_user_flag(); // set the user flag of a cell
+ * if (cell->user_flag_set() == false) // if cell hasn't been flagged yet
+ * {
+ * cell->face(0)->set_user_flag(); // flag its first face
+ * }
+ * @endcode
+ * Typically, this user flag is
+ * used if an algorithm walks over all cells and needs information whether
+ * another cell, e.g. a neighbor, has already been processed. Similarly,
+ * it can be used to flag faces, quads or lines at the boundary for which
+ * some operation has already been performed. The latter is often useful
+ * since a loop such as
+ * @code
+ * // in 3d
+ * for (cell=dof_handler.begin_active();
+ * cell!=dof_handler.end(); ++cell)
+ * for (unsigned int line=0; line<GeometryInfo<dim>::lines_per_cell; ++l)
+ * if (cell->line(l)->at_boundary())
+ * {
+ * do something with this line
+ * }
+ * @endcode
+ * encounters some boundary lines more than once. Consequently, one would
+ * set the user flag of the line in the body of the loop, and only enter the
+ * body if the user flag had not previously been set. There are a number of
+ * additional functions that can be accessed through the iterator interface;
+ * see the TriaAccessor class for more information. Note that there are no
+ * user flags that can be associated with vertices; however, since vertices
+ * are numbered consecutively, this can easily be emulated in user code
+ * using a vector of bools.
+ *
+ * There are two functions, Triangulation::save_user_flags and
+ * Triangulation::load_user_flags which
+ * write and read these flags to and from a stream or a vector of bools. Unlike
+ * Triangulation::save_refine_flags and Triangulation::load_refine_flags,
+ * these two functions store
+ * and read the flags of all used lines, quads, etc, i.e., not only of the
+ * active ones.
+ *
+ * If you want to store more specific user flags, you can use the functions
+ * Triangulation::save_user_flags_line and Triangulation::load_user_flags_line
+ * and the similarly for quads, etc.
+ *
+ * As for the refinement and coarsening flags, there exist two versions of these
+ * functions, one which reads/writes from a stream and one which does so from
+ * a <tt>vector@<bool@></tt>. The latter is used to store flags temporarily, while the
+ * first is used to store them in a file.
+ *
+ * It is good practice to clear the user flags using the
+ * Triangulation::clear_user_flags() function before usage, since it is
+ * often necessary to use the flags in more than one function. If the flags may
+ * be in use at the time a function that needs them is called, then this function
+ * should save and restore the flags as described above.
+ *
+ * @note If more information than just a single boolean flag needs to be stored
+ * with a cell, line, or face, then see about @ref GlossUserData "user data".
+ * </dd>
+ *
+ *
+ * <dt class="glossary">@anchor GlossUserData <b>User pointers and user indices</b></dt>
+ * <dd>
+ * Just like the @ref GlossUserFlags "user flags", the Triangulation class offers a
+ * field for each line, quad and hex in which to store more descriptive data than just
+ * a single boolean flag. This is called "user data" and the data that can be stored
+ * in it is either a single unsigned integer or a void pointer. Both are typically
+ * used to index into a bigger array that contains more detailed data an application
+ * wants to attach to a mesh entity.
+ *
+ * User data is stored and retrieved in the following manner:
+ * @code
+ * for (cell=dof_handler.begin_active();
+ * cell!=dof_handler.end(); ++cell)
+ * for (unsigned int line=0; line<GeometryInfo<dim>::lines_per_cell; ++l)
+ * if (cell->line(l)->at_boundary())
+ * {
+ * cell->line(l)->set_user_index(42);
+ * }
+ * @endcode
+ * Similarly, there are functions TriaAccessor::set_user_pointer to set a pointer, and
+ * TriaAccessor::user_index and TriaAccessor::user_pointer to retrieve the index
+ * and pointer. To clear all user indices or pointers, use Triangulation::clear_user_data().
+ * As with flags, there are functions that allow to save and restore user data,
+ * either for all entities of the mesh hierarchy or for lines, quads or hexes
+ * separately. There are a number of additional functions that can be accessed
+ * through the iterator interface; see the TriaAccessor class for more information.
+ *
+ * @note User pointers and user indices are stored in the same
+ * place. In order to avoid unwanted conversions, Triangulation
+ * checks which one of them is in use and does not allow access to
+ * the other one, until Triangulation::clear_user_data() has been called.
+ *
+ * @note The usual warning about the missing type safety of @p void pointers are
+ * obviously in place here; responsibility for correctness of types etc
+ * lies entirely with the user of the pointer.
+ * </dd>
+ *
* </dl>
*/
* This field can be
* accessed as all other data using iterators. Normally, this user flag is
* used if an algorithm walks over all cells and needs information whether
- * another cell, e.g. a neighbor, has already been processed. It can also
- * be used to flag the lines subject to constraints in 2D, as for example the
- * functions in the DoFHandler classes do.
- *
- * There are two functions, @p save_user_flags and @p load_user_flags which
- * write and read these flags to and from a stream. Unlike
- * @p save_refine_flags and @p load_refine_flags, these two functions store
- * and read the flags of all used lines, quads, etc, not only of the
- * active ones (well, activity is a concept which really only applies to
- * cells, not for example to lines in 2D, so the abovementioned generalization
- * to <em>all</em> lines, quads, etc seems plausible).
- *
- * If you want to store more specific user flags, you can use the functions
- * @p save_user_flags_line and @p load_user_flags_line and the generalizations
- * for quads, etc.
- *
- * As for the refinement and coarsening flags, there exist two versions of these
- * functions, one which reads/writes from a stream and one which does so from
- * a <tt>vector<bool></tt>. The latter is used to store flags temporarily, while the
- * first is used to store them in a file.
- *
- * It is convention to clear the user flags using the
- * <tt>Triangulation<>::clear_user_flags()</tt> function before usage, since it is
- * often necessary to use the flags in more than one function consecutively and
- * is then error prone to dedicate one of these to clear the flags.
- *
- * It is recommended that a functions using the flags states so in
- * its documentation. For example, the
- * execute_coarsening_and_refinement() function uses some of the user
- * flags and will therefore destroy any content stored in them.
+ * another cell, e.g. a neighbor, has already been processed.
+ * See @ref GlossUserFlags "the glossary for more information".
*
* There is another set of user data, which can be either an
* <tt>unsigned int</tt> or a <tt>void *</tt>, for
* each line, quad, etc. You can access these through
* the functions listed under <tt>User data</tt> in
- * the accessor classes. These pointers are not used nor changed in
- * many places of the library, and those classes and functions that
- * do use them should document this clearly; the most prominent user
- * of these pointers is the SolutionTransfer class which uses the
- * cell->user_pointers.
+ * the accessor classes.
+ * Again, see @ref GlossUserData "the glossary for more information".
*
* The value of these user indices or pointers is @p NULL by default. Note that
* the pointers are not inherited to children upon
* refinement. Still, after a remeshing they are available on all
- * cells, where they were set on the previous mesh (unless, of
- * course, overwritten by the SolutionTransfer class).
+ * cells, where they were set on the previous mesh.
*
* The usual warning about the missing type safety of @p void pointers are
* obviously in place here; responsibility for correctness of types etc
* checks which one of them is in use and does not allow access to
* the other one, until clear_user_data() has been called.
*
- * Just like the user flags, this field is not available for vertices,
- * which does no harm since the vertices have a unique and continuous number
- * unlike the structured objects lines and quads.
- *
*
* <h3>Boundary approximation</h3>
*
/*@{*/
/**
* Clear all user flags.
+ * See also @ref GlossUserFlags .
*/
void clear_user_flags ();
* and the documentation for the
* @p save_refine_flags for more
* details.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags (std::ostream &out) const;
/**
- * Same as above, but store the flags to
- * a bitvector rather than to a file.
- * The output vector is resized if
- * necessary.
+ * Same as above, but store the flags to
+ * a bitvector rather than to a file.
+ * The output vector is resized if
+ * necessary.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags (std::vector<bool> &v) const;
/**
* Read the information stored by
* @p save_user_flags.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags (std::istream &in);
/**
* Read the information stored by
* @p save_user_flags.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags (const std::vector<bool> &v);
/**
* Clear all user flags on lines.
+ * See also @ref GlossUserFlags .
*/
void clear_user_flags_line ();
/**
* Save the user flags on lines.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags_line (std::ostream &out) const;
* a bitvector rather than to a file.
* The output vector is resized if
* necessary.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags_line (std::vector<bool> &v) const;
/**
* Load the user flags located on lines.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags_line (std::istream &in);
/**
* Load the user flags located on lines.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags_line (const std::vector<bool> &v);
/**
* Clear all user flags on quads.
+ * See also @ref GlossUserFlags .
*/
void clear_user_flags_quad ();
/**
* Save the user flags on quads.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags_quad (std::ostream &out) const;
* a bitvector rather than to a file.
* The output vector is resized if
* necessary.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags_quad (std::vector<bool> &v) const;
/**
* Load the user flags located on quads.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags_quad (std::istream &in);
/**
* Load the user flags located on quads.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags_quad (const std::vector<bool> &v);
/**
- * Clear all user flags on quads.
+ * Clear all user flags on quads.
+ * See also @ref GlossUserFlags .
*/
void clear_user_flags_hex ();
/**
* Save the user flags on hexs.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags_hex (std::ostream &out) const;
* a bitvector rather than to a file.
* The output vector is resized if
* necessary.
+ * See also @ref GlossUserFlags .
*/
void save_user_flags_hex (std::vector<bool> &v) const;
/**
* Load the user flags located on hexs.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags_hex (std::istream &in);
/**
* Load the user flags located on hexs.
+ * See also @ref GlossUserFlags .
*/
void load_user_flags_hex (const std::vector<bool> &v);
* Clear all user pointers and
* indices and allow the use of
* both for next access.
+ * See also @ref GlossUserData .
*/
void clear_user_data ();
* clear_user_data() instead.
*
* Clear all user pointers.
+ * See also @ref GlossUserData .
*/
void clear_user_pointers ();
* Save all user indices. The
* output vector is resized if
* necessary.
+ * See also @ref GlossUserData .
*/
void save_user_indices (std::vector<unsigned int> &v) const;
/**
* Read the information stored by
* save_user_indices().
+ * See also @ref GlossUserData .
*/
void load_user_indices (const std::vector<unsigned int> &v);
* Save all user pointers. The
* output vector is resized if
* necessary.
+ * See also @ref GlossUserData .
*/
void save_user_pointers (std::vector<void *> &v) const;
/**
* Read the information stored by
* save_user_pointers().
+ * See also @ref GlossUserData .
*/
void load_user_pointers (const std::vector<void *> &v);
* Save the user indices on
* lines. The output vector is
* resized if necessary.
+ * See also @ref GlossUserData .
*/
void save_user_indices_line (std::vector<unsigned int> &v) const;
/**
* Load the user indices located
* on lines.
+ * See also @ref GlossUserData .
*/
void load_user_indices_line (const std::vector<unsigned int> &v);
* Save the user indices on
* quads. The output vector is
* resized if necessary.
+ * See also @ref GlossUserData .
*/
void save_user_indices_quad (std::vector<unsigned int> &v) const;
/**
* Load the user indices located
* on quads.
+ * See also @ref GlossUserData .
*/
void load_user_indices_quad (const std::vector<unsigned int> &v);
* Save the user indices on
* hexes. The output vector is
* resized if necessary.
+ * See also @ref GlossUserData .
*/
void save_user_indices_hex (std::vector<unsigned int> &v) const;
/**
* Load the user indices located
* on hexs.
+ * See also @ref GlossUserData .
*/
void load_user_indices_hex (const std::vector<unsigned int> &v);
/**
* Save the user indices on
* lines. The output vector is
* resized if necessary.
+ * See also @ref GlossUserData .
*/
void save_user_pointers_line (std::vector<void *> &v) const;
/**
* Load the user pointers located
* on lines.
+ * See also @ref GlossUserData .
*/
void load_user_pointers_line (const std::vector<void *> &v);
* Save the user pointers on
* quads. The output vector is
* resized if necessary.
+ * See also @ref GlossUserData .
*/
void save_user_pointers_quad (std::vector<void *> &v) const;
/**
* Load the user pointers located
* on quads.
+ * See also @ref GlossUserData .
*/
void load_user_pointers_quad (const std::vector<void *> &v);
* Save the user pointers on
* hexes. The output vector is
* resized if necessary.
+ * See also @ref GlossUserData .
*/
void save_user_pointers_hex (std::vector<void *> &v) const;
/**
* Load the user pointers located
* on hexs.
+ * See also @ref GlossUserData .
*/
void load_user_pointers_hex (const std::vector<void *> &v);
/*@}*/
*/
/**
* Read the user flag.
+ * See @ref GlossUserFlags for more information.
*/
bool user_flag_set () const;
/**
* Set the user flag.
+ * See @ref GlossUserFlags for more information.
*/
void set_user_flag () const;
/**
* Clear the user flag.
+ * See @ref GlossUserFlags for more information.
*/
void clear_user_flag () const;
/**
* Set the user flag for this
* and all descendants.
+ * See @ref GlossUserFlags for more information.
*/
void recursively_set_user_flag () const;
/**
* Clear the user flag for this
* and all descendants.
+ * See @ref GlossUserFlags for more information.
*/
void recursively_clear_user_flag () const;
/**
* Reset the user data to zero,
* independent if pointer or index.
+ * See @ref GlossUserData for more information.
*/
void clear_user_data () const;
* you call
* Triangulation::clear_user_data()
* in between.
+ *
+ * See @ref GlossUserData for more information.
*/
void set_user_pointer (void *p) const;
/**
* Reset the user pointer
* to a @p NULL pointer.
+ * See @ref GlossUserData for more information.
*/
void clear_user_pointer () const;
* Triangulation::clear_user_data()
* in between.
* <tt>A *a=static_cast<A*>(cell->user_pointer());</tt>.
+ *
+ * See @ref GlossUserData for more information.
*/
void * user_pointer () const;
* you call
* Triangulation::clear_user_data()
* in between.
+ *
+ * See @ref GlossUserData for more information.
*/
void recursively_set_user_pointer (void *p) const;
* said for the
* recursively_set_user_pointer()
* function.
+ * See @ref GlossUserData for more information.
*/
void recursively_clear_user_pointer () const;
* you call
* Triangulation::clear_user_data()
* in between.
+ * See @ref GlossUserData for more information.
*/
void set_user_index (const unsigned int p) const;
/**
* Reset the user index to 0.
+ * See @ref GlossUserData for more information.
*/
void clear_user_index () const;
* you call
* Triangulation::clear_user_data()
* in between.
+ *
+ * See @ref GlossUserData for more information.
*/
unsigned int user_index () const;
* you call
* Triangulation::clear_user_data()
* in between.
+ *
+ * See @ref GlossUserData for more information.
*/
void recursively_set_user_index (const unsigned int p) const;
* said for the
* recursively_set_user_index()
* function.
+ *
+ * See @ref GlossUserData for more information.
*/
void recursively_clear_user_index () const;
/**
projects / dealii-svn.git / commitdiff