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, 34 insertions, 0 deletions

diff --git a/src/Fl_visual.cxx b/src/Fl_visual.cxx
index a0487c046..c19fa5b03 100644
--- a/src/Fl_visual.cxx
+++ b/src/Fl_visual.cxx
@@ -31,6 +31,40 @@
 #include <FL/Fl.H>
 #include <FL/x.H>
 
+/** \fn  Fl::visual(int flags)
+    Selects a visual so that your graphics are drawn correctly.  This is
+    only allowed before you call show() on any windows.  This does nothing
+    if the default visual satisfies the capabilities, or if no visual
+    satisfies the capabilities, or on systems that don't have such
+    brain-dead notions.
+    
+    <P>Only the following combinations do anything useful:
+    
+    <UL>
+    <LI>Fl::visual(FL_RGB)
+    <BR>Full/true color (if there are several depths FLTK chooses  the
+    largest).  Do this if you use fl_draw_image
+    for much better (non-dithered)  output.
+    <BR>&nbsp; </LI>
+    <LI>Fl::visual(FL_RGB8)
+    <BR>Full color with at least 24 bits of color. FL_RGB will
+    always  pick this if available, but if not it will happily return a
+    less-than-24 bit deep visual.  This call fails if 24 bits are not
+    available.
+    <BR>&nbsp; </LI>
+    <LI>Fl::visual(FL_DOUBLE|FL_INDEX)
+    <BR>Hardware double buffering.  Call this if you are going to use 
+    Fl_Double_Window.
+    <BR>&nbsp; </LI>
+    <LI>Fl::visual(FL_DOUBLE|FL_RGB)</LI>
+    <LI>Fl::visual(FL_DOUBLE|FL_RGB8)
+    <BR>Hardware double buffering and full color.
+    </UL>
+    
+    <P>This returns true if the system has the capabilities by default or
+    FLTK suceeded in turing them on.  Your program will still work even if
+    this returns false (it just won't look as good).
+*/
 #ifdef WIN32
 int Fl::visual(int flags) {
   fl_GetDC(0);