WP1 merged from my branch, WP2 reserved, todo list updated.

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

1 files changed, 109 insertions, 0 deletions

diff --git a/FL/Fl_Gl_Window.H b/FL/Fl_Gl_Window.H
index d13b832ca..cbe793baf 100644
--- a/FL/Fl_Gl_Window.H
+++ b/FL/Fl_Gl_Window.H
@@ -35,6 +35,24 @@ typedef void* GLContext; // actually a GLXContext or HGLDC
 
 class Fl_Gl_Choice; // structure to hold result of glXChooseVisual
 
+/**
+  The Fl_Gl_Window widget sets things up so OpenGL works, and
+  also keeps an OpenGL "context" for that window, so that changes to the
+  lighting and projection may be reused between redraws. Fl_Gl_Window
+  also flushes the OpenGL streams and swaps buffers after draw()
+  returns.
+  <P>OpenGL hardware typically provides some overlay bit planes, which
+  are very useful for drawing UI controls atop your 3D graphics.  If the
+  overlay hardware is not provided, FLTK tries to simulate the overlay,
+  This works pretty well if your graphics are double buffered, but not
+  very well for single-buffered. </P>
+  <P>Please note that the FLTK drawing and clipping functions
+  will not work inside an Fl_Gl_Window. All drawing
+  should be done using OpenGL calls exclusively.
+  Even though Fl_Gl_Window is derived from Fl_Group, 
+  it is not useful to add other FLTK Widgets as children,
+  unless those Widgets are modified to draw using OpenGL calls.
+*/
 class FL_EXPORT Fl_Gl_Window : public Fl_Window {
 
   int mode_;
@@ -61,16 +79,84 @@ public:
   void hide();
   void resize(int,int,int,int);
 
+  /**
+    Is turned off when FLTK creates a new
+    context for this window or when the window resizes, and is turned on <I>
+    after</I> draw() is called.  You can use this inside your 
+    draw() method to avoid unneccessarily initializing the OpenGL
+    context.  Just do this:
+    <UL><PRE>
+    void mywindow::draw() {
+     if (!valid()) {
+       glViewport(0,0,w(),h());
+       glFrustum(...);
+       ...other initialization...
+     }
+     if (!context_valid()) {
+       ...load textures, etc. ...
+     }
+     ... draw your geometry here ...
+    }
+    </PRE></UL>
+    
+    You can turn valid() on by calling valid(1).  You
+    should only do this after fixing the transformation inside a draw()
+    or after make_current().  This is done automatically after 
+    draw() returns.
+  */
   char valid() const {return valid_f_ & 1;}
+  /**
+    See char Fl_Gl_Window::valid() const 
+  */
   void valid(char v) {if (v) valid_f_ |= 1; else valid_f_ &= 0xfe;}
   void invalidate();
 
+  /**
+    Will only be set if the 
+    OpenGL context is created or recreated. It differs from
+    Fl_Gl_Window::valid() which is also set whenever the context
+    changes size.
+  */
   char context_valid() const {return valid_f_ & 2;}
+  /**
+    See char Fl_Gl_Window::context_valid() const 
+  */
   void context_valid(char v) {if (v) valid_f_ |= 2; else valid_f_ &= 0xfd;}
 
   static int can_do(int m) {return can_do(m,0);}
   static int can_do(const int *m) {return can_do(0, m);}
+  /**
+    See static int Fl_Gl_Window::can_do(int) 
+  */
   int can_do() {return can_do(mode_,alist);}
+  /**
+    Set or change the OpenGL capabilites of the window.  The value can be
+    any of the following OR'd together:
+    <UL>
+    <LI>FL_RGB - RGB color (not indexed) </LI>
+    <LI>FL_RGB8 - RGB color with at least 8 bits of each color </LI>
+    <LI>FL_INDEX - Indexed mode </LI>
+    <LI>FL_SINGLE - not double buffered </LI>
+    <LI>FL_DOUBLE - double buffered </LI>
+    <LI>FL_ACCUM - accumulation buffer </LI>
+    <LI>FL_ALPHA - alpha channel in color </LI>
+    <LI>FL_DEPTH - depth buffer </LI>
+    <LI>FL_STENCIL - stencil buffer </LI>
+    <LI>FL_MULTISAMPLE - multisample antialiasing </LI>
+    </UL>
+    FL_RGB and FL_SINGLE have a value of zero, so they
+    are &quot;on&quot; unless you give FL_INDEX or FL_DOUBLE.
+    <P>If the desired combination cannot be done, FLTK will try turning off 
+    FL_MULTISAMPLE.  If this also fails the show() will call 
+    Fl::error() and not show the window. </P>
+    <P>You can change the mode while the window is displayed.  This is most
+    useful for turning double-buffering on and off.  Under X this will
+    cause the old X window to be destroyed and a new one to be created.  If
+    this is a top-level window this will unfortunately also cause the
+    window to blink, raise to the top, and be de-iconized, and the xid()
+    will change, possibly breaking other code.  It is best to make the GL
+    window a child of another window if you wish to do this!
+  */
   Fl_Mode mode() const {return (Fl_Mode)mode_;}
   int mode(int a) {return mode(a,0);}
   int mode(const int *a) {return mode(0, a);}
@@ -81,12 +167,35 @@ public:
   void swap_buffers();
   void ortho();
 
+  /**
+    Returns true if the hardware overlay is possible.  If this is false,
+    FLTK will try to simulate the overlay, with significant loss of update
+    speed.  Calling this will cause FLTK to open the display.
+  */
   int can_do_overlay();
+  /**
+    This method causes draw_overlay to be called at a later time.
+    Initially the overlay is clear, if you want the window to display
+    something in the overlay when it first appears, you must call this
+    immediately after you show() your window.
+  */
   void redraw_overlay();
   void hide_overlay();
+  /**
+    The make_overlay_current() method selects the OpenGL context
+    for the widget's overlay.  It is called automatically prior to the 
+    draw_overlay() method being called and can also be used to
+    implement feedback and/or selection within the handle()
+    method.
+  */
   void make_overlay_current();
 
   ~Fl_Gl_Window();
+  /**
+    Creates a new Fl_Gl_Window widget using the given position,
+    size, and label string. The default boxtype is FL_NO_BOX. The
+    default mode is FL_RGB|FL_DOUBLE|FL_DEPTH.
+  */
   Fl_Gl_Window(int W, int H, const char *l=0) : Fl_Window(W,H,l) {init();}
   Fl_Gl_Window(int X, int Y, int W, int H, const char *l=0)
     : Fl_Window(X,Y,W,H,l) {init();}