Doxygen

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

lib/display/cnversions.c

@@ -51,22 +51,6 @@ static struct vector U_to_D_conv;	/* UTM to Display   */
 /* others */
 static int is_lat_lon;
 
-/*!
- * \brief initialize conversions
- *
- * The relationship between the
- * earth <b>region</b> and the <b>top, bottom, left</b>, and <b>right</b>
- * screen coordinates is established, which then allows conversions between all
- * three coordinate systems to be performed.
- * Note this routine is called by <i>D_setup.</i>
- *
- *  \param region
- *  \param top
- *  \param bottom
- *  \param left
- *  \param right
- *  \return int
- */
 
 static void calc_size(struct rect *rect)
 {
@@ -150,6 +134,21 @@ void D_show_conversions(void)
 	    U_to_D_conv.x, U_to_D_conv.y);
 }
 
+/*!
+ * \brief initialize conversions
+ *
+ * The relationship between the earth <b>region</b> and the <b>top, bottom,
+ * left</b>, and <b>right</b> screen coordinates is established, which then
+ * allows conversions between all three coordinate systems to be performed.
+ * Note this routine is called by <i>D_setup</i>.
+ *
+ *  \param region
+ *  \param top
+ *  \param bottom
+ *  \param left
+ *  \param right
+ *  \return none
+ */
 void D_do_conversions(const struct Cell_head *window,
 		      double t, double b, double l, double r)
 {
@@ -162,6 +161,7 @@ void D_do_conversions(const struct Cell_head *window,
 #endif /* DEBUG */
 }
 
+
 int D_is_lat_lon(void)			{    return (is_lat_lon);		}
 
 double D_get_d_to_a_xconv(void)		{    return (D_to_A_conv.x);		}
@@ -211,6 +211,18 @@ void D_set_src(double t, double b, double l, double r)
     calc_size(&U);
 }
 
+/*!
+ * \brief returns frame bounds in source coordinate system
+ *
+ * D_get_src() returns the frame bounds in the source coordinate system
+ * (used by D_* functions)
+ *
+ *  \param top
+ *  \param bottom
+ *  \param left
+ *  \param right
+ *  \return void
+ */
 void D_get_src(double *t, double *b, double *l, double *r)
 {
     *t = U.north;
@@ -245,6 +257,20 @@ void D_set_dst(double t, double b, double l, double r)
     calc_size(&D);
 }
 
+/*!
+ * \brief returns frame bounds in destination coordinate system
+ *
+ * D_get_dst() returns the frame bounds in the destination coordinate system
+ * (used by R_* commands).
+ * The various D_setup() commands all set the destination coordinate
+ * system to the current frame reported by R_get_window().
+ *
+ *  \param top
+ *  \param bottom
+ *  \param left
+ *  \param right
+ *  \return none
+ */
 void D_get_dst(double *t, double *b, double *l, double *r)
 {
     *t = D.north;

lib/display/setup.c

@@ -3,15 +3,6 @@
  * This is a high level D call.
  * It does a full setup for the current graphics frame.
  *
- *   1. Makes sure there is a current graphics frame
- *      (will create a full-screen one, if not
- *   2. Sets the region coordinates so that the graphics frame
- *      and the active program region agree
- *      (may change active program region to do this).
- *   3. Performs graphic frame/region coordinate conversion intialization
- *
- * Returns: 0 if ok. Exits with error message if failure.
- *
  * Note: Connection to driver must already be made.
  *
  * clear values:
@@ -23,22 +14,27 @@
 #include <grass/display.h>
 #include <grass/raster.h>
 
+
 /*!
  * \brief graphics frame setup
  *
- * Performs a full setup
- * for the current graphics frame: 1) Makes sure there is a current graphics
- * frame (will create a full-screen one, if not); 2) Sets the region coordinates
- * so that the graphics frame and the active module region agree (may change
- * active module region to do this); and 3) performs graphic frame/region
- * coordinate conversion initialization.
+ * D_setup() sets the source coordinate system to the current region, and
+ * adjusts the destination coordinate system to preserve the aspect
+ * ratio.
+ *
+ * Performs a full setup for the current graphics frame:
+ * 1) Makes sure there is a current graphics frame (will create a full-screen
+ *    one, if not);
+ * 2) Sets the region coordinates so that the graphics frame and the active
+ *    module region agree (may change active module region to do this); and  
+ * 3) Performs graphic frame/region coordinate conversion initialization.
+ *
  * If <b>clear</b> is true, the frame is cleared (same as running
- * <i>d.erase.</i>) Otherwise, it is not cleared.
+ * <i>d.erase</i>.) Otherwise, it is not cleared.
  *
  *  \param clear
- *  \return int
+ *  \return none
  */
-
 void D_setup(int clear)
 {
     struct Cell_head region;
@@ -56,6 +52,20 @@ void D_setup(int clear)
 	D_erase(DEFAULT_BG_COLOR);
 }
 
+
+/*!
+ * \brief 
+ *
+ * D_setup_unity() sets the source coordinate system to match the
+ * destination coordinate system, so that D_* functions use the same
+ * coordinate system as R_* functions.
+ *
+ * If <b>clear</b> is true, the frame is cleared (same as running
+ * <i>d.erase</i>.) Otherwise, it is not cleared.
+ *
+ *  \param clear
+ *  \return none
+ */
 void D_setup_unity(int clear)
 {
     double dt, db, dl, dr;
@@ -71,6 +81,25 @@ void D_setup_unity(int clear)
 	D_erase(DEFAULT_BG_COLOR);
 }
 
+
+/*!
+ * \brief 
+ *
+ * D_setup2() sets the source coordinate system to its arguments, and if
+ * the <b>fit</b> argument is non-zero, adjusts the destination coordinate
+ * system to preserve the aspect ratio.
+ *
+ * If <b>clear</b> is true, the frame is cleared (same as running
+ * <i>d.erase</i>.) Otherwise, it is not cleared.
+ *
+ *  \param clear
+ *  \param fit
+ *  \param s_top
+ *  \param s_bottom
+ *  \param s_left
+ *  \param s_right
+ *  \return none
+ */
 void D_setup2(int clear, int fit, double st, double sb, double sl, double sr)
 {
     double dt, db, dl, dr;
@@ -88,4 +117,3 @@ void D_setup2(int clear, int fit, double st, double sb, double sl, double sr)
     if (clear)
 	D_erase(DEFAULT_BG_COLOR);
 }
-