ogsflib: doxygenization (initial) in progress

fprintf -> G_debug
[sync'ed with devbr6]


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

lib/ogsf/gp.c

@@ -13,6 +13,7 @@
   for details.
   
   \author Bill Brown USACERL, GMSL/University of Illinois (January 1994)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>
@@ -24,16 +25,19 @@
 
 static geosite *Site_top = NULL;
 
-/***********************************************************************/
+/*!
+  \brief Get geosite struct
+
+  \param id point set id
+
+  \return pointer to geosite struct
+  \return NULL on failure
+*/
 geosite *gp_get_site(int id)
 {
     geosite *gp;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_get_site");
-    }
-#endif
+    G_debug(3, "gp_get_site");
 
     for (gp = Site_top; gp; gp = gp->next) {
 	if (gp->gsite_id == id) {
@@ -44,16 +48,19 @@ geosite *gp_get_site(int id)
     return (NULL);
 }
 
-/***********************************************************************/
+/*!
+  \brief Get previous geosite struct from list
+
+  \param id point set id
+
+  \return pointer to geosite struct
+  \return NULL on failure
+*/
 geosite *gp_get_prev_site(int id)
 {
     geosite *pp;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_get_prev_site");
-    }
-#endif
+    G_debug(3, "gp_get_prev_site");
 
     for (pp = Site_top; pp; pp = pp->next) {
 	if (pp->gsite_id == id - 1) {
@@ -64,33 +71,34 @@ geosite *gp_get_prev_site(int id)
     return (NULL);
 }
 
-/***********************************************************************/
+/*!
+  \brief Get number of registrated point sets
+
+  \return number of point sets
+*/
 int gp_num_sites(void)
 {
     geosite *gp;
     int i;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_num_sites");
-    }
-#endif
+    G_debug(3, "gp_num_sites");
 
     for (i = 0, gp = Site_top; gp; gp = gp->next, i++);
 
     return (i);
 }
 
-/***********************************************************************/
+/*!
+  \brief Get last point set
+
+  \return pointer to geosite struct
+  \return NULL if no point set is available
+*/
 geosite *gp_get_last_site(void)
 {
     geosite *lp;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_get_last_site");
-    }
-#endif
+    G_debug(3, "gp_get_last_site");
 
     if (!Site_top) {
 	return (NULL);
@@ -98,32 +106,30 @@ geosite *gp_get_last_site(void)
 
     for (lp = Site_top; lp->next; lp = lp->next);
 
-#ifdef DEBUG
-    {
-	fprintf(stderr, "last site id: %d\n", lp->gsite_id);
-    }
-#endif
+    G_debug(3, " last site id: %d", lp->gsite_id);
 
     return (lp);
 }
 
-/***********************************************************************/
+/*!
+  \brief Create new geosite instance and add it to list
+
+  \return pointer to geosite struct
+  \return NULL on error
+*/
 geosite *gp_get_new_site(void)
 {
     geosite *np, *lp;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_get_new_site");
-    }
-#endif
+    G_debug(3, "gp_get_new_site");
 
-    if (NULL == (np = (geosite *) malloc(sizeof(geosite)))) {
-	gs_err("gp_get_new_site");
+    np = (geosite *) G_malloc(sizeof(geosite)); /* G_fatal_error */
+    if (!np) {
 	return (NULL);
     }
 
-    if (lp = gp_get_last_site()) {
+    lp = gp_get_last_site();
+    if (lp) {
 	lp->next = np;
 	np->gsite_id = lp->gsite_id + 1;
     }
@@ -137,8 +143,11 @@ geosite *gp_get_new_site(void)
     return (np);
 }
 
-/***********************************************************************/
-/* call after surface is deleted */
+/*!
+  \brief Update drape surfaces
+  
+  Call after surface is deleted
+*/
 void gp_update_drapesurfs(void)
 {
     geosite *gp;
@@ -163,17 +172,20 @@ void gp_update_drapesurfs(void)
     return;
 }
 
-/***********************************************************************/
+/*!
+  \brief Set default value for geosite struct
+
+  \param gp pointer to geosite struct
+
+  \return 1 on success
+  \return -1 on failure
+*/
 int gp_set_defaults(geosite * gp)
 {
     int i;
     float dim;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_set_defaults");
-    }
-#endif
+    G_debug(3, "gp_set_defaults");
 
     if (!gp) {
 	return (-1);
@@ -198,7 +210,11 @@ int gp_set_defaults(geosite * gp)
     return (1);
 }
 
-/***********************************************************************/
+/*!
+  \brief Print point set fields, debugging
+
+  \param gp pointer to geosite struct
+*/
 void print_site_fields(geosite * gp)
 {
     int i;
@@ -222,14 +238,17 @@ void print_site_fields(geosite * gp)
     return;
 }
 
-/***********************************************************************/
+/*!
+  \brief Initialize geosite struct
+
+  \param gp pointer to geosite struct
+
+  \return -1 on failure
+  \return 0 on success
+*/
 int gp_init_site(geosite * gp)
 {
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_init_site");
-    }
-#endif
+    G_debug(3, "gp_init_site");
 
     if (!gp) {
 	return (-1);
@@ -238,16 +257,16 @@ int gp_init_site(geosite * gp)
     return (0);
 }
 
-/***********************************************************************/
+/*!
+  \brief Delete point set and remove from list
+
+  \param id point set id
+*/
 void gp_delete_site(int id)
 {
     geosite *fp;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_delete_site");
-    }
-#endif
+    G_debug(3, "gp_delete_site");
 
     fp = gp_get_site(id);
 
@@ -258,17 +277,20 @@ void gp_delete_site(int id)
     return;
 }
 
-/***********************************************************************/
+/*!
+  \brief Free geosite struct
+
+  \param fp pointer to geosite struct
+
+  \return 1 on success
+  \return -1 on failure
+*/
 int gp_free_site(geosite * fp)
 {
     geosite *gp;
     int found = 0;
 
-#ifdef TRACE_FUNCS
-    {
-	Gs_status("gp_free_site");
-    }
-#endif
+    G_debug(3, "gp_free_site");
 
     if (Site_top) {
 	if (fp == Site_top) {
@@ -279,7 +301,7 @@ int gp_free_site(geosite * fp)
 	    }
 	    else {
 		gp_free_sitemem(fp);
-		free(fp);
+		G_free(fp);
 		Site_top = NULL;
 	    }
 	}
@@ -297,7 +319,7 @@ int gp_free_site(geosite * fp)
 
 	if (found) {
 	    gp_free_sitemem(fp);
-	    free(fp);
+	    G_free(fp);
 	    fp = NULL;
 	}
 
@@ -307,7 +329,11 @@ int gp_free_site(geosite * fp)
     return (-1);
 }
 
-/***********************************************************************/
+/*!
+  \brief Free geosite
+
+  \param fp pointer to geosite struct
+*/
 void gp_free_sitemem(geosite * fp)
 {
     geopoint *gpt, *tmp;
@@ -315,12 +341,12 @@ void gp_free_sitemem(geosite * fp)
     if (fp->points) {
 	for (gpt = fp->points; gpt;) {
 	    if (gpt->cattr) {
-		free(gpt->cattr);
+		G_free(gpt->cattr);
 	    }
 
 	    tmp = gpt;
 	    gpt = gpt->next;
-	    free(tmp);
+	    G_free(tmp);
 	}
 
 	fp->n_sites = 0;
@@ -330,7 +356,13 @@ void gp_free_sitemem(geosite * fp)
     return;
 }
 
-/***********************************************************************/
+/*!
+  \brief Set drape surfaces
+
+  \param gp pointer to geosite struct
+  \param hsurf list of surfaces (id)
+  \param nsurf number of surfaces
+*/
 void gp_set_drapesurfs(geosite * gp, int hsurfs[], int nsurfs)
 {
     int i;

lib/ogsf/gpd.c

@@ -13,6 +13,7 @@
   for details.
   
   \author Bill Brown USACERL, GMSL/University of Illinois (December 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdio.h>
@@ -29,52 +30,61 @@
 /* ACS_MODIFY_BEGIN site_attr management ***************************************/
 static float _cur_size_;
 
-/* This substitutes gpd_obj */
+/*!
+  \brief Substitutes gpd_obj()
+
+  \param gs surface (geosurf)
+  \param gp site (geosite)
+  \param gpt point (point)
+  \param site point
+
+  \return 0
+*/
 int gpd_obj_site_attr(geosurf * gs, geosite * gp, geopoint *gpt, Point3 site)
 {
     float size, z, y, x, z_scale, z_offset;
     int marker, color, i, ii, iii;
-	int use_attr, has_drawn;
-	int _put_aside_;
-
-	_put_aside_ = 0;
-	_cur_size_ = gp->size;
-
+    int use_attr, has_drawn;
+    int _put_aside_;
+    
+    _put_aside_ = 0;
+    _cur_size_ = gp->size;
+    
     z_scale = GS_global_exag();
-	z_offset = 0.0;
-
-	has_drawn = 0;
-
-	for(i=0; i<GPT_MAX_ATTR; i++) {
-		color = gp->color; marker = gp->marker; size = gp->size;
-		use_attr = 0;
-
-		if (gp->use_attr[i] & ST_ATT_COLOR) {
-			use_attr = 1;
-			color = gpt->color[i];
-		}
-
-		if (gp->use_attr[i] & ST_ATT_MARKER) {
-			use_attr = 1;
-			marker = gpt->marker[i];
-		}
-
-		if (gp->use_attr[i] & ST_ATT_SIZE) {
-			use_attr = 1;
-			size = gpt->size[i] * gp->size;
-			if (gp->marker == ST_HISTOGRAM) _put_aside_ = 1;
-		}
-
+    z_offset = 0.0;
+    
+    has_drawn = 0;
+    
+    for(i=0; i<GPT_MAX_ATTR; i++) {
+	color = gp->color; marker = gp->marker; size = gp->size;
+	use_attr = 0;
+	
+	if (gp->use_attr[i] & ST_ATT_COLOR) {
+	    use_attr = 1;
+	    color = gpt->color[i];
+	}
+	
+	if (gp->use_attr[i] & ST_ATT_MARKER) {
+	    use_attr = 1;
+	    marker = gpt->marker[i];
+	}
+	
+	if (gp->use_attr[i] & ST_ATT_SIZE) {
+	    use_attr = 1;
+	    size = gpt->size[i] * gp->size;
+	    if (gp->marker == ST_HISTOGRAM) _put_aside_ = 1;
+	}
+	
 /* ACS_MODIFY_BEGIN site_highlight management **********************************/
-		if (gpt->highlight_color) color = gpt->highlight_color_value;
-		if (gpt->highlight_marker) marker = gpt->highlight_marker_value;
-		if (gpt->highlight_size) size *= gpt->highlight_size_value;
+	if (gpt->highlight_color) color = gpt->highlight_color_value;
+	if (gpt->highlight_marker) marker = gpt->highlight_marker_value;
+	if (gpt->highlight_size) size *= gpt->highlight_size_value;
 /* ACS_MODIFY_END site_highlight management ************************************/
-
-		if (_put_aside_) {
-			if (use_attr == 1) {
-				has_drawn = 1;
-
+	
+	if (_put_aside_) {
+	    if (use_attr == 1) {
+		has_drawn = 1;
+		
 /*******************************************************************************
 		fixed size = gp->size
 		this is mailny intended for "histograms" that grow in z, but not in xy
@@ -87,53 +97,62 @@ int gpd_obj_site_attr(geosurf * gs, geosite * gp, geopoint *gpt, Point3 site)
           0  1  4  9
 
 *******************************************************************************/
-				x = site[X];
-				y = site[Y];
-
-				ii = (int)(sqrt(i));
-				iii = ii * ii + ii;
-
-				if (i <= iii) {
-					site[X] += ii * 2.2 * gp->size;
-					site[Y] += (i-ii) * 2.2 * gp->size;
-				} else {
-					site[X] += (ii-(i-iii)) * 2.2 * gp->size;
-					site[Y] += ii * 2.2 * gp->size;
-
-				}
-
-				gpd_obj(gs, color, size, marker, site);
-
-				site[X] = x;
-				site[Y] = y;
-			}
+		x = site[X];
+		y = site[Y];
+		
+		ii = (int)(sqrt(i));
+		iii = ii * ii + ii;
+		
+		if (i <= iii) {
+		    site[X] += ii * 2.2 * gp->size;
+		    site[Y] += (i-ii) * 2.2 * gp->size;
 		} else {
-			if (i>0) z_offset += size;
-			if (use_attr == 1) {
-				has_drawn = 1;
-
-				z = site[Z];
-				site[Z] += z_offset / z_scale;
-
-				gpd_obj(gs, color, size, marker, site);
-
-				site[Z] = z;
-			}
-
-			z_offset += size;
+		    site[X] += (ii-(i-iii)) * 2.2 * gp->size;
+		    site[Y] += ii * 2.2 * gp->size;
+		    
 		}
-	}
-
-	if (has_drawn == 0)
+		
 		gpd_obj(gs, color, size, marker, site);
-
-	return(0);
+		
+		site[X] = x;
+		site[Y] = y;
+	    }
+	} else {
+	    if (i>0) z_offset += size;
+	    if (use_attr == 1) {
+		has_drawn = 1;
+		
+		z = site[Z];
+		site[Z] += z_offset / z_scale;
+		
+		gpd_obj(gs, color, size, marker, site);
+		
+		site[Z] = z;
+	    }
+	    
+	    z_offset += size;
+	}
+    }
+    
+    if (has_drawn == 0)
+	gpd_obj(gs, color, size, marker, site);
+    
+    return(0);
 }
 /* ACS_MODIFY_END site_attr management *****************************************/
 
+/*!
+  \brief Check if point is in region
+
+  Check for cancel every CHK_FREQ points
 
-/* check for cancel every CHK_FREQ points */
+  \param gs surface (geosurf)
+  \param pt point (array(X,Y,Z))
+  \param region region settings (array (top,bottom,left,right))
 
+  \return 0 point outside of region
+  \return 1 point inside region
+*/
 int gs_point_in_region(geosurf * gs, float *pt, float *region)
 {
     float top, bottom, left, right;
@@ -155,10 +174,20 @@ int gs_point_in_region(geosurf * gs, float *pt, float *region)
 	    pt[Y] >= bottom && pt[Y] <= top);
 }
 
-/* TODO: add size1, size2 & dir1, dir2 (eg azimuth, elevation) variables
+/*!
+  \brief ADD
+
+  Do normal transforms before calling
+
+  Note gs: NULL if 3d obj or const elev surface
+
+  \todo add size1, size2 & dir1, dir2 (eg azimuth, elevation) variables
+
+  \param gs surface (geosurf)
+  \param size
+  \param marker
+  \param pt 3d point (Point3)
 */
-/* do normal transforms before calling */
-/* Note gs: NULL if 3d obj or const elev surface */
 void gpd_obj(geosurf * gs, int color, float size, int marker, Point3 pt)
 {
     float sz, lpt[3];
@@ -288,11 +317,24 @@ void gpd_obj(geosurf * gs, int color, float size, int marker, Point3 pt)
     return;
 }
 
-/* need to think about translations - If user translates surface,
-sites should automatically go with it, but translating sites should
-translate it relative to surface on which it's displayed */
-/*  TODO: prevent scaling by 0  */
-/* handling mask checking here */
+/*!
+  \brief ADD
+
+  Need to think about translations - If user translates surface,
+  sites should automatically go with it, but translating sites should
+  translate it relative to surface on which it's displayed
+
+  Handling mask checking here
+  
+  \todo prevent scaling by 0 
+
+  \param gp site (geosite)
+  \param gs surface (geosurf)
+  \param do_fast (unused)
+
+  \return 0
+  \return 1
+*/
 int gpd_2dsite(geosite * gp, geosurf * gs, int do_fast)
 {
     float site[3], konst;
@@ -393,6 +435,16 @@ int gpd_2dsite(geosite * gp, geosurf * gs, int do_fast)
     return (1);
 }
 
+/*!							       
+  \brief ADD
+
+  \param gp site (geosite)
+  \param xo,yo
+  \param do_fast (unused)
+
+  \return 0
+  \return 1
+*/
 int gpd_3dsite(geosite * gp, float xo, float yo, int do_fast)
 {
     float site[3], tz;

lib/ogsf/gs_bm.c

@@ -1,7 +1,7 @@
 /*!
   \file gs_bm.c
  
-  \brief OGSF library - loading and manipulating surfaces
+  \brief OGSF library - manipulating bitmaps (lower level functions)
  
   GRASS OpenGL gsurf OGSF Library 
  
@@ -13,14 +13,24 @@
   for details.
   
   \author Bill Brown USACERL, GMSL/University of Illinois (September 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
+#include <stdio.h>
 #include <grass/gstypes.h>
+#include <grass/glocale.h>
 #include "gsget.h"
-#include <stdio.h>
 
-/* do combining of bitmaps, make bitmaps from other data w/maskval */
+/*!
+  \brief Do combining of bitmaps, make bitmaps from other data w/maskval
+
+  \param frombuff data buffer
+  \param maskval mask type
+  \param rows number of rows
+  \param cols number of cols
 
+  \return pointer to BM struct
+*/
 struct BM *gsbm_make_mask(typbuff * frombuff, float maskval, int rows,
 			  int cols)
 {
@@ -59,6 +69,11 @@ struct BM *gsbm_make_mask(typbuff * frombuff, float maskval, int rows,
     return (bm);
 }
 
+/*!
+  \brief Zero mask
+
+  \param map pointer to BM struct
+*/
 void gsbm_zero_mask(struct BM *map)
 {
     int numbytes;
@@ -74,13 +89,26 @@ void gsbm_zero_mask(struct BM *map)
     return;
 }
 
-/* mask types */
+/*!
+  \brief mask types
+*/
 #define MASK_OR		1
 #define MASK_ORNOT	2
 #define MASK_AND	3
 #define MASK_XOR	4
 
-/* must be same size, ORs bitmaps & stores in bmvar */
+/*!
+  \brief Mask bitmap
+
+  Must be same size, ORs bitmaps & stores in bmvar
+
+  \param bmvar bitmap (BM) to changed
+  \param bmcom bitmap (BM)
+  \param mask_type mask type (see mask types macros)
+
+  \return -1 on failure (bitmap mispatch)
+  \return 0 on success
+*/
 static int gsbm_masks(struct BM *bmvar, struct BM *bmcon, const int mask_type)
 {
     int i;
@@ -92,8 +120,7 @@ static int gsbm_masks(struct BM *bmvar, struct BM *bmcon, const int mask_type)
 
     if (bmcon && bmvar) {
 	if (varsize != consize) {
-	    fprintf(stderr, "bitmap mismatch\n");
-
+	    G_warning (_("Bitmap mismatch"));
 	    return (-1);
 	}
 
@@ -104,52 +131,103 @@ static int gsbm_masks(struct BM *bmvar, struct BM *bmcon, const int mask_type)
         case MASK_OR:
             for (i = 0; i < numbytes; i++)
                 bmvar->data[i] |= bmcon->data[i];
-        break;
+	    break;
         case MASK_ORNOT:
             for (i = 0; i < numbytes; i++)
                 bmvar->data[i] |= ~bmcon->data[i];
-        break;
+	    break;
         case MASK_AND:
             for (i = 0; i < numbytes; i++)
                 bmvar->data[i] &= bmcon->data[i];
-        break;
+	    break;
         case MASK_XOR:
             for (i = 0; i < numbytes; i++)
                 bmvar->data[i] ^= bmcon->data[i];
-        break;
+	    break;
         }
-
+	
 	return (0);
     }
 
     return (-1);
 }
 
-/* must be same size, ORs bitmaps & stores in bmvar */
+/*!
+  \brief Mask bitmap (mask type OR)
+
+  Must be same size, ORs bitmaps & stores in bmvar
+
+  \param bmvar bitmap (BM) to changed
+  \param bmcom bitmap (BM)
+  \param mask_type mask type (see mask types macros)
+
+  \return -1 on failure (bitmap mispatch)
+  \return 0 on success
+*/
 int gsbm_or_masks(struct BM *bmvar, struct BM *bmcon)
 {
     return gsbm_masks(bmvar, bmcon, MASK_OR);
 }
 
-/* must be same size, ORs bitmap with ~bmcon & stores in bmvar */
+/*!
+  \brief Mask bitmap (mask type ORNOT)
+
+  Must be same size, ORNOTs bitmaps & stores in bmvar
+
+  \param bmvar bitmap (BM) to changed
+  \param bmcom bitmap (BM)
+  \param mask_type mask type (see mask types macros)
+
+  \return -1 on failure (bitmap mispatch)
+  \return 0 on success
+*/
 int gsbm_ornot_masks(struct BM *bmvar, struct BM *bmcon)
 {
     return gsbm_masks(bmvar, bmcon, MASK_ORNOT);
 }
 
-/* must be same size, ANDs bitmaps & stores in bmvar */
+/*!
+  \brief Mask bitmap (mask type ADD)
+
+  Must be same size, ADDs bitmaps & stores in bmvar
+
+  \param bmvar bitmap (BM) to changed
+  \param bmcom bitmap (BM)
+  \param mask_type mask type (see mask types macros)
+
+  \return -1 on failure (bitmap mispatch)
+  \return 0 on success
+*/
 int gsbm_and_masks(struct BM *bmvar, struct BM *bmcon)
 {
     return gsbm_masks(bmvar, bmcon, MASK_AND);
 }
 
-/* must be same size, XORs bitmaps & stores in bmvar */
+/*!
+  \brief Mask bitmap (mask type XOR)
+
+  Must be same size, XORs bitmaps & stores in bmvar
+
+  \param bmvar bitmap (BM) to changed
+  \param bmcom bitmap (BM)
+  \param mask_type mask type (see mask types macros)
+
+  \return -1 on failure (bitmap mispatch)
+  \return 0 on success
+*/
 int gsbm_xor_masks(struct BM *bmvar, struct BM *bmcon)
 {
     return gsbm_masks(bmvar, bmcon, MASK_XOR);
 }
 
-/***********************************************************************/
+/*!
+  \brief Update current maps
+
+  \param surf surface (geosurf)
+
+  \return 0
+  \return 1
+*/
 int gs_update_curmask(geosurf * surf)
 {
     struct BM *b_mask, *b_topo, *b_color;
@@ -157,6 +235,8 @@ int gs_update_curmask(geosurf * surf)
     int row, col, offset, destroy_ok = 1;
     gsurf_att *coloratt;
 
+    G_debug (3, "gs_update_curmask():");
+
     if (surf->mask_needupdate) {
 	surf->mask_needupdate = 0;
 	surf->norm_needupdate = 1;	/* edges will need to be recalculated */
@@ -223,24 +303,24 @@ int gs_update_curmask(geosurf * surf)
 	    }
 
 	    if (b_topo) {
-		fprintf(stderr, "Update topo mask\n");
+		G_debug(3, "  Update topo mask");
 		gsbm_or_masks(surf->curmask, b_topo);
 		BM_destroy(b_topo);
 	    }
 
 	    if (b_color) {
-		fprintf(stderr, "Update color mask\n");
+		G_debug(3, "  Update color mask");
 		gsbm_or_masks(surf->curmask, b_color);
 		BM_destroy(b_color);
 	    }
 
 	    if (t_topo->nm) {
-		fprintf(stderr, "Update elev null mask\n");
+		G_debug(3, "  Update elev null mask");
 		gsbm_or_masks(surf->curmask, t_topo->nm);
 	    }
 
 	    if (b_mask) {
-		fprintf(stderr, "Update mask mask\n");
+		G_debug(3, "  Update mask mask");
 
 		if (t_mask->bm) {
 		    if (surf->att[ATT_MASK].constant) {
@@ -274,7 +354,11 @@ int gs_update_curmask(geosurf * surf)
     return (0);
 }
 
-/***********************************************************************/
+/*!
+  \brief Print bitmap to stderr
+
+  \param bm bitmap (BM)
+*/
 void print_bm(struct BM *bm)
 {
     int i, j;