displaylib: modify D_driver_open() to supports 'monitors'

	    doxygen update


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

lib/display/r_raster.c

@@ -1,12 +1,12 @@
 /*!
-  \file display/r_raster.c
+  \file lib/display/r_raster.c
 
   \brief Display Library - Raster graphics subroutines
 
-  (C) 2001-2009 by the GRASS Development Team
+  (C) 2001-2009, 2011 by the GRASS Development Team
 
   This program is free software under the GNU General Public License
-  (>=v2).  Read the file COPYING that comes with GRASS for details.
+  (>=v2). Read the file COPYING that comes with GRASS for details.
 
   \author Original author CERL
 */
@@ -26,7 +26,6 @@
 
 #include "driver.h"
 
-
 extern const struct driver *PNG_Driver(void);
 extern const struct driver *PS_Driver(void);
 extern const struct driver *HTML_Driver(void);
@@ -34,6 +33,8 @@ extern const struct driver *HTML_Driver(void);
 extern const struct driver *Cairo_Driver(void);
 #endif
 
+static int read_env_file(const char *);
+
 static void init(void)
 {
     const char *fenc = getenv("GRASS_ENCODING");
@@ -64,27 +65,103 @@ static void init(void)
     }
 }
 
+int read_env_file(const char *path)
+{
+    FILE *fd;
+    char buf[1024];
+    char **token;
+    
+    fd = fopen(path, "r");
+    if (!fd)
+	return -1;
+
+    token = NULL;
+    while (G_getl2(buf, sizeof(buf) - 1, fd) != 0) {
+	token = G_tokenize(buf, "=");
+	if (G_number_of_tokens(token) != 2)
+	    continue;
+	
+	setenv(token[0], token[1], 1);
+	G_free_tokens(token);
+	token = NULL;
+    }
+
+    return 0;
+}
+
+/*!
+  \brief Open display driver
+
+  Default display driver is Cairo, if not available PNG is used.
+
+  \todo Replace strncmp by G_strncasecmp()
+  
+  \return 0 on success
+  \return 1 no monitor defined
+*/
 int D_open_driver(void)
 {
-    const char *p = getenv("GRASS_RENDER_IMMEDIATE");
+    const char *p, *m;
+    
+    p = getenv("GRASS_RENDER_IMMEDIATE");
+    m = G__getenv("MONITOR");
+    if (m) {
+	char *env;
+	const char *v;
+	
+	if (p)
+	    G_warning(_("%s variable defined, %s ignored"),
+		      "MONITOR", "GRASS_RENDER_IMMEDIATE");
+	env = NULL;
+	G_asprintf(&env, "MONITOR_%s_MAPFILE", m);
+	v = G__getenv(env);
+	if (strncmp(m, "wx", 2) == 0) 
+	    p = NULL; /* use default display driver */
+	else
+	    p = m;
+	
+	if (v) {
+	    if (p && G_strcasecmp(p, "ps") == 0)
+		setenv("GRASS_PSFILE", v, 1);
+	    else
+		setenv("GRASS_PNGFILE", v, 1);
+	}
+	
+	G_asprintf(&env, "MONITOR_%s_ENVFILE", m);
+	v = G__getenv(env);
+	if (v) 
+	    read_env_file(v);
+    }
+    
     const struct driver *drv =
-	(p && G_strcasecmp(p, "PNG") == 0) ? PNG_Driver() :
-	(p && G_strcasecmp(p, "PS") == 0) ? PS_Driver() :
-	(p && G_strcasecmp(p, "HTML") == 0) ? HTML_Driver() :
+	(p && G_strcasecmp(p, "PNG")   == 0) ? PNG_Driver() :
+	(p && G_strcasecmp(p, "PS")    == 0) ? PS_Driver() :
+	(p && G_strcasecmp(p, "HTML")  == 0) ? HTML_Driver() :
 #ifdef USE_CAIRO
 	(p && G_strcasecmp(p, "cairo") == 0) ? Cairo_Driver() :
 	Cairo_Driver();
 #else
 	PNG_Driver();
 #endif
-
+	
+    if (p && G_strcasecmp(drv->name, p) != 0)
+	G_warning(_("Unknown display driver <%s>"), p);
+    G_verbose_message(_("Using display driver <%s>..."), drv->name);
     LIB_init(drv);
 
     init();
 
+    if (!m)
+	return 1;
+
     return 0;
 }
 
+/*!
+  \brief Close display driver
+
+  If GRASS_NOTIFY is defined, run notifier.
+*/
 void D_close_driver(void)
 {
     const char *cmd = getenv("GRASS_NOTIFY");
@@ -95,89 +172,130 @@ void D_close_driver(void)
 	system(cmd);
 }
 
+int D_save_command(const char *cmd)
+{
+    const char *mon_name, *mon_cmd;
+    char *env;
+    FILE *fd;
+
+    G_debug(1, "D_save_command(): %s", cmd);
+
+    mon_name = G__getenv("MONITOR");
+    if (!mon_name)
+	return 0;
+    
+    env = NULL;
+    G_asprintf(&env, "MONITOR_%s_CMDFILE", mon_name);
+    mon_cmd = G__getenv(env);
+    if (!mon_cmd)
+	return 0;
+    
+    fd = fopen(mon_cmd, "a");
+    if (!fd) {
+	G_warning(_("Unable to open file '%s'"), mon_cmd);
+	return -1;
+    }
+    fprintf(fd, "%s\n", cmd);
+    fclose(fd);
+
+    return 1;
+}
+
+/*!
+  \brief Erase display (internal use only)
+*/
 void D__erase(void)
 {
     COM_Erase();
 }
 
 /*!
- * \brief set text size
- *
- * Sets text pixel width and height to <b>width</b> and <b>height.</b>
- *
- *  \param width
- *  \param height
- *  \return void
- */
-
+  \brief Set text size (width and height)
+ 
+  \param width text pixel width
+  \param height text pixel height
+*/
 void D_text_size(double width, double height)
 {
     COM_Text_size(width, height);
 }
 
+/*!
+  \brief Set text rotation
+
+  \param rotation value
+*/
 void D_text_rotation(double rotation)
 {
     COM_Text_rotation(rotation);
 }
 
 /*!
- * \brief get clipping frame
- *
- * Retrieve clipping frame
- *
- *  \param t top
- *  \param b bottom
- *  \param l left
- *  \param r right
- *  \return void
- */
-
+  \brief Get clipping frame
+  
+  \param[out] t top
+  \param[out] b bottom
+  \param[out] l left
+  \param[out] r right
+*/
 void D_get_window(double *t, double *b, double *l, double *r)
 {
     return COM_Get_window(t, b, l, r);
 }
 
 /*!
- * \brief write text
- *
- * Writes <b>text</b> in the current color and font, at the current text
- * width and height, starting at the current screen location.
- *
- *  \param sometext
- *  \return void
- */
-
+  \brief Draw text
+  
+  Writes <em>text</em> in the current color and font, at the current text
+  width and height, starting at the current screen location.
+  
+  \param text text to be drawn
+*/
 void D_text(const char *text)
 {
     COM_Text(text);
 }
 
 /*!
- * \brief choose font
- *
- * Set current font to <b>font name</b>.
- * 
- *  \param name
- *  \return void
- */
-
+  \brief Choose font
+ 
+  Set current font to <em>font name</em>.
+  
+  \param name font name
+*/
 void D_font(const char *name)
 {
     COM_Set_font(name);
 }
 
+/*!
+  \brief Set encoding
+
+  \param name encoding name
+*/
 void D_encoding(const char *name)
 {
     COM_Set_encoding(name);
 }
 
+/*!
+  \brief Get font list
+
+  \param[out] list list of font names
+  \param[out] number of items in the list
+*/
 void D_font_list(char ***list, int *count)
 {
     COM_Font_list(list, count);
 }
 
+/*!
+  \brief Get font info
+
+  \param[out] list list of font info
+  \param[out] number of items in the list
+*/
 void D_font_info(char ***list, int *count)
 {
     COM_Font_info(list, count);
 }
-

lib/display/raster.c

@@ -1,3 +1,32 @@
+/*!
+  \file lib/driver/raster.c
+
+  \brief Display Driver - draw raster data
+
+  (C) 2006-2011 by the GRASS Development Team
+
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+
+  \author Glynn Clements <glynn gclements.plus.com> (original contributor)
+  \author Huidae Cho <grass4u gmail.com>
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <grass/gis.h>
+#include <grass/raster.h>
+#include <grass/display.h>
+#include "driver.h"
+
+extern int D__overlay_mode;
+
+static int src[2][2];
+static double dst[2][2];
+
+static int draw_cell(int, const void *, struct Colors *, RASTER_MAP_TYPE);
+
 /* routines used by programs such as Dcell, display, combine, and weight
  * for generating raster images (for 1-byte, i.e. not super-cell, data)
  *
@@ -23,21 +52,16 @@
  *       first.
  */
 
-#include <stdio.h>
-#include <stdlib.h>
-
-#include <grass/gis.h>
-#include <grass/raster.h>
-#include <grass/display.h>
-#include "driver.h"
-
-extern int D__overlay_mode;
-
-static int src[2][2];
-static double dst[2][2];
-
-static int draw_cell(int, const void *, struct Colors *, RASTER_MAP_TYPE);
+/*!
+  \brief Draw raster row
+  
+  \param A_row row number
+  \param array
+  \param colors pointer to Colors structure
+  \param data_type raster type (CELL, FCELL, DCELL)
 
+  \return 
+*/
 int D_draw_raster(int A_row,
 		  const void *array,
 		  struct Colors *colors, RASTER_MAP_TYPE data_type)
@@ -45,16 +69,43 @@ int D_draw_raster(int A_row,
     return draw_cell(A_row, array, colors, data_type);
 }
 
+/*!
+  \brief Draw raster row (DCELL)
+  
+  \param A_row row number
+  \param darray
+  \param colors pointer to Colors structure
+
+  \return 
+*/
 int D_draw_d_raster(int A_row, const DCELL * darray, struct Colors *colors)
 {
     return draw_cell(A_row, darray, colors, DCELL_TYPE);
 }
 
+/*!
+  \brief Draw raster row (FCELL)
+  
+  \param A_row row number
+  \param farray
+  \param colors pointer to Colors structure
+
+  \return 
+*/
 int D_draw_f_raster(int A_row, const FCELL * farray, struct Colors *colors)
 {
     return draw_cell(A_row, farray, colors, FCELL_TYPE);
 }
 
+/*!
+  \brief Draw raster row (CELL)
+  
+  \param A_row row number
+  \param carray
+  \param colors pointer to Colors structure
+
+  \return 
+*/
 int D_draw_c_raster(int A_row, const CELL * carray, struct Colors *colors)
 {
     return draw_cell(A_row, carray, colors, CELL_TYPE);
@@ -62,21 +113,24 @@ int D_draw_c_raster(int A_row, const CELL * carray, struct Colors *colors)
 
 
 /*!
- * \brief render a raster row
- *
- * The <b>row</b> gives the map array row. The <b>raster</b>
- * array provides the categories for each raster value in that row. 
- * This routine is called consecutively with the information necessary to draw a
- * raster image from north to south. No rows can be skipped. All screen pixel
- * rows which represent the current map array row are rendered. The routine
- * returns the map array row which is needed to draw the next screen pixel row.
- *
- *  \param row
- *  \param raster
- *  \param colors
- *  \return int
- */
+  \brief Render a raster row
 
+  \todo Replace by D_draw_c_raster()
+  
+  The <b>row</b> gives the map array row. The <b>raster</b> array
+  provides the categories for each raster value in that row.  This
+  routine is called consecutively with the information necessary to
+  draw a raster image from north to south. No rows can be skipped. All
+  screen pixel rows which represent the current map array row are
+  rendered. The routine returns the map array row which is needed to
+  draw the next screen pixel row.
+ 
+  \param A_row row number
+  \param carray
+  \param colors pointer to Colors structure
+  
+  \return
+*/
 int D_draw_cell(int A_row, const CELL * carray, struct Colors *colors)
 {
     return draw_cell(A_row, carray, colors, CELL_TYPE);
@@ -117,19 +171,13 @@ static int draw_cell(int A_row,
 }
 
 /*!
- * \brief prepare for raster graphic
- *
- * The raster display subsystem establishes
- * conversion parameters based on the screen extent defined by <b>top,
- * bottom, left</b>, and <b>right</b>, all of which are obtainable from
- * <i>D_get_dst for the current frame.</i>
- *
- *  \param top
- *  \param bottom
- *  \param left
- *  \param right
- *  \return int
- */
+  \brief Prepare for raster graphic
+ 
+  The raster display subsystem establishes conversion parameters based
+  on the screen extent defined by <b>top, bottom, left</b>, and
+  <b>right</b>, all of which are obtainable from <i>D_get_dst for the
+  current frame.</i>
+*/
 
 void D_cell_draw_begin(void)
 {
@@ -139,6 +187,22 @@ void D_cell_draw_begin(void)
     COM_begin_raster(D__overlay_mode, src, dst);
 }
 
+/*!
+  \brief Draw raster row in RGB mode
+
+  \param A_row row number
+  \param r_raster red data buffer
+  \param g_raster green data buffer
+  \param b_raster blue data buffer
+  \param r_colors colors used for red channel
+  \param g_colors colors used for green channel
+  \param b_colors colors used for blue channel
+  \param r_type raster type used for red channel
+  \param g_type raster type used for red channel
+  \param b_type raster type used for red channel
+
+  \return
+*/
 int D_draw_raster_RGB(int A_row,
 		      const void *r_raster, const void *g_raster,
 		      const void *b_raster, struct Colors *r_colors,
@@ -190,6 +254,9 @@ int D_draw_raster_RGB(int A_row,
 	? A_row : -1;
 }
 
+/*!
+  \brief Finish rendering
+*/
 void D_cell_draw_end(void)
 {
     COM_end_raster();

lib/display/setup.c

@@ -1,40 +1,46 @@
-/* D_setup (clear)
- *
- * This is a high level D call.
- * It does a full setup for the current graphics frame.
- *
- * Note: Connection to driver must already be made.
- *
- * clear values:
- *   1: clear frame (visually and coordinates)
- *   0: do not clear frame
- */
+/*!
+  \file lib/driver/setup.c
+
+  \brief Display Driver - setup
+
+  (C) 2006-2011 by the GRASS Development Team
+
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+
+  \author Glynn Clements <glynn gclements.plus.com> (original contributor)
+  \author Huidae Cho <grass4u gmail.com>
+*/
+
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/raster.h>
 #include <grass/display.h>
 
-
 /*!
- * \brief graphics frame setup
- *
- * 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.
- *
- *  \param clear
- *  \return none
- */
+  \brief Graphics frame setup
+
+  This is a high level D call. It does a full setup for the current
+  graphics frame.
+ 
+  Note: Connection to driver must already be made.
+  
+  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:
+  - Makes sure there is a current graphics frame (will create a full-screen
+  one, if not);
+  - Sets the region coordinates so that the graphics frame and the active
+  module region agree (may change active module region to do this); and  
+  - 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.
+
+  \param clear 1 to clear frame (visually and coordinates)
+*/
 void D_setup(int clear)
 {
     struct Cell_head region;
@@ -51,20 +57,18 @@ 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
- */
+  \brief Graphics frame setup
+ 
+  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 non-zero code to clear the frame
+*/
 void D_setup_unity(int clear)
 {
     double dt, db, dl, dr;
@@ -80,25 +84,23 @@ 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
- */
+  \brief Sets source coordinate system
+  
+  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 non-zero code to clear the frame
+  \param fit non-zero code to adjust destination coordinate system
+  \param s_top
+  \param s_bottom
+  \param s_left
+  \param s_right
+*/
 void D_setup2(int clear, int fit, double st, double sb, double sl, double sr)
 {
     double dt, db, dl, dr;