ogsflib: doxygen strings/debug messages updated

[merged from devbr6, r31506]


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

include/gsurf.h

@@ -1,10 +1,18 @@
-/*
-* $Id$
-*/
-
-/*  gsurf.h
-    Bill Brown, USACERL
-    January 1993
+/*!
+  \file gsurf.h
+ 
+  \brief OGSF library - main header
+ 
+  GRASS OpenGL gsurf OGSF Library 
+ 
+  (C) 1999-2008 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 Bill Brown USACERL (January 1993)
 */
 
 #ifndef _GSURF_H
@@ -69,17 +77,17 @@
 #define LEGAL_SRC(s) (s==NOTSET_ATT||s==MAP_ATT||s==CONST_ATT||s==FUNC_ATT)
 
 /* site markers */
-#define ST_X        1
+#define ST_X          1
 #define ST_BOX        2
-#define ST_SPHERE    3
+#define ST_SPHERE     3
 #define ST_CUBE       4
-#define ST_DIAMOND     5
-#define ST_DEC_TREE     6
-#define ST_CON_TREE     7
-#define ST_ASTER    8
-#define ST_GYRO            9
+#define ST_DIAMOND    5
+#define ST_DEC_TREE   6
+#define ST_CON_TREE   7
+#define ST_ASTER      8
+#define ST_GYRO       9
 /* ACS_MODIFY_One Line site_attr management ***************************************/
-#define ST_HISTOGRAM       10
+#define ST_HISTOGRAM  10
 
 /* site attribute modes (what attribute of marker category is used for) */
 /* TODO: may want to make these OR'able */

lib/bitmap/bitmap.c

@@ -47,11 +47,14 @@ static int Size = 1;
 
 /*!
  * \brief Create bitmap of dimension x/y and return structure token. 
+ *
  * Bitmap is initialized to all zeros
  *
- *  \param int x
- *  \param int y
- *  \return struct BM or NULL on error
+ *  \param x x dimension
+ *  \param y y dimension
+ *
+ *  \return pointer to struct BM
+ *  \return NULL on error
  */
 
 struct BM *BM_create (int x, int y)

lib/ogsf/GS2.c

@@ -83,10 +83,11 @@ void void_func(void)
 }
 
 /*!
-  \brief Library initialization
+  \brief Initialize OGSF library
 
-  Get region settings - wind, Region (NSWE array)
-  Compute scale
+  Get region settings - wind
+
+  Set Region (NSWE array) and compute scale
 */
 void GS_libinit(void)
 {
@@ -213,8 +214,6 @@ int GS_new_surface(void)
 {
     geosurf *ns;
 
-    G_debug(3, "GS_new_surface");
-
     if (Next_surf < MAX_SURFS) {
 	ns = gs_get_new_surface();
 	gs_init_surf(ns, wind.west + wind.ew_res / 2.,
@@ -228,9 +227,13 @@ int GS_new_surface(void)
 	Surf_ID[Next_surf] = ns->gsurf_id;
 	++Next_surf;
 
+	G_debug(3, "GS_new_surface(): id=%d", ns->gsurf_id);
+	
 	return (ns->gsurf_id);
     }
 
+
+
     return (-1);
 }
 
@@ -1569,11 +1572,11 @@ int GS_delete_surface(int id)
 
 
 /*!
-  \brief Load attribute map
+  \brief Load raster map as attribute
 
   \param id surface id
   \param filename filename
-  \param att attribute id
+  \param att attribute descriptor
 
   \return -1 on error (invalid surface id)
   \return ?
@@ -1588,7 +1591,7 @@ int GS_load_att_map(int id, char *filename, int att)
     int reuse = 0, begin, hdata, ret, neg = 0, has_null = 0;
     typbuff *tbuff;
 
-    G_debug (3, "GS_load_att_map(): att_map: %s", filename);
+    G_debug (3, "GS_load_att_map(): map=%s", filename);
 
     gs = gs_get_surf(id);
 
@@ -1747,8 +1750,6 @@ int GS_load_att_map(int id, char *filename, int att)
 				      tbuff->nm, &has_null);
 	    filename = G_fully_qualified_name(filename, mapset);
 
-	    G_debug(3, "HAS-NULL = %d", has_null);
-
 	    break;
 	case ATTY_INT:
 	default:
@@ -1769,7 +1770,7 @@ int GS_load_att_map(int id, char *filename, int att)
 	    return (-1);
 	}
 
-	G_debug(3, "HAS-NULL = %d", has_null);
+	G_debug(4, "  has_null=%d", has_null);
 
 	if (!has_null) {
 	    gsds_free_data_buff(gs->att[att].hdata, ATTY_NULL);
@@ -1843,9 +1844,6 @@ int GS_load_att_map(int id, char *filename, int att)
 	G_warning(_("Error finding range"));
     }
 
-    G_debug (3, "Range Updated: %f %f",
-	     gs->zmin, gs->zmax);
-
     return (ret);
 }
 
@@ -2068,7 +2066,7 @@ int GS_setall_drawmode(int mode)
   \brief Set draw mode
 
   \param id surface id
-  \param mode mode id
+  \param mode mode type(s)
 
   \return 0 on success
   \return -1 on error (invalid surface id)
@@ -2077,7 +2075,8 @@ int GS_set_drawmode(int id, int mode)
 {
     geosurf *gs;
 
-    G_debug(3, "GS_set_drawmode");
+    G_debug(3, "GS_set_drawmode(): id=%d mode=%d",
+	    id, mode);
 
     gs = gs_get_surf(id);
 
@@ -2215,7 +2214,8 @@ int GS_set_drawres(int id, int xres, int yres, int xwire, int ywire)
 {
     geosurf *gs;
 
-    G_debug(3, "GS_set_drawres");
+    G_debug(3, "GS_set_drawres() id=%d xyres=%d/%d xywire=%d/%d",
+	    id, xres, yres, xwire, ywire);
 
     if (xres < 1 || yres < 1 || xwire < 1 || ywire < 1) {
 	return (-1);
@@ -2272,8 +2272,6 @@ void GS_get_dims(int id, int *rows, int *cols)
 {
     geosurf *gs;
 
-    G_debug(3, "GS_get_dims");
-
     gs = gs_get_surf(id);
 
     if (gs) {

lib/ogsf/Gs3.c

@@ -130,7 +130,7 @@ int Gs_loadmap_as_float(struct Cell_head *wind, char *map_name, float *buff,
     char *map_set, *nullflags;
     int offset, row, col;
 
-    G_debug(3, "Gs_loadmap_as_float");
+    G_debug(3, "Gs_loadmap_as_float(): name=%s", map_name);
 
     map_set = G_find_cell2(map_name, "");
     if (!map_set) {
@@ -167,7 +167,7 @@ int Gs_loadmap_as_float(struct Cell_head *wind, char *map_name, float *buff,
 	}
     }
 
-    G_debug(3, "_HAS-NULL_ = %d", *has_null);
+    G_debug(4, "  has_null=%d", *has_null);
 
     G_close_cell(cellfile);
 
@@ -1132,10 +1132,10 @@ int Gs_load_3dview(char *vname, geoview * gv, geodisplay * gd,
 }
 
 /*!
-  \brief Update no_zero ranges for att (actually no_null now)
+  \brief Update no_zero ranges for attribute (actually no_null now)
   
   \param gs pointer to geosurf struct
-  \param desc attribute id
+  \param desc attribute id (descriptor)
 
   \return -1 on error
   \return 1 on success
@@ -1246,5 +1246,8 @@ int Gs_update_attrange(geosurf * gs, int desc)
 	gs->zrange_nz = gs->zmax_nz - gs->zmin_nz;
     }
 
+    G_debug (3, "Gs_update_attrange(): min=%f max=%f",
+	     gs->zmin, gs->zmax);
+
     return (1);
 }

lib/ogsf/gs.c

@@ -39,7 +39,7 @@ void gs_err(char *msg)
 }
 
 /*!
-  \brief Library initialization
+  \brief Initialize library
 
   Still need to take care of library initialization, 
   probably want to define a Surf_top of constant value (i.e., 0)
@@ -63,10 +63,11 @@ geosurf *gs_get_surf(int id)
 {
     geosurf *gs;
 
-    G_debug(3, "gs_get_surf");
+    G_debug(4, "gs_get_surf():");
 
     for (gs = Surf_top; gs; gs = gs->next) {
 	if (gs->gsurf_id == id) {
+	    G_debug(4, "  id=%d", id);
 	    return (gs);
 	}
     }
@@ -86,7 +87,7 @@ geosurf *gs_get_prev_surface(int id)
 {
     geosurf *ps;
 
-    G_debug(3, "gs_get_prev_surface");
+    G_debug(4, "gs_get_prev_surface");
 
     for (ps = Surf_top; ps; ps = ps->next) {
 	if (ps->gsurf_id == id - 1) {
@@ -113,7 +114,7 @@ int gs_getall_surfaces(geosurf ** gsurfs)
 	gsurfs[i] = gs;
     }
 
-    G_debug(3, "gs_num_surfaces(): num=%d", i);
+    G_debug(4, "gs_num_surfaces(): num=%d", i);
 
     return (i);
 }
@@ -130,7 +131,7 @@ int gs_num_surfaces(void)
 
     for (i = 0, gs = Surf_top; gs; gs = gs->next, i++);
 
-    G_debug(3, "gs_num_surfaces(): num=%d", i);
+    G_debug(4, "gs_num_surfaces(): num=%d", i);
 
     return (i);
 }
@@ -164,7 +165,7 @@ int gs_att_is_set(geosurf * surf, IFLAG att)
 }
 
 /*!
-  \brief Get last geosurf struct
+  \brief Get last allocated geosurf struct from list
 
   \return pointer to geosurf struct
 */
@@ -172,22 +173,21 @@ geosurf *gs_get_last_surface(void)
 {
     geosurf *ls;
 
-    G_debug(3, "gs_get_last_surface():");
-
     if (!Surf_top) {
 	return (NULL);
     }
 
     for (ls = Surf_top; ls->next; ls = ls->next);
 
-    G_debug(3, " last surface id: %d", ls->gsurf_id);
+    G_debug(4, "gs_get_last_surface(): last surface id=%d",
+	    ls->gsurf_id);
 
     return (ls);
 }
 
 
 /*!
-  \brief Get new geosurf struct
+  \brief Allocate new geosurf struct
 
   \return pointer to geosurf struct
 */
@@ -195,8 +195,6 @@ geosurf *gs_get_new_surface(void)
 {
     geosurf *ns, *ls;
 
-    G_debug(3, "gs_get_new_surface");
-
     ns = (geosurf *) G_malloc(sizeof(geosurf)); /* G_fatal_error */
     if (!ns) {
 	return (NULL);
@@ -213,13 +211,15 @@ geosurf *gs_get_new_surface(void)
 
     ns->next = NULL;
 
+    G_debug(4, "gs_get_new_surface(): id=%d", ns->gsurf_id);
+
     return (ns);
 }
 
 /*!
-  \brief Init geosurf struct
+  \brief Initialize allocated geosurf struct
 
-  Now xmin & ox are the same, right? - get rid of ox, oy in geosurf struct?
+  \todo Now xmin & ox are the same, right? - get rid of ox, oy in geosurf struct?
 
   \param gs pointer to geosurf struct
   \param ox,oy x/y origin coordinates
@@ -236,7 +236,7 @@ int gs_init_surf(geosurf * gs, double ox, double oy, int rows, int cols,
     geosurf *ps;
     int i;
 
-    G_debug(3, "gs_init_surf");
+    G_debug(4, "gs_init_surf() id=%d", gs->gsurf_id);
 
     if (!gs) {
 	return (-1);
@@ -422,17 +422,17 @@ void print_view_fields(geoview * gv)
 }
 
 /*!
-  \brief Set default attributes
+  \brief Set default attribute values
 
   \param gs pointer to geosurf struct
-  \param defs array of default values
-  \param null_defs array of null default values
+  \param defs array of default values (dim MAX_ATTRS)
+  \param null_defs array of null default values (dim MAX_ATTRS)
 */
 void gs_set_defaults(geosurf * gs, float *defs, float *null_defs)
 {
     int i;
 
-    G_debug(3, "gs_set_defaults");
+    G_debug(4, "gs_set_defaults(): id=%d", gs->gsurf_id);
 
     for (i = 0; i < MAX_ATTS; i++) {
 	gs->att[i].constant = defs[i];
@@ -454,7 +454,7 @@ void gs_delete_surf(int id)
 {
     geosurf *fs;
 
-    G_debug(3, "gs_delete_surf");
+    G_debug(4, "gs_delete_surf");
     
     fs = gs_get_surf(id);
 
@@ -479,7 +479,7 @@ int gs_free_surf(geosurf * fs)
     geosurf *gs;
     int found = 0;
 
-    G_debug(3, "gs_free_surf");
+    G_debug(4, "gs_free_surf");
 
     if (Surf_top) {
 	if (fs == Surf_top) {
@@ -550,7 +550,7 @@ void gs_free_unshared_buffs(geosurf * fs)
     int i, j, same;
     int old_datah;
 
-    G_debug(3, "gs_free_unshared_buffs");
+    G_debug(4, "gs_free_unshared_buffs");
 
     /* for each attribute 
        if !same, free buff   
@@ -589,7 +589,7 @@ int gs_num_datah_reused(int dh)
     geosurf *gs;
     int ref, j;
 
-    G_debug(3, "gs_num_datah_reused");
+    G_debug(4, "gs_num_datah_reused");
 
     /* for each attribute 
        if same, ++reference
@@ -619,7 +619,7 @@ int gs_num_datah_reused(int dh)
 */
 int gs_get_att_type(geosurf * gs, int desc)
 {
-    G_debug(3, "gs_get_att_type");
+    G_debug(4, "gs_get_att_type");
 
     if (!LEGAL_ATT(desc)) {
 	return (-1);
@@ -645,7 +645,7 @@ int gs_get_att_type(geosurf * gs, int desc)
 */
 int gs_get_att_src(geosurf * gs, int desc)
 {
-    G_debug(3, "gs_get_att_src");
+    G_debug(4, "gs_get_att_src(): id=%d desc=%d", gs->gsurf_id, desc);
 
     if (!LEGAL_ATT(desc)) {
 	return (-1);
@@ -662,8 +662,8 @@ int gs_get_att_src(geosurf * gs, int desc)
   \brief Get attribute typbuff
 
   \param gs pointer to geosurf struct
-  \param desc attribute id
-  \param to_write
+  \param desc attribute id (descriptor)
+  \param to_write non-zero value for 'write'
 
   \return NULL on error
   \return pointer to typbuff
@@ -673,6 +673,9 @@ typbuff *gs_get_att_typbuff(geosurf * gs, int desc, int to_write)
     typbuff *tb;
     geosurf *gsref;
 
+    G_debug(4, "gs_get_att_typbuff(): id=%d desc=%d to_write=%d",
+	    gs->gsurf_id, desc, to_write);
+
     if (gs) {
 	if ((tb = gsds_get_typbuff(gs->att[desc].hdata, to_write))) {
 	    tb->tfunc = NULL;
@@ -696,8 +699,8 @@ typbuff *gs_get_att_typbuff(geosurf * gs, int desc, int to_write)
   \brief Allocate attribute buffer
 
   \param gs pointer to geosurf struct
-  \param desc attribute id
-  \param type buffer type
+  \param desc attribute id (descriptor)
+  \param type buffer type (based on raster map type)
 
   \return -1 on error
   \return pointer to typbuff (casted)
@@ -706,7 +709,7 @@ int gs_malloc_att_buff(geosurf * gs, int desc, int type)
 {
     int hdata, dims[2], ndims;
 
-    G_debug(3, "gs_malloc_att_buff");
+    G_debug(4, "gs_malloc_att_buff");
 
     if (gs) {
 	if (0 < (hdata = gs->att[desc].hdata)) {
@@ -735,7 +738,7 @@ int gs_malloc_lookup(geosurf * gs, int desc)
 {
     int size;
 
-    G_debug(3, "gs_malloc_lookup");
+    G_debug(4, "gs_malloc_lookup");
 
     if (gs) {
 	if (gs->att[desc].lookup) {
@@ -791,7 +794,7 @@ int gs_malloc_lookup(geosurf * gs, int desc)
 int gs_set_att_type(geosurf * gs, int desc, int type)
 {
 
-    G_debug(3, "gs_set_att_type(): desc=%d, type=%d",
+    G_debug(4, "gs_set_att_type(): desc=%d, type=%d",
 	    desc, type);
 
     if (gs && LEGAL_TYPE(type)) {
@@ -807,7 +810,7 @@ int gs_set_att_type(geosurf * gs, int desc, int type)
   \brief Set attribute source
 
   \param gs pointer to geosurf struct
-  \param desc attribute id
+  \param desc attribute id (descriptor)
   \param src source id
 
   \return -1 on error
@@ -815,7 +818,8 @@ int gs_set_att_type(geosurf * gs, int desc, int type)
 */
 int gs_set_att_src(geosurf * gs, int desc, int src)
 {
-    G_debug(3, "gs_set_att_src");
+    G_debug(4, "gs_set_att_src(): id=%d desc=%d src=%d",
+	    gs->gsurf_id, desc, src);
 
     /* check if old source was MAP_ATT, free buff */
     if (MAP_ATT == gs_get_att_src(gs, desc)) {
@@ -858,7 +862,7 @@ int gs_set_att_src(geosurf * gs, int desc, int src)
 */
 int gs_set_att_const(geosurf * gs, int desc, float constant)
 {
-    G_debug(3, "gs_set_att_const");
+    G_debug(4, "gs_set_att_const");
 
     if (gs) {
 	gs->att[desc].constant = constant;

lib/ogsf/gsds.c

@@ -1,7 +1,7 @@
 /*!
   \file gsds.c
  
-  \brief OGSF library - ? (lower level functions) 
+  \brief OGSF library - dataset loading and management (lower level functions) 
  
   GRASS OpenGL gsurf OGSF Library 
 
@@ -79,7 +79,7 @@ static int Cur_max;
 static int Tot_mem = 0;
 
 /*!
-  \brief Initialize 
+  \brief Initialize gsds
 */
 static int init_gsds(void)
 {
@@ -211,7 +211,7 @@ int gsds_findh(char *name, IFLAG * changes, IFLAG * types, int begin)
 /*!
   \brief Get handle to gsds
 
-  \param name
+  \param name raster map name
 
   \return -1 on failure
   \return data id
@@ -266,16 +266,14 @@ int gsds_newh(char *name)
 }
 
 /*!
-  \brief Get typbuff
+  \brief Get data buffer
 
-  change_flag just tells us to set changed flag
-  
-  Doesn't prevent
-  writing a buff thats's been gotten with change_flag == 0 (could return a
-  copy, but willing to trust calling func for now)
+  Doesn't prevent writing a buff thats's been gotten with change_flag
+  == 0 (could return a copy, but willing to trust calling func for
+  now)
   
-  \param id
-  \param change_flag
+  \param id dataset id
+  \param change_flag set changed flag
 
   \return pointer to typbuff struct
   \return NULL on failure
@@ -359,10 +357,10 @@ int gsds_free_datah(int id)
 }
 
 /*!
-  \brief ADD
+  \brief Free allocated buffer
 
-  \param id
-  \param typ
+  \param id dataset id
+  \param typ data type
 
   \return 0 not found
   \return 1 found
@@ -384,12 +382,12 @@ int gsds_free_data_buff(int id, int typ)
 }
 
 /*!
-  \brief ADD
+  \brief Free data buffer
 
-  \param ds
-  \param typ
+  \param ds pointer to dataset struct
+  \param typ data type
 
-  \return
+  \return freed size
 */
 int free_data_buffs(dataset * ds, int typ)
 {
@@ -457,8 +455,8 @@ int free_data_buffs(dataset * ds, int typ)
     ds->numbytes -= freed;
 
     if (freed) {
-	G_debug (3, "freed data from id no. %d", ds->data_id);
-	G_debug (3, "%.3f Kbytes freed, current total = %.3f",
+	G_debug (5, "free_data_buffs(): freed data from id no. %d", ds->data_id);
+	G_debug (5, "free_data_buffs(): %.3f Kbytes freed, current total = %.3f",
 		 freed / 1000., Tot_mem / 1000.);
     }
     
@@ -470,10 +468,10 @@ int free_data_buffs(dataset * ds, int typ)
 
   \todo add ATTY_CONST
 
-  \param id
-  \param dims
-  \param ndims
-  \param type
+  \param id dataset id
+  \param dims array of dimensions
+  \param ndims number of dimensions
+  \param type data type
 
   \return
 */
@@ -590,7 +588,7 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 	ds->ndims = ndims;
 	Tot_mem += siz;
 
-	G_debug (3, "%f Kbytes allocated, current total = %f",
+	G_debug (5, "gsds_alloc_typbuff(): %f Kbytes allocated, current total = %f",
 		 siz / 1000., Tot_mem / 1000.);
 
 	return (siz);