requires_update_flags (const UpdateFlags update_flags) const = 0;
/**
- * Prepare internal data structures and fill in values independent of the
- * cell. See the documentation of Mapping::InternalDataBase for more
- * information on the purpose of this function.
+ * Create and return a pointer to an object into which mappings can
+ * store data that only needs to be computed once but that can then
+ * be used whenever the mapping is applied to a concrete cell (e.g.,
+ * in the various transform() functions, as well as in the
+ * fill_fe_values(), fill_fe_face_values() and fill_fe_subface_values()
+ * that form the interface of mappings with the FEValues class).
+ *
+ * Derived classes will return pointers to objects of a type
+ * derived from Mapping::InternalDataBase (see there for more information)
+ * and may pre-compute some information already (in accordance with what will
+ * be asked of the mapping in the future, as specified by the update
+ * flags) and for the given quadrature object. Subsequent calls to
+ * transform() or fill_fe_values() and friends will then receive back the
+ * object created here (with the same set of update flags and for the
+ * same quadrature object). Derived classes can therefore pre-compute
+ * some information in their get_data() function and store it in
+ * the internal data object.
+ *
+ * The mapping classes do not keep track of the objects created by
+ * this function. Ownership will therefore rest with the caller.
+ *
+ * @param update_flags A set of flags that define what is expected of
+ * the mapping class in future calls to transform() or the
+ * fill_fe_values() group of functions. This set of flags may
+ * contain flags that mappings do not know how to deal with
+ * (e.g., for information that is in fact computed by the
+ * finite element classes, such as UpdateFlags::update_values).
+ * Derived classes will need to store these flags, or at least that
+ * subset of flags that will require the mapping to perform any
+ * actions in fill_fe_values(), in InternalDataBase::update_each.
+ * @param quadrature The quadrature object for which mapping
+ * information will have to be computed. This includes the
+ * locations and weights of quadrature points.
+ * @return A pointer to a newly created object of type
+ * InternalDataBase (or a derived class). Ownership of this
+ * object passes to the calling function.
+ *
+ * @note C++ allows that virtual functions in derived classes
+ * may return pointers to objects not of type InternalDataBase
+ * but in fact pointers to objects of classes <i>derived</i>
+ * from InternalDataBase. (This feature is called "covariant return
+ * types".) This is useful in some contexts where the calling
+ * is within the derived class and will immediately make use
+ * of the returned object, knowing its real (derived) type.
*/
virtual
InternalDataBase *
const Quadrature<dim> &quadrature) const = 0;
/**
- * Prepare internal data structure for transformation of faces and fill in
- * values independent of the cell. See the documentation of
- * Mapping::InternalDataBase for more
- * information on the purpose of this function.
+ * Like get_data(), but in preparation for later calls to
+ * transform() or fill_fe_face_values() that will need
+ * information about mappings from the reference face to a
+ * face of a concrete cell.
+ *
+ * @param update_flags A set of flags that define what is expected of
+ * the mapping class in future calls to transform() or the
+ * fill_fe_values() group of functions. This set of flags may
+ * contain flags that mappings do not know how to deal with
+ * (e.g., for information that is in fact computed by the
+ * finite element classes, such as UpdateFlags::update_values).
+ * Derived classes will need to store these flags, or at least that
+ * subset of flags that will require the mapping to perform any
+ * actions in fill_fe_values(), in InternalDataBase::update_each.
+ * @param quadrature The quadrature object for which mapping
+ * information will have to be computed. This includes the
+ * locations and weights of quadrature points.
+ * @return A pointer to a newly created object of type
+ * InternalDataBase (or a derived class). Ownership of this
+ * object passes to the calling function.
+ *
+ * @note C++ allows that virtual functions in derived classes
+ * may return pointers to objects not of type InternalDataBase
+ * but in fact pointers to objects of classes <i>derived</i>
+ * from InternalDataBase. (This feature is called "covariant return
+ * types".) This is useful in some contexts where the calling
+ * is within the derived class and will immediately make use
+ * of the returned object, knowing its real (derived) type.
*/
virtual
InternalDataBase *
const Quadrature<dim-1> &quadrature) const = 0;
/**
- * Prepare internal data structure for transformation of children of faces
- * and fill in values independent of the cell. See the documentation
- * of Mapping::InternalDataBase for more
- * information on the purpose of this function.
+ * Like get_data() and get_face_data(), but in preparation for later calls to
+ * transform() or fill_fe_subface_values() that will need
+ * information about mappings from the reference face to a
+ * child of a face (i.e., subface) of a concrete cell.
+ *
+ * @param update_flags A set of flags that define what is expected of
+ * the mapping class in future calls to transform() or the
+ * fill_fe_values() group of functions. This set of flags may
+ * contain flags that mappings do not know how to deal with
+ * (e.g., for information that is in fact computed by the
+ * finite element classes, such as UpdateFlags::update_values).
+ * Derived classes will need to store these flags, or at least that
+ * subset of flags that will require the mapping to perform any
+ * actions in fill_fe_values(), in InternalDataBase::update_each.
+ * @param quadrature The quadrature object for which mapping
+ * information will have to be computed. This includes the
+ * locations and weights of quadrature points.
+ * @return A pointer to a newly created object of type
+ * InternalDataBase (or a derived class). Ownership of this
+ * object passes to the calling function.
+ *
+ * @note C++ allows that virtual functions in derived classes
+ * may return pointers to objects not of type InternalDataBase
+ * but in fact pointers to objects of classes <i>derived</i>
+ * from InternalDataBase. (This feature is called "covariant return
+ * types".) This is useful in some contexts where the calling
+ * is within the derived class and will immediately make use
+ * of the returned object, knowing its real (derived) type.
*/
virtual
InternalDataBase *
public:
/**
- * @name Functions usable by finite element fields to map points and tensors
+ * @name Functions to transform tensors from reference to real coordinates
* @{
*/
compute_shapes_virtual (const std::vector<Point<dim> > &unit_points,
typename MappingFEField<dim, spacedim>::InternalData &data) const;
- /**
- * Implementation of the corresponding function in the base class,
- * Mapping::requires_update_flags(). See there for more information.
- */
+ // documentation can be found in Mapping::requires_update_flags()
virtual
UpdateFlags
requires_update_flags (const UpdateFlags update_flags) const;
const unsigned int n_original_q_points,
InternalData &data) const;
- /**
- * Reimplemented from Mapping. See the documentation of the base class for
- * detailed information.
- */
+ // documentation can be found in Mapping::get_data()
virtual
InternalData *
get_data (const UpdateFlags,
const Quadrature<dim> &quadrature) const;
- /**
- * Reimplemented from Mapping. See the documentation of the base class for
- * detailed information.
- */
+ // documentation can be found in Mapping::get_face_data()
virtual
typename Mapping<dim,spacedim>::InternalDataBase *
get_face_data (const UpdateFlags flags,
const Quadrature<dim-1>& quadrature) const;
- /**
- * Reimplemented from Mapping. See the documentation of the base class for
- * detailed information.
- */
+ // documentation can be found in Mapping::get_subface_data()
virtual
typename Mapping<dim,spacedim>::InternalDataBase *
get_subface_data (const UpdateFlags flags,
* Storage for internal data of d-linear mappings. See Mapping::InternalDataBase
* for an extensive description.
*
- * This includes data that is computed once when the object is created
+ * For the current class MappingQ1, the InternalData class store
+ * data that is computed once when the object is created
* (in get_data()) as well as data the class wants to store from between
* the call to fill_fe_values(), fill_fe_face_values(), or
* fill_fe_subface_values() until possible later calls from the finite
private:
- /**
- * Implementation of the corresponding function in the base class,
- * Mapping::requires_update_flags(). See there for more information.
- */
+ // documentation can be found in Mapping::requires_update_flags()
virtual
UpdateFlags
requires_update_flags (const UpdateFlags update_flags) const;
- /**
- * Implementation of the Mapping::get_data() interface.
- *
- * As allowed by C++ (using a feature called "covariant return
- * types"), this function returns a pointer to a
- * MappingQ1::InternalData object since these objects are
- * derived from the Mapping::InternalDataBase class, pointers to
- * which are returned by the Mapping::get_data() function. This
- * makes some uses of this function simpler.
- */
+ // documentation can be found in Mapping::get_data()
virtual
InternalData *
get_data (const UpdateFlags,
const Quadrature<dim> &quadrature) const;
+ // documentation can be found in Mapping::get_face_data()
virtual
typename Mapping<dim,spacedim>::InternalDataBase *
get_face_data (const UpdateFlags flags,
const Quadrature<dim-1>& quadrature) const;
+ // documentation can be found in Mapping::get_subface_data()
virtual
typename Mapping<dim,spacedim>::InternalDataBase *
get_subface_data (const UpdateFlags flags,
projects / dealii.git / commitdiff