Added Doxygen doc to offscreen drawing functions.

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

3 files changed, 41 insertions, 13 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index dfd2a48c9..d96507ccc 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -779,7 +779,9 @@ public:
 
   /**   @} */
  /** \defgroup  fl_drawings  Drawing functions
-	fl global graphics and gui drawing functions
+  FLTK global graphics and GUI drawing functions.
+  These functions are declared in <FL/fl_draw.H>, 
+  and in <FL/x.H> for offscreen buffer-related ones.
      @{ */
   // <Hack to re-order the 'Drawing functions' group>
  /** @} */
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 299709574..68bb2df24 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -925,15 +925,13 @@ This is the same as doing \p draw(x,y,img->w(),img->h(),0,0).
 
 \subsection ssect_Offscreen Offscreen Drawing
 
-\todo
-Doxygenate the offscreen drawing functions.
-
 Sometimes it can be very useful to generate a complex drawing
 in memory first and copy it to the screen at a later point in 
 time. This technique can significantly reduce the amount of
-repeated drawing. Fl_Double_Window uses offscreen rendering
+repeated drawing. Offscreen drawing functions are declared in <FL/x.H>.
+Fl_Double_Window uses offscreen rendering
 to avoid flickering on systems that don't support 
-double-buffering natively.
+double-buffering natively. 
 
 Fl_Offscreen fl_create_offscreen(int w, int h)
 
@@ -957,8 +955,7 @@ void fl_end_offscreen()
 \par
 Quit sending drawing commands to this offscreen buffer.
 
-void fl_copy_offscreen(int x, int y, int w, int h,
-Fl_Offscreen osrc, int srcx, int srcy)
+void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen osrc, int srcx, int srcy)
 
 \par
 Copy a rectangular area of the size \p w*h from \p srcx,srcy
diff --git a/src/Fl_Double_Window.cxx b/src/Fl_Double_Window.cxx
index a09134879..b12d1f183 100644
--- a/src/Fl_Double_Window.cxx
+++ b/src/Fl_Double_Window.cxx
@@ -67,6 +67,15 @@ void Fl_Double_Window::show() {
 
 static void fl_copy_offscreen_to_display(int x, int y, int w, int h, Fl_Offscreen pixmap, int srcx, int srcy);
 
+/** \addtogroup fl_drawings
+ @{
+ */
+/** Copy a rectangular area of the given offscreen buffer into the current drawing destination.
+ \param x,y	position where to draw the copied rectangle
+ \param w,h	size of the copied rectangle
+ \param pixmap  offscreen buffer containing the rectangle to copy
+ \param srcx,srcy origin in offscreen buffer of rectangle to copy
+ */
 void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen pixmap, int srcx, int srcy) {
   if( fl_graphics_driver == fl_display_device->driver()) {
     fl_copy_offscreen_to_display(x, y, w, h, pixmap, srcx, srcy);
@@ -79,6 +88,7 @@ void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen pixmap, int srcx
     delete img;
   }
 }
+/** @} */
 
 #if defined(USE_X11)
 
@@ -184,26 +194,35 @@ void fl_copy_offscreen_with_alpha(int x,int y,int w,int h,HBITMAP bitmap,int src
 
 extern void fl_restore_clip();
 
-#elif defined(__APPLE_QUARTZ__)
+#elif defined(__APPLE_QUARTZ__) || defined(FL_DOXYGEN)
 
 char fl_can_do_alpha_blending() {
   return 1;
 }
 
-Fl_Offscreen fl_create_offscreen(int w, int h) {
+Fl_Offscreen fl_create_offscreen_with_alpha(int w, int h) {
   void *data = calloc(w*h,4);
   CGColorSpaceRef lut = CGColorSpaceCreateDeviceRGB();
   CGContextRef ctx = CGBitmapContextCreate(
-    data, w, h, 8, w*4, lut, kCGImageAlphaNoneSkipLast);
+    data, w, h, 8, w*4, lut, kCGImageAlphaPremultipliedLast);
   CGColorSpaceRelease(lut);
   return (Fl_Offscreen)ctx;
 }
 
-Fl_Offscreen fl_create_offscreen_with_alpha(int w, int h) {
+/** \addtogroup fl_drawings
+ @{
+ */
+
+/** 
+  Creation of an offscreen graphics buffer.
+ \param w,h     width and height in pixels of the buffer.
+ \return    the created graphics buffer.
+ */
+Fl_Offscreen fl_create_offscreen(int w, int h) {
   void *data = calloc(w*h,4);
   CGColorSpaceRef lut = CGColorSpaceCreateDeviceRGB();
   CGContextRef ctx = CGBitmapContextCreate(
-    data, w, h, 8, w*4, lut, kCGImageAlphaPremultipliedLast);
+    data, w, h, 8, w*4, lut, kCGImageAlphaNoneSkipLast);
   CGColorSpaceRelease(lut);
   return (Fl_Offscreen)ctx;
 }
@@ -238,6 +257,9 @@ static void fl_copy_offscreen_to_display(int x,int y,int w,int h,Fl_Offscreen os
   CGDataProviderRelease(src_bytes);
 }
 
+/**  Deletion of an offscreen graphics buffer.
+ \param ctx     the buffer to be deleted.
+ */
 void fl_delete_offscreen(Fl_Offscreen ctx) {
   if (!ctx) return;
   void *data = CGBitmapContextGetData((CGContextRef)ctx);
@@ -252,6 +274,9 @@ static CGContextRef stack_gc[stack_max];
 static Window stack_window[stack_max];
 static Fl_Surface_Device *_ss;
 
+/**  Send all subsequent drawing commands to this offscreen buffer.
+ \param ctx     the offscreen buffer.
+ */
 void fl_begin_offscreen(Fl_Offscreen ctx) {
   _ss = fl_surface; 
   fl_display_device->set_current();
@@ -268,6 +293,8 @@ void fl_begin_offscreen(Fl_Offscreen ctx) {
   fl_push_no_clip();
 }
 
+/** Quit sending drawing commands to the current offscreen buffer.
+ */
 void fl_end_offscreen() {
   Fl_X::q_release_context();
   fl_pop_clip();
@@ -282,6 +309,8 @@ void fl_end_offscreen() {
   _ss->set_current();
 }
 
+/** @} */
+
 extern void fl_restore_clip();
 
 #else