dox: updating the range section of raster 3D main page and documenting compression variables

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@57781 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/raster3d/defaults.c

@@ -21,7 +21,24 @@
 
 /*---------------------------------------------------------------------------*/
 
+/*!
+\brief Name of the environmental variable specifying that compression
+       should be used.
+
+       Setting the environmental variable to any value will cause that the
+       compression will be used (set when calling Rast3d_init_defaults
+       for the first time).
+
+       This environmental variable takes precedence before the environmental
+       variable specified by RASTER3D_COMPRESSION_ENV_VAR_NO.
+*/
 #define RASTER3D_COMPRESSION_ENV_VAR_YES "RASTER3D_USE_COMPRESSION"
+/*!
+\brief Name of the environmental variable specifying that compression
+       should not be used.
+
+       \see RASTER3D_COMPRESSION_ENV_VAR_YES
+*/
 #define RASTER3D_COMPRESSION_ENV_VAR_NO "RASTER3D_NO_COMPRESSION"
 
 #define RASTER3D_PRECISION_ENV_VAR "RASTER3D_PRECISION"
@@ -63,15 +80,16 @@ int g3d_vertical_unit_default = U_UNDEFINED;
  * \brief set compression mode
  *
  * <em>doCompress</em> should be one of RASTER3D_NO_COMPRESSION and
- * RASTER3D_COMPRESSION, <em>doRle</em> should be either RASTER3D_NO_RLE or
- * RASTER3D_USE_RLE, and <em>precision</em> should be either RASTER3D_MAX_PRECISION or
- * a positive integer.
+ * RASTER3D_COMPRESSION. <em>precision</em> should be either
+ * RASTER3D_MAX_PRECISION or a positive integer.
  *
- *  \param doCompress
- *  \param doLzw
- *  \param doRle
- *  \param precision
- *  \return void
+ * \note Note that older parameters <em>doLzw</em> and <em>doRle</em>
+ *       (RASTER3D_NO_RLE or RASTER3D_USE_RLE) are no longer in the API.
+ *
+ * Calls Rast3d_fatal_error() if a wrong parameter value is provided.
+ *
+ * \param doCompress specifies if a compression should be perfomed
+ * \param precision a precision of compression
  */
 
 void
@@ -95,13 +113,15 @@ Rast3d_set_compression_mode(int doCompress, int precision)
 
 
 /*!
- * \brief get compression mode
+ * \brief Gets compression mode
  *
- *  \param doCompress
- *  \param doLzw
- *  \param doRle
- *  \param precision
- *  \return void
+ * \param doCompress pointer to the integer where the compression mode will
+ *        be stored
+ * \param precision pointer to the integer where the precision mode will
+ *        be stored
+ *
+ * \see Rast3d_set_compression_mode, RASTER3D_COMPRESSION_ENV_VAR_YES,
+        RASTER3D_COMPRESSION_ENV_VAR_YES
  */
 
 void

lib/raster3d/range.c

@@ -102,11 +102,9 @@ Rast3d_read_range(const char *name, const char *mapset, struct FPRange *drange)
 
 
 /*!
- * \brief 
- *
- *  Loads the range into the range structure of <em>map</em>.
+ * \brief Loads the range into the range structure of <em>map</em>.
  *
- *  \param map
+ *  \param map a pointer to a raster 3D map object
  *  \return 1 ... if successful
  *          0 ... otherwise.
  */
@@ -126,15 +124,12 @@ int Rast3d_range_load(RASTER3D_Map * map)
 
 
 /*!
- * \brief 
+ * \brief Returns in <em>min</em> and <em>max</em> the minimum and maximum values of
+ *        the range.
  *
- * Returns in <em>min</em> and <em>max</em> the minimum and maximum values of
- * the range.
- *
- *  \param map
- *  \param min
- *  \param max
- *  \return void
+ *  \param map a pointer to a raster 3D map object
+ *  \param min a pointer to a double to store minumim
+ *  \param max a pointer to a double to store maximum
  */
 
 void Rast3d_range_min_max(RASTER3D_Map * map, double *min, double *max)
@@ -191,7 +186,6 @@ static int writeRange(const char *name, struct FPRange *range)
  *  \return 1 ... if successful
  *          0 ... otherwise.
  */
-
 int Rast3d_range_write(RASTER3D_Map * map)
 {
     char path[GPATH_MAX];

lib/raster3d/raster3dlib.dox

@@ -5,6 +5,8 @@
 
 <i>TODO: Update for this page for GRASS 7.</i>
 
+\tableofcontents
+
 \section raster3dlib_Overview Overview
 
 The 3D Raster Volume Library is used for the <tt>r3.*</tt> and vector
@@ -1322,40 +1324,22 @@ int Rast3d_computeClippedTileDimensions(void *map, int tileIndex, int
 
 \subsection RASTER3D_Range_Support RASTER3D Range Support
 
-<P>
-The map structure of RASTER3D provides storage for the range.  The range of a map is
-updated every time a cell is written to the file. When an old map is opened the
-range is not automatically loaded. The application has to invoke
-<TT>Rast3d_range_load()</TT> (cf. Section 22.4.12)
- explicitly.
-In addition to this function, the application can also use the standard GRASS
-functions to manipulate the range.
+The map structure RASTER3D_Map provides storage for the range. The range of
+a map is updated every time a cell is written to the file. When an old map is
+opened the range is not automatically loaded. The application has to invoke
+Rast3d_range_load() explicitly. Alternatively, an application can use
+the Rast3d_read_range() function and FPRange structure to read the range.
 
-<P>
-int Rast3d_range_load(void *map)
-Loads the range into the range structure of <EM>map</EM>.
+Rast3d_range_min_max() is used to get the minimum and maximum values of the
+map range into integer.
 
-<P>
-Returns
-        1 ... if successful
-        0 ... otherwise.
-
-<P>
-void Rast3d_range_min_max(void *map, double *min, double *max)
-        Returns in <EM>min</EM> and <EM>max</EM> the minimum and maximum values of
-        the range.
+Rast3d_range_write() function stores the range in file and is invoked
+automatically when a new map is closed.
 
-<P>
-int Rast3d_range_write(void *map)
-Writes the range which is stored in the range structure of <EM>map</EM>. 
-(This function is invoked automatically when a new file is closed).
-
-<P>
-Returns
-        1 ... if successful
-        0 ... otherwise.
-
-<P>
+In addition to these functions, the application can also use some of the
+standard GRASS 2D raster functions to manipulate the floating point range. It
+is preferred to use <tt>Rast3d_</tt> functions if possible and importantly it is
+not possible to use functions for reading and writing.
 
 \subsection RASTER3D_Color_Support RASTER3D Color Support