"Final" changes for first draft of 1.0 documentation.

git-svn-id: file:///fltk/svn/fltk/trunk@187 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 140 insertions, 91 deletions

diff --git a/documentation/glut.html b/documentation/glut.html
index 3cbfdb50e..643f66dc2 100644
--- a/documentation/glut.html
+++ b/documentation/glut.html
@@ -3,143 +3,192 @@
 
 <H1 ALIGN=RIGHT><A NAME="glut">D - GLUT Compatibility</A></H1>
 
-You should be able to compile existing Glut source code by
-including &lt;FL/glut.H> instead of &lt;GL/glut.h>.  This can be done by
-editing the source, by changing the -I switches to the compiler, or by
-providing a symbolic link from GL/glut.h to FL/glut.H.
+This appendix describes the GLUT compatibility header file supplied with
+FLTK.
 
-<p>All files calling glut procedures must be compiled with C++.  You may
+<H2>Using the GLUT Compatibility Header File</H2>
+
+You should be able to compile existing GLUT source code by including
+<tt>&lt;FL/glut.H></tt> instead of <tt>&lt;GL/glut.h></tt>.  This can
+be done by editing the source, by changing the <tt>-I</tt> switches to
+the compiler, or by providing a symbolic link from <tt>GL/glut.h</tt>
+to <tt>FL/glut.H</tt>.
+
+<p><i>All files calling GLUT procedures must be compiled with C++</i>.  You may
 have to alter them slightly to get them to compile without warnings,
 and you may have to rename them to get make to use the C++ compiler.
-I was unable to get some calls to glu to compile without adding some
-casts, apparently due to errors in the glu header files.
 
-<p>You must link with -lFl.  If you call any glut drawing functions
-that fltk does not emulate (<code>glutExtensionsSupported(), glutWire*(),
-glutSolid*(), and glutStroke*()</code>), you will also have to link with
--lglut, <i>after</i> -lFl.
+<p>You must link with the FLTK library.  If you call any GLUT drawing
+functions that FLTK does not emulate
+(<tt>glutExtensionsSupported()</tt>, <tt>glutWire*()</tt>,
+<tt>glutSolid*()</tt>, and <tt>glutStroke*()</tt>), you will also have
+to link with the GLUT library (<i>after</i> the FLTK library!)
 
-<p>Most of glut.H is inline functions.  You should take a look at it
-(and maybe at glut.C in the fltk source) if you are having trouble
-porting your Glut program.
+<p>Most of <tt>FL/glut.H</tt> is inline functions.  You should take a
+look at it (and maybe at <tt>test/glut.cxx</tt> in the FLTK source) if
+you are having trouble porting your GLUT program.
 
 <p>This has been tested with most of the demo programs that come with
-the Glut 3.3 distribution.
+the GLUT 3.3 distribution.
 
 <h2>Known Problems</h2>
 
+The following functions and/or arguments to functions are missing,
+and you will have to replace them or comment them out for your code to
+compile:
+
 <ul>
 
-<li>The following functions and/or arguments to functions are missing,
-and you will have to replace them or comment them out for your code to
-compile:<ul>
-
-<li><code>glutLayerGet(GLUT_LAYER_IN_USE)</code>
-<li><code>glutLayerGet(GLUT_HAS_OVERLAY)</code>
-<li><code>glutSetColor(), glutGetColor(), glutCopyColormap()</code>
-<li><code>glutInitDisplayMode(GLUT_STEREO)</code>
-<li><code>glutInitDisplayMode(GLUT_LUMINANCE)</code>
-<li><code>glutPushWindow()</code>
-<li><code>glutWarpPointer()</code>
-<li>Spaceball, buttonbox, dials, tablet functions, <code>glutDeviceGet()</code>
-<li><code>glutWindowStatusFunc()</code>
-<li><code>glutGet(GLUT_WINDOW_NUM_CHILDREN)</code>
-<li><code>glutGet(GLUT_SCREEN_WIDTH_MM)</code>
-<li><code>glutGet(GLUT_SCREEN_HEIGHT_MM)</code>
-<li><code>glutGet(GLUT_ELAPSED_TIME)</code>
-<li><code>glutVideoResize()</code> missing.
+	<li><tt>glutLayerGet(GLUT_LAYER_IN_USE)</tt>
+	<li><tt>glutLayerGet(GLUT_HAS_OVERLAY)</tt>
+	<li><tt>glutSetColor(), glutGetColor(), glutCopyColormap()</tt>
+	<li><tt>glutInitDisplayMode(GLUT_STEREO)</tt>
+	<li><tt>glutInitDisplayMode(GLUT_LUMINANCE)</tt>
+	<li><tt>glutPushWindow()</tt>
+	<li><tt>glutWarpPointer()</tt>
+	<li>Spaceball, buttonbox, dials, tablet functions,
+	<tt>glutDeviceGet()</tt>
+	<li><tt>glutWindowStatusFunc()</tt>
+	<li><tt>glutGet(GLUT_WINDOW_NUM_CHILDREN)</tt>
+	<li><tt>glutGet(GLUT_SCREEN_WIDTH_MM)</tt>
+	<li><tt>glutGet(GLUT_SCREEN_HEIGHT_MM)</tt>
+	<li><tt>glutGet(GLUT_ELAPSED_TIME)</tt>
+	<li><tt>glutVideoResize()</tt> missing.
 
 </ul>
 
-<li>Most of the symbols/enumerations have different values than
-Glut uses.  This will break code that relies on the actual values.
+Most of the symbols/enumerations have different values than
+GLUT uses.  This will break code that relies on the actual values.
 The only symbols guaranteed to have the same values are true/false
-pairs like <code>GLUT_DOWN</code> and <code>GLUT_UP</code>, mouse
-buttons <code>GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON,
-GLUT_RIGHT_BUTTON</code>, and <code>GLUT_KEY_F1</code> thru
-<code>F12</code>.
+pairs like <tt>GLUT_DOWN</tt> and <tt>GLUT_UP</tt>, mouse
+buttons <tt>GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON,
+GLUT_RIGHT_BUTTON</tt>, and <tt>GLUT_KEY_F1</tt> thru
+<tt>F12</tt>.
 
-<li><i>The strings passed as menu labels are not copied</i>.
+<p>The strings passed as menu labels are not copied.
 
-<li><code>glutPostRedisplay()</code> does not work if called from
-inside a display function.  You must use <code>glutIdleFunc()</code>
+<p><tt>glutPostRedisplay()</tt> does not work if called from
+inside a display function.  You must use <tt>glutIdleFunc()</tt>
 if you want your display to update continuously.
 
-<li><code>glutSwapBuffers()</code> does not work from inside a display
-function.  This is on purpose, because fltk swaps the buffers for you.
+<p><tt>glutSwapBuffers()</tt> does not work from inside a display
+function.  This is on purpose, because FLTK swaps the buffers for you.
 
-<li><code>glutUseLayer()</code> does not work well, and should only be
+<p><tt>glutUseLayer()</tt> does not work well, and should only be
 used to initialize transformations inside a resize callback.  You
-should redraw overlays by using <code>glutOverlayDisplayFunc()</code>.
+should redraw overlays by using <tt>glutOverlayDisplayFunc()</tt>.
 
-<li>Overlays are cleared before the overlay display function is
-called.  <code>glutLayerGet(GLUT_OVERLAY_DAMAGED)</code> always
-returns true, this fixed some glut overlay programs.  You must rewrite
-your code so that gl_color() is used to choose colors in an overlay,
-or you will get random overlay colors.
+<p>Overlays are cleared before the overlay display function is called. 
+<tt>glutLayerGet(GLUT_OVERLAY_DAMAGED)</tt> always returns true for
+compatibility with some GLUT overlay programs.  You must rewrite your
+code so that <tt>gl_color()</tt> is used to choose colors in an
+overlay, or you will get random overlay colors.
 
-<li><code>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</code> just
+<p><tt>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</tt> just
 results in a small crosshair.
 
-<li>The fonts used by <code>glutBitmapCharacter() and
-glutBitmapWidth()</code> may be different.
+<p>The fonts used by <tt>glutBitmapCharacter() and
+glutBitmapWidth()</tt> may be different.
 
-<li><code>glutInit(argc,argv)</code> will consume different switches than glut
+<p><tt>glutInit(argc,argv)</tt> will consume different switches than GLUT
 does.  It accepts the switches recognized by <a
-href=Fl.html>Fl_Window::arg()</a>, and will accept any
-abbreviation of these switches (such as -d for -display).
+href="#args"><tt>Fl::args()</tt></a>, and will accept any
+abbreviation of these switches (such as "-di" for "-display").
 
-</ul>
+<h2>Mixing GLUT and FLTK Code</h2>
+
+You can make your GLUT window a child of a <tt>Fl_Window</tt> with the
+following scheme.  The biggest trick is that GLUT insists on
+<tt>show()</tt>'ing the window at the point it is created, which means the
+<tt>Fl_Window</tt> parent window must already be shown.
+
+<ul>
+
+	<li>Don't call <tt>glutInit()</tt>.
+
+	<li>Create your <tt>Fl_Window</tt>, and any FLTK widgets. 
+	Leave a blank area in the window for your GLUT window.
+
+	<li><tt>show()</tt> the <tt>Fl_Window</tt>.  Perhaps call
+	<tt>show(argc,argv)</tt>.
 
-<h2>Mixing Glut code and Fltk code</h2>
+	<li>Call <tt>window->begin()</tt> so that the GLUT window will
+	be automatically added to it.
 
-You can make your Glut window a child of a Fl_Window with the
-following scheme.  The biggest trick is that Glut insists on
-show()'ing the window at the point it is created, which means the
-Fl_Window parent window must already be show()n.
+	<li>Use <tt>glutInitWindowSize()</tt> and
+	<tt>glutInitWindowPosition()</tt> to set the location in the
+	parent window to put the GLUT window.
 
-<p>Don't call glutInit().
+	<li>Put your GLUT code next.  It probably does not need many changes.
+	Call <tt>window->end()</tt> immediately after the <tt>glutCreateWindow()</tt>!
 
-<p>Create your Fl_Window, and any fltk widgets.  Leave a blank area in
-the window for your glut window.
+	<li>You can call either <tt>glutMainLoop()</tt>,
+	<tt>Fl::run()</tt>, or loop calling <tt>Fl::wait()</tt> to run
+	the program.
 
-<p>show() the Fl_Window.  Perhaps call show(argc,argv).
+</ul>
+
+<hr break>
+
+<h2><a name="Fl_Glut_Window">class Fl_Glut_Window</a></h2>
 
-<p>Call window->begin() so the glut window will be automatically added
-to it.
+<hr>
 
-<p>Use glutInitWindowSize() and glutInitWindowPosition() to set the
-location in the parent window to put the glut window.
+<h3>Class Hierarchy</h3>
 
-<p>Put your glut code next.  It probably does not need many changes.
-Call window->end() immediately after the glutCreateWindow()!
+<ul><pre>
+<a href="#Fl_Gl_Window">Fl_Gl_Window</a>
+   |
+   +----<b>Fl_Glut_Window</b>
+</pre></ul>
 
-<p>You can call either glutMainLoop() or Fl::run() or loop calling
-Fl::wait() to run the program.
+<h3>Include Files</h3>
 
-<h2>class Fl_Glut_Window : public <a href=Fl_Gl_Window.html>Fl_Gl_Window</a></h2>
+<ul><pre>
+#include &lt;FL/glut.H>
+</pre></ul>
 
-Each Glut window is an instance of this class, which is a subclass of
-<a href=Fl_Gl_Window.html>Fl_Gl_Window</a>.  You may find it useful to
-manipulate instances directly rather than use glut window id's.  These
+<h3>Description</h3>
+
+Each GLUT window is an instance of this class.  You may find it useful to
+manipulate instances directly rather than use GLUT window id's.  These
 may be created without opening the display, and thus can fit better
-into FL's method of creating windows.
+into FLTK's method of creating windows.
 
-<p>The current glut window is available in <code>Fl_Glut_Window
-*glut_window</code>.
+<p>The current GLUT window is available in the global variable
+<tt>glut_window</tt>.
 
-<p><code>new Fl_Glut_Window(...)</code> is the same as
-<code>glutCreateWindow()</code> except it does not show() the window
+<p><tt>new Fl_Glut_Window(...)</tt> is the same as
+<tt>glutCreateWindow()</tt> except it does not <tt>show()</tt> the window
 or make the window current.
 
-<p><code>window->make_current()</code> is the same as
-<code>glutSetWindow(number)</code>.  If the window has not had show()
-called on it yet, some functions that assumme a gl context will not
-work.  If you do show() the window, call make_current() again to set
-the context.
+<p><tt>window->make_current()</tt> is the same as
+<tt>glutSetWindow(number)</tt>.  If the window has not had
+<tt>show()</tt> called on it yet, some functions that assumme an OpenGL
+context will not work.  If you do <tt>show()</tt> the window, call
+<tt>make_current()</tt> again to set the context.
+
+<p><tt>~Fl_Glut_Window()</tt> is the same as
+<tt>glutDestroyWindow()</tt>.
+
+<h3>Methods</h3>
+
+<ul>
+	<li><a href="#Fl_Glut_Window.Fl_Glut_Window">Fl_Glut_Window</a>
+	<li><a href="#Fl_Glut_Window.~Fl_Glut_Window">~Fl_Glut_Window</a>
+</ul>
+
+<h4><a name="Fl_Glut_Window.Fl_Glut_Window">Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char *title = 0)<br>
+Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)</a></h4>
+
+The first constructor takes 4 int arguments to create the window with
+a preset position and size.  The second constructor with 2 arguments
+will create the window with a preset size, but the window manager
+will choose the position according to it's own whims.
+
+<h4><a name="Fl_Glut_Window.~Fl_Glut_Window">virtual Fl_Glut_Window::~Fl_Glut_Window()</a></h4>
 
-<p><code>~Fl_Glut_Window()</code> is the same as
-<code>glutDestroyWindow()</code>.
+Destroys the GLUT window.
 
 </BODY>
 </HTML>