ogsflib: doxygen strings & debug messages updated (merge devbr6, https://trac.osgeo.org/grass/changeset/31611)

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

lib/ogsf/GS2.c

@@ -132,6 +132,9 @@ void GS_libinit(void)
 int GS_get_longdim(float *dim)
 {
     *dim = Longdim;
+
+    G_debug(3, "GS_get_longdim(): dim=%g", *dim);
+
     return (1);
 }
 
@@ -153,7 +156,7 @@ int GS_get_region(float *n, float *s, float *w, float *e)
 }
 
 /*!
-  \brief Set attributes to default
+  \brief Set default attributes for map objects
 
   \param defs attributes array (dim MAX_ATTS)
   \param null_defs null attributes array (dim MAX_ATTS)
@@ -280,8 +283,8 @@ int GS_new_light(void)
 
   \bug I think lights array doesnt match sgi_light array
   
-  \param num light id (starts with 1?)
-  \param xpos,ypos,zpos coordinates
+  \param num light id (starts with 1)
+  \param xpos,ypos,zpos coordinates (model)
   \param local ?
 */
 void GS_setlight_position(int num, float xpos, float ypos, float zpos,
@@ -1454,7 +1457,7 @@ int GS_get_maskmode(int id, int *mode)
   \brief Set client data
 
   \param id surface id
-  \param clientd ?
+  \param clientd pointer to client data struct
 
   \return 1 on success
   \return -1 on error (invalid surface id)
@@ -1856,7 +1859,7 @@ void GS_draw_surf(int id)
 {
     geosurf *gs;
 
-    G_debug(3, "GS_draw_surf");
+    G_debug(3, "GS_draw_surf(): id=%d", id);
 
     gs = gs_get_surf(id);
     if (gs) {
@@ -1881,7 +1884,7 @@ void GS_draw_surf(int id)
 }
 
 /*!
-  \brief Draw wire
+  \brief Draw surface wire
 
   Overrides draw_mode for fast display
 
@@ -1891,7 +1894,7 @@ void GS_draw_wire(int id)
 {
     geosurf *gs;
 
-    G_debug(3, "GS_draw_wire");
+    G_debug(3, "GS_draw_wire(): id=%d", id);
 
     gs = gs_get_surf(id);
 
@@ -1989,7 +1992,7 @@ void GS_set_global_exag(float exag)
 */
 float GS_global_exag(void)
 {
-    G_debug(3, "GS_global_exag");
+    G_debug(3, "GS_global_exag(): %g", Gv.vert_exag);
 
     return (Gv.vert_exag);
 }
@@ -2342,7 +2345,7 @@ int GS_get_exag_guess(int id, float *exag)
 }
 
 /*!
-  Get Z extents for all loaded surfaces
+  \brief Get Z extents for all loaded surfaces
 
   Treating zeros as "no data"
 
@@ -2372,6 +2375,9 @@ void GS_get_zrange_nz(float *min, float *max)
 	}
     }
 
+    G_debug (3, "GS_get_zrange_nz(): min=%g max=%g",
+             *min, *max);
+
     return;
 }
 
@@ -2490,7 +2496,7 @@ void GS_ready_draw(void)
 }
 
 /*!
-  \brief Draw done
+  \brief Draw done, swap buffers
 */
 void GS_done_draw(void)
 {
@@ -2604,7 +2610,7 @@ void GS_set_focus_center_map(int id)
 }
 
 /*!
-  \brief Move position to
+  \brief Move to position
 
   \param pt point model coordinates
 */
@@ -2612,7 +2618,7 @@ void GS_moveto(float *pt)
 {
     float ft[3];
 
-    G_debug(3, "GS_moveto");
+    G_debug(3, "GS_moveto(): %f,%f,%f", pt[0], pt[1], pt[2]);
 
     if (Gv.infocus) {
 	GS_v3eq(Gv.from_to[FROM], pt);
@@ -2652,7 +2658,7 @@ void GS_moveto_real(float *pt)
   \param id surface id
   \param[out] min min z-value
   \param[out] max max z-value
-  \param[out] mid middle z-value ?
+  \param[out] mid middle z-value
 
   \return -1 on error (invalid surface id)
   \return ?
@@ -2661,12 +2667,12 @@ int GS_get_zextents(int id, float *min, float *max, float *mid)
 {
     geosurf *gs;
 
-    G_debug(3, "GS_get_zextents");
-
     if (NULL == (gs = gs_get_surf(id))) {
 	return (-1);
     }
 
+    G_debug(3, "GS_get_zextents(): id=%d", id);
+
     return (gs_get_zextents(gs, min, max, mid));
 }
 
@@ -2675,7 +2681,7 @@ int GS_get_zextents(int id, float *min, float *max, float *mid)
 
   \param[out] min min z-value
   \param[out] max max z-value
-  \param doexag ?
+  \param doexag use z-exaggeration
 
   \return 1 on success
   \return -1 on error
@@ -2686,8 +2692,6 @@ int GS_get_zrange(float *min, float *max, int doexag)
     float surf_min, surf_max;
     float vol_min, vol_max;
     
-    G_debug(3, "GS_get_zrange");
-    
     ret_surf = gs_get_zrange(&surf_min, &surf_max);
     ret_vol = gvl_get_zrange(&vol_min, &vol_max);
     
@@ -2707,20 +2711,22 @@ int GS_get_zrange(float *min, float *max, int doexag)
 	*max *= Gv.vert_exag;
     }
     
+    G_debug(3, "GS_get_zrange(): min=%g max=%g",
+	    *min, *max);
     return ((ret_surf > 0 || ret_vol > 0) ? (1) :(-1));
 }
 
 /*!
-  \brief Get 'from' coordinates
+  \brief Get 'from' position
 
   \param[out] fr from model coordinates
 */
 void GS_get_from(float *fr)
 {
-    G_debug(3, "GS_get_from");
-
     GS_v3eq(fr, Gv.from_to[FROM]);
 
+    G_debug(3, "GS_get_from(): %f,%f,%f", fr[0], fr[1], fr[2]);
+
     return;
 }
 
@@ -2908,7 +2914,8 @@ void GS_set_infocus(void)
 */
 void GS_set_viewport(int left, int right, int bottom, int top)
 {
-    G_debug(3, "GS_set_viewport");
+    G_debug(3, "GS_set_viewport(): left=%d, right=%d, "
+	    "bottom=%d, top=%d", left, right, bottom, top);
 
     gsd_viewport(left, right, bottom, top);
 
@@ -3162,7 +3169,7 @@ void GS_unset_cplane(int num)
   \brief Get scale
 
   \param sx,sy,sz x/y/z scale values
-  \param doexag ?
+  \param doexag use vertical exaggeration
 */
 void GS_get_scale(float *sx, float *sy, float *sz, int doexag)
 {
@@ -3366,6 +3373,8 @@ void GS_clear(int col)
 
 /*!
   \brief Get aspect value
+
+  \return aspect value
 */
 double GS_get_aspect(void)
 {

lib/ogsf/GSX.c

@@ -24,7 +24,7 @@ void (*Swap_func) ();
 static int Cxl = 0;
 
 /*!
-  \brief Check cancel
+  \brief Check for cancel
 
   \return code
 */

lib/ogsf/gs.c

@@ -638,7 +638,7 @@ int gs_get_att_type(geosurf * gs, int desc)
   \brief Get attribute source
 
   \param gs pointer to geosurf struct
-  \param desc attribute id
+  \param desc attribute id (descriptor)
 
   \return -1 on error
   \return attribute source id
@@ -659,7 +659,7 @@ int gs_get_att_src(geosurf * gs, int desc)
 }
 
 /*!
-  \brief Get attribute typbuff
+  \brief Get attribute data buffer
 
   \param gs pointer to geosurf struct
   \param desc attribute id (descriptor)

lib/ogsf/gs_bm.c

@@ -236,7 +236,7 @@ int gs_update_curmask(geosurf * surf)
     int row, col, offset, destroy_ok = 1;
     gsurf_att *coloratt;
 
-    G_debug (3, "gs_update_curmask():");
+    G_debug (4, "gs_update_curmask(): id=%d", surf->gsurf_id);
 
     if (surf->mask_needupdate) {
 	surf->mask_needupdate = 0;
@@ -304,24 +304,24 @@ int gs_update_curmask(geosurf * surf)
 	    }
 
 	    if (b_topo) {
-		G_debug(3, "  Update topo mask");
+		G_debug(4, "gs_update_curmask(): update topo mask");
 		gsbm_or_masks(surf->curmask, b_topo);
 		BM_destroy(b_topo);
 	    }
 
 	    if (b_color) {
-		G_debug(3, "  Update color mask");
+		G_debug(4, "gs_update_curmask(): update color mask");
 		gsbm_or_masks(surf->curmask, b_color);
 		BM_destroy(b_color);
 	    }
 
 	    if (t_topo->nm) {
-		G_debug(3, "  Update elev null mask");
+		G_debug(4, "gs_update_curmask(): update elev null mask");
 		gsbm_or_masks(surf->curmask, t_topo->nm);
 	    }
 
 	    if (b_mask) {
-		G_debug(3, "  Update mask mask");
+		G_debug(4, "gs_update_curmask(): update mask mask");
 
 		if (t_mask->bm) {
 		    if (surf->att[ATT_MASK].constant) {

lib/ogsf/gs_norms.c

@@ -141,7 +141,7 @@ int gs_calc_normals(geosurf * gs)
 
     init_vars(gs);
 
-    G_debug (3, "recalculating normals...");
+    G_debug (4, "gs_calc_normals(): id=%d", gs->gsurf_id);
 
     /* first row - just use single cell */
     /* first col - use bottom & right neighbors */
@@ -158,7 +158,7 @@ int gs_calc_normals(geosurf * gs)
     /* now use four neighboring points for rows 1 - (n-1) */
     for (row = 1; row < ycnt; row++) {
 	if (!(row % 100)) 
-	    G_debug (4, "  row %d", row);
+	    G_debug (4, "gs_calc_normals(): row=%d", row);
 
 	/* turn off left neighbor for first col */
 	calc_norm(gs, row * ymod, 0, ~NLFT);
@@ -195,9 +195,9 @@ int gs_calc_normals(geosurf * gs)
   and data row & col
 
   \param gs surface (geosurf)
-  \param drow
-  \param dcol
-  \param neighbors
+  \param drow data row
+  \param dcol data col
+  \param neighbors neighbors id
 
   \return 0 no normals
   \return 1 on success

lib/ogsf/gsd_img_ppm.c

@@ -32,7 +32,7 @@
 #include <grass/gstypes.h>
 
 /*!
-  \brief Write ppm file
+  \brief Save current GL screen to ppm file
 
   \param name file name
 
@@ -49,7 +49,6 @@ int GS_write_ppm(char *name)
 
     gsd_getimage(&pixbuf, &xsize, &ysize);
 
-
     if (NULL == (fp = fopen(name, "w"))) {
 	G_warning (_("Unable to open file <%s> for writing"),
 		   name);

lib/ogsf/gsd_prim.c

@@ -79,11 +79,11 @@ void gsd_flush(void)
 }
 
 /*!
-  \brief ADD
+  \brief Set color mode
 
   Call glColorMaterial before enabling the GL_COLOR_MATERIAL
 
-  \param cm
+  \param cm color mode value
 */
 void gsd_colormode(int cm)
 {
@@ -221,7 +221,10 @@ void gsd_sphere(float *center, float siz)
 /*!
   \brief Write out z-mask
 
-  \param n
+  Enable or disable writing into the depth buffer
+
+  \param n Specifies whether the depth buffer is enabled for
+  writing
 */
 void gsd_zwritemask(unsigned long n)
 {
@@ -352,7 +355,7 @@ void gsd_swaptmesh(void)
 }
 
 /*!
-  \brief ADD
+  \brief Delimit the vertices of a primitive or a group of like primitives
 */
 void gsd_bgnpolygon(void)
 {
@@ -367,7 +370,7 @@ void gsd_bgnpolygon(void)
 }
 
 /*!
-  \brief ADD
+  \brief Delimit the vertices of a primitive or a group of like primitives
 */
 void gsd_endpolygon(void)
 {
@@ -397,9 +400,9 @@ void gsd_endline(void)
 }
 
 /*!
-  \brief Shaded model
+  \brief Set shaded model
 
-  \param bool type
+  \param bool type non-zero for GL_SMOOTH otherwise GL_FLAT
 */
 void gsd_shademodel(int bool)
 {
@@ -437,7 +440,10 @@ void gsd_bothbuffer(void)
 }
 
 /*!
-  \brief ADD
+  \brief Specify which color buffers are to be drawn
+  into
+
+  \param bool non-zero for enable otherwise disable front buffer
 */
 void gsd_frontbuffer(int bool)
 {
@@ -448,9 +454,10 @@ void gsd_frontbuffer(int bool)
 }
 
 /*!
-  \brief ADD
+  \brief Specify which color buffers are to be drawn
+  into
 
-  \param bool
+  \param bool non-zero for enable otherwise disable back buffer
 */
 void gsd_backbuffer(int bool)
 {
@@ -460,7 +467,7 @@ void gsd_backbuffer(int bool)
 }
 
 /*!
-  \brief ADD
+  \brief Swap buffers
 */
 void gsd_swapbuffers(void)
 {
@@ -474,7 +481,7 @@ void gsd_swapbuffers(void)
 }
 
 /*!
-  \brief ADD
+  \brief Pop the current matrix stack
 */
 void gsd_popmatrix(void)
 {
@@ -484,7 +491,7 @@ void gsd_popmatrix(void)
 }
 
 /*!
-  \brief ADD
+  \brief Push the current matrix stack
 */
 void gsd_pushmatrix(void)
 {
@@ -494,7 +501,11 @@ void gsd_pushmatrix(void)
 }
 
 /*!
-  \brief ADD
+  \brief Multiply the current matrix by a general scaling matrix
+
+  \param xs x scale value
+  \param ys y scale value
+  \param zs z scale value
 */
 void gsd_scale(float xs, float ys, float zs)
 {
@@ -504,7 +515,11 @@ void gsd_scale(float xs, float ys, float zs)
 }
 
 /*!
-  \brief ADD
+  \brief Multiply the current matrix by a translation matrix
+
+  \param dx x translation value
+  \param dy y translation value
+  \param dz z translation value
 */
 void gsd_translate(float dx, float dy, float dz)
 {
@@ -514,12 +529,12 @@ void gsd_translate(float dx, float dy, float dz)
 }
 
 /*!
-  \brief ADD
+  \brief Get viewport
 
-  \param window
+  \param[out] window
   \param viewport
-  \param modelMatrix
-  \param projMatrix
+  \param modelMatrix model matrix
+  \param projMatrix projection matrix
 */
 void gsd_getwindow(int *window, int *viewport, double *modelMatrix,
 		   double *projMatrix)
@@ -623,11 +638,11 @@ void gsd_rot(float angle, char axis)
 }
 
 /*!
-  \brief ADD
+  \brief Set the current normal vector & specify vertex
 
-  \param norm
-  \param col
-  \param pt
+  \param norm normal vector
+  \param col color value
+  \param pt point (model coordinates)
 */
 void gsd_litvert_func(float *norm, unsigned long col, float *pt)
 {
@@ -666,9 +681,9 @@ void gsd_vert_func(float *pt)
 }
 
 /*!
-  \brief ADD
+  \brief Set current color
 
-  \param col
+  \param col color value
 */
 void gsd_color_func(unsigned int col)
 {
@@ -866,7 +881,7 @@ void gsd_switchlight(int num, int on)
 }
 
 /*!
-  \brief Get image
+  \brief Get image of current GL screen
 
   \param pixbuf data buffer
   \param[out] xsize,ysize picture dimension
@@ -951,7 +966,7 @@ int gsd_writeView(unsigned char **pixbuf, unsigned int xsize,
 }
 
 /*!
-  \brief ADD
+  \brief Specify pixel arithmetic
 
   \param yesno turn on/off
 */
@@ -1026,12 +1041,17 @@ void gsd_finish(void)
 }
 
 /*!
-  \brief ADD
+  \brief Set the viewport
   
-  \param l
-  \param r
-  \param b
-  \param t
+  <i>l</i>, <i>b</i> specify the lower left corner of the viewport
+  rectangle, in pixels.
+
+  <i>r</i>, <i>t</i> specify the width and height of the viewport.
+
+  \param l left
+  \param r right
+  \param b bottom
+  \param t top
 */
 void gsd_viewport(int l, int r, int b, int t)
 {

lib/ogsf/gsd_surf.c

@@ -81,7 +81,7 @@ int gsd_surf(geosurf * surf)
 {
     int desc, ret;
 
-    G_debug (3, "gsd_surf");
+    G_debug (4, "gsd_surf(): id=%d", surf->gsurf_id);
 
     desc = ATT_TOPO;
 
@@ -746,7 +746,7 @@ int gsd_surf_const(geosurf * surf, float k)
 
     unsigned int ktrans = 255;
 
-    G_debug(3, "gsd_surf_const");
+    G_debug(4, "gsd_surf_const(): id=%d", surf->gsurf_id);
 
     if (GS_check_cancel()) {
 	return (-1);
@@ -2038,10 +2038,8 @@ int gsd_norm_arrows(geosurf * surf)
 
 
 /*!
-  \brief ADD
+  \brief Draw surface using triangle fan instead of strip
 
-  New (TEST) surface drawing routine using triangle fan instead of strip
-  
   Optimized by getting rid of BM_get mask check - GET_MAPPATT does same
   and returns zero if masked 
   

lib/ogsf/gsd_views.c

@@ -276,9 +276,9 @@ int gsd_zup_twist(geoview * gv)
 }
 
 /*!
-  \brief ADD
+  \brief Set current scale
 
-  \param doexag
+  \param doexag use z-exaggeration
 */
 void gsd_do_scale(int doexag)
 {

lib/ogsf/gsd_wire.c

@@ -38,7 +38,7 @@
 */
 
 /*!
-  \brief ADD
+  \brief Draw surface wire
 
   \param surf surface (geosurf)
 
@@ -48,7 +48,7 @@ int gsd_wire_surf(geosurf * surf)
 {
     int desc, ret;
 
-    G_debug(3, "gsd_wire_surf");
+    G_debug(3, "gsd_wire_surf(): id=%d", surf->gsurf_id);
 
     desc = ATT_TOPO;
 
@@ -552,7 +552,7 @@ int gsd_wire_arrows(geosurf * surf)
 }
 
 /*!
-  \brief ADD
+  \brief Draw coarse surface
 
   New (TEST) wire routine that draws low res surface 
   Based on new Trinagle Fan routine