From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 31 Jul 2018 21:25:58 +0000 (-0600)
Subject: Document new VTK extensions and restrictions.
X-Git-Tag: v9.1.0-rc1~860^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9fa2588d970dc81660a6f8f6170016e6bbc8503d;p=dealii.git

Document new VTK extensions and restrictions.
---

diff --git a/include/deal.II/base/data_out_base.h b/include/deal.II/base/data_out_base.h
index 8ecc24f01f..d826959ed6 100644
--- a/include/deal.II/base/data_out_base.h
+++ b/include/deal.II/base/data_out_base.h
@@ -1153,6 +1153,19 @@ namespace DataOutBase
      * or as a high-order Lagrange cell.
      *
      * Default is <tt>false</tt>.
+     *
+     * @note The ability to write data that corresponds to higher
+     *   order polynomials rather than simply linear or bilinear is a
+     *   feature that was only introduced in VTK sometime in 2017 or
+     *   2018.  You will need at least Paraview version 5.5 (released
+     *   in the spring of 2018) or a similarly recent version of Visit
+     *   for this feature to work (for example, Visit 2.13.2, released
+     *   in May 2018, does not yet support this feature). Older
+     *   versions of these programs are likely going to result in
+     *   errors when trying to read files generated with this flag set
+     *   to @p true. Experience with these programs shows that these
+     *   error messages are likely going to be rather less descriptive
+     *   and more obscure.
      */
     bool write_higher_order_cells;
 
diff --git a/include/deal.II/numerics/data_out.h b/include/deal.II/numerics/data_out.h
index 3a797f4e6b..e0051930d4 100644
--- a/include/deal.II/numerics/data_out.h
+++ b/include/deal.II/numerics/data_out.h
@@ -258,6 +258,23 @@ public:
    * In other words, using this parameter can not help you plot the solution
    * exactly, but it can get you closer if you use finite elements of higher
    * polynomial degree.
+   *
+   * @note Specifying `n_subdivisions>1` is useful when using higher order
+   *   finite elements, but in general it does not actually result in the
+   *   visualization showing higher order polynomial surfaces -- rather, you
+   *   just get a (bi-, tri-)linear interpolation of that higher order
+   *   surface on a finer mesh. However, when outputting the solution in the
+   *   VTK and VTU file formats via DataOutInterface::write_vtk() or
+   *   DataOutInterface::write_vtu() (where DataOutInterface is a base
+   *   class of the current class) as we often do in the tutorials,
+   *   you can provide a set of flags via the DataOutBase::VtkFlags
+   *   structure that includes the
+   *   DataOutBase::VtkFlags::write_higher_order_cells flag. When set, the
+   *   subdivisions produced by this function will be interpreted as
+   *   support point for a higher order polynomial that will then actually
+   *   be visualized as such. On the other hand, this requires a
+   *   sufficiently new version of one of the VTK-based visualization
+   *   programs.
    */
   virtual void
   build_patches(const unsigned int n_subdivisions = 0);