added doxygen coments for more routines in fl_draw.H

FL/fl_draw.H: fl_rectf(), fl_read_image()
src/fl_draw_pixmap.cxx: fl_draw_pixmap(), fl_measure_pixmap()
documentation/src/drawing.dox: corrected paragraph link tags



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6689 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

3 files changed, 72 insertions, 12 deletions

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index 5ac267515..f1bf89e53 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -99,6 +99,15 @@ FL_EXPORT void fl_rectf(int x, int y, int w, int h);
 /** Colors a rectangle that exactly fills the given bounding box */
 inline void fl_rectf(int x, int y, int w, int h, Fl_Color c) {fl_color(c); fl_rectf(x,y,w,h);}
 
+/**
+  Color a rectangle with "exactly" the passed <tt>r,g,b</tt> color.
+  On screens with less than 24 bits of color this is done by drawing a
+  solid-colored block using fl_draw_image() so that the correct color
+  shade is produced.
+  */
+/* note: doxygen comment here to avoid triplication in os-speciic files */
+FL_EXPORT void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b);
+
 // line segments:
 FL_EXPORT void fl_line(int x, int y, int x1, int y1);
 FL_EXPORT void fl_line(int x, int y, int x1, int y1, int x2, int y2);
@@ -389,16 +398,39 @@ FL_EXPORT void fl_draw_image(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,
   */
 FL_EXPORT void fl_draw_image_mono(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,int H, int D=1);
 
-FL_EXPORT void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b);
+/**
+  Checks whether platform supports true alpha blending for RGBA images.
+  \returns 1 if true alpha blending supported by platform
+  \returns 0 not supported so FLTK will use screen door transparency
+  */
+/* note: doxygen comment here to avoid triplication in os-speciic files */
 FL_EXPORT char fl_can_do_alpha_blending();
 
-FL_EXPORT uchar *fl_read_image(uchar *p, int x,int y, int w, int h, int alpha=0);
+/**
+  Read an RGB(A) image from the current window or off-screen buffer.
+  \param[in] p     pixel buffer, or NULL to allocate one
+  \param[in] X,Y   position of top-left of image to read
+  \param[in] W,H   width and height of image to read
+  \param[in] alpha alpha value for image (0 fr none)
+  \returns pointer to pixel buffer, or NULL if allocation failed.
+
+  The \a p argument points to a buffer that can hold the image and must
+  be at least \a W*H*3 bytes when reading RGB images, or \a W*H*4 bytes
+  when reading RGBA images. If NULL, fl_read_image() will create an
+  array of the proper suze which can be freed using <tt>delete[]</tt>.
+
+  The \a alpha parameter controls whether an alpha channel is created
+  and the value that is placed in the alpha channel. If 0, no alpha
+  channel is generated.
+  */
+/* note: doxygen comment here to avoid triplication in os-speciic files */
+FL_EXPORT uchar *fl_read_image(uchar *p,int X,int Y,int W,int H,int alpha=0);
 
 // pixmaps:
 FL_EXPORT int fl_draw_pixmap(/*const*/ char* const* data, int x,int y,Fl_Color=FL_GRAY);
+FL_EXPORT int fl_draw_pixmap(const char* const* cdata, int x,int y,Fl_Color=FL_GRAY);
 FL_EXPORT int fl_measure_pixmap(/*const*/ char* const* data, int &w, int &h);
-FL_EXPORT int fl_draw_pixmap(const char* const* data, int x,int y,Fl_Color=FL_GRAY);
-FL_EXPORT int fl_measure_pixmap(const char* const* data, int &w, int &h);
+FL_EXPORT int fl_measure_pixmap(const char* const* cdata, int &w, int &h);
 
 // other:
 FL_EXPORT void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 4596c1a42..40c7b4470 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -821,7 +821,8 @@ If <tt>D</tt> is 4 or more, you must fill in the unused bytes
 with zero.
 
 <A NAME="fl_draw_pixmap"></A> <!-- For old HTML links only ! -->
-int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)
+int fl_draw_pixmap(char* const* data, int x, int y, Fl_Color bg) <br>
+int fl_draw_pixmap(const char* const* cdata, int x, int y, Fl_Color bg)
 
 \par
 Draws XPM image data, with the top-left corner at the given position.
@@ -844,7 +845,8 @@ Fl_Color argument. To draw with true transparency you must
 use the Fl_Pixmap class.
 
 <A NAME="fl_measure_pixmap"></A> <!-- For old HTML links only ! -->
-int fl_measure_pixmap(char **data, int &w, int &h)
+int fl_measure_pixmap(char* const* data, int &w, int &h) <br>
+int fl_measure_pixmap(const char* const* cdata, int &w, int &h)
 
 \par
 An XPM image contains the dimensions in its data. This
@@ -858,7 +860,7 @@ FLTK provides a single function for reading from the current
 window or off-screen buffer into a RGB(A) image buffer.
 
 <A NAME="fl_read_image"></A> <!-- For old HTML links only ! -->
-uchar *fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha = 0);
+uchar* fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha)
 
 \par
 Read a RGB(A) image from the current window or off-screen
diff --git a/src/fl_draw_pixmap.cxx b/src/fl_draw_pixmap.cxx
index dbb72efd2..e552f7a76 100644
--- a/src/fl_draw_pixmap.cxx
+++ b/src/fl_draw_pixmap.cxx
@@ -43,12 +43,25 @@
 
 static int ncolors, chars_per_pixel;
 
+/**
+  Get the dimensions of a pixmap.
+  An XPM image contains the dimensions in its data. This function
+  returns te width and height.
+  \param[in]  data pointer to XPM image data.
+  \param[out] w,h  width and height of image
+  \returns non-zero if the dimensions were parsed OK
+  \returns 0 if there were any problems
+  */
 int fl_measure_pixmap(/*const*/ char* const* data, int &w, int &h) {
   return fl_measure_pixmap((const char*const*)data,w,h);
 }
 
-int fl_measure_pixmap(const char * const *data, int &w, int &h) {
-  int i = sscanf(data[0],"%d%d%d%d",&w,&h,&ncolors,&chars_per_pixel);
+/**
+  Get the dimensions of a pixmap.
+  \see fl_measure_pixmap(char* const* data, int &w, int &h)
+  */
+int fl_measure_pixmap(const char * const *cdata, int &w, int &h) {
+  int i = sscanf(cdata[0],"%d%d%d%d",&w,&h,&ncolors,&chars_per_pixel);
   if (i<4 || w<=0 || h<=0 ||
       chars_per_pixel!=1 && chars_per_pixel!=2) return w=0;
   return 1;
@@ -153,14 +166,27 @@ static void cb2(void*v, int x, int y, int w, uchar* buf) {
 
 uchar **fl_mask_bitmap; // if non-zero, create bitmap and store pointer here
 
+/**
+  Draw XPM image data, with the top-left corner at the given position.
+  The image is dithered on 8-bit displays so you won't lose color
+  space for programs displaying both images and pixmaps.
+  \param[in] data pointer to XPM image data
+  \param[in] x,y  position of top-left corner
+  \param[in] bg   background color
+  \returns 0 if there was any error decoding the XPM data.
+  */
 int fl_draw_pixmap(/*const*/ char* const* data, int x,int y,Fl_Color bg) {
   return fl_draw_pixmap((const char*const*)data,x,y,bg);
 }
 
-int fl_draw_pixmap(const char*const* di, int x, int y, Fl_Color bg) {
+/**
+  Draw XPM image data, with the top-left corner at the given position.
+  \see fl_draw_pixmap(char* const* data, int x, int y, Fl_Color bg)
+  */
+int fl_draw_pixmap(const char*const* cdata, int x, int y, Fl_Color bg) {
   pixmap_data d;
-  if (!fl_measure_pixmap(di, d.w, d.h)) return 0;
-  const uchar*const* data = (const uchar*const*)(di+1);
+  if (!fl_measure_pixmap(cdata, d.w, d.h)) return 0;
+  const uchar*const* data = (const uchar*const*)(cdata+1);
   int transparent_index = -1;
 
   if (ncolors < 0) {	// FLTK (non standard) compressed colormap