converted more html to plain doxygen in {events,subclassing,opengl}.dox

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

1 files changed, 156 insertions, 163 deletions

diff --git a/documentation/opengl.dox b/documentation/opengl.dox
index c06d1bb4d..4fd6d6ec0 100644
--- a/documentation/opengl.dox
+++ b/documentation/opengl.dox
@@ -2,46 +2,42 @@
 
  \page	opengl	8 - Using OpenGL
 
-<P>This chapter discusses using FLTK for your OpenGL applications.
+This chapter discusses using FLTK for your OpenGL applications.
 
-<H2>Using OpenGL in FLTK</H2>
+\section opengl_using Using OpenGL in FLTK
 
-<P>The easiest way to make an OpenGL display is to subclass <A
-href="Fl_Gl_Window.html#Fl_Gl_Window"><TT>Fl_Gl_Window</TT></A>.
-Your subclass must implement a <TT>draw()</TT> method which uses
+The easiest way to make an OpenGL display is to subclass
+<A href="Fl_Gl_Window.html#Fl_Gl_Window"><tt>Fl_Gl_Window</tt></A>.
+Your subclass must implement a <tt>draw()</tt> method which uses
 OpenGL calls to draw the display. Your main program should call
-<TT>redraw()</TT> when the display needs to change, and
-(somewhat later) FLTK will call <TT>draw()</TT>.
+<tt>redraw()</tt> when the display needs to change, and
+(somewhat later) FLTK will call <tt>draw()</tt>.
 
-<P>With a bit of care you can also use OpenGL to draw into
+With a bit of care you can also use OpenGL to draw into
 normal FLTK windows. This allows you to use Gouraud shading for
-drawing your widgets.  To do this you use the <A
-href="#gl_start"><TT>gl_start()</TT></A> and <A
-href=#gl_finish><TT>gl_finish()</TT></A> functions around your
-OpenGL code.</P>
-
-<P>You must include FLTK's <TT><FL/gl.h></TT> header
-file. It will include the file <TT><GL/gl.h></TT>, define
+drawing your widgets.  To do this you use the
+<A href="#gl_start"><tt>gl_start()</tt></A>
+and
+<A href=#gl_finish><tt>gl_finish()</tt></A>
+functions around your OpenGL code.
+
+You must include FLTK's <tt><FL/gl.h></tt> header
+file. It will include the file <tt><GL/gl.h></tt>, define
 some extra drawing functions provided by FLTK, and include the
-<TT><windows.h></TT> header file needed by WIN32
-applications.</P>
-
-<H2>Making a Subclass of Fl_Gl_Window</H2>
-
-<P>To make a subclass of Fl_Gl_Window, you must provide:
+<tt><windows.h></tt> header file needed by WIN32
+applications.
 
-<UL>
+\section opengl_subclass Making a Subclass of Fl_Gl_Window
 
-	<LI>A class definition.</LI>
+To make a subclass of Fl_Gl_Window, you must provide:
 
-	<LI>A <TT>draw()</TT> method.</LI>
+\li A class definition.
 
-	<LI>A <TT>handle()</TT> method if you need to receive
-	input from the user.</LI>
+\li A <tt>draw()</tt> method.
 
-</UL>
+\li A <tt>handle()</tt> method if you need to receive input from the user.
 
-<P>If your subclass provides static controls in the window, they
+If your subclass provides static controls in the window, they
 must be redrawn whenever the <tt>FL_DAMAGE_ALL</tt> bit is set
 in the value returned by <tt>damage()</tt>. For double-buffered
 windows you will need to surround the drawing code with the
@@ -72,10 +68,9 @@ glDrawBuffer(GL_BACK);
 </TR>
 </TABLE></CENTER>
 
-<H3>Defining the Subclass</H3>
+\subsection opengl_defining Defining the Subclass
 
-<P>To define the subclass you just subclass the
-<TT>Fl_Gl_Window</TT> class:
+To define the subclass you just subclass the <tt>Fl_Gl_Window</tt> class:
 
 \code
 class MyWindow : public Fl_Gl_Window {
@@ -88,15 +83,14 @@ public:
 };
 \endcode
 
-<P>The <TT>draw()</TT> and <TT>handle()</TT> methods are
+The <tt>draw()</tt> and <tt>handle()</tt> methods are
 described below. Like any widget, you can include additional
 private and public data in your class (such as scene graph
 information, etc.)
 
-<H3>The draw() Method</H3>
+\subsection opengl_draw The draw() Method
 
-<P>The <TT>draw()</TT> method is where you actually do your
-OpenGL drawing:
+The <tt>draw()</tt> method is where you actually do your OpenGL drawing:
 
 \code
 void MyWindow::draw() {
@@ -109,9 +103,9 @@ void MyWindow::draw() {
 }
 \endcode
 
-<H3>The handle() Method</H3>
+\subsection opengl_handle The handle() Method
 
-<P>The <TT>handle()</TT> method handles mouse and keyboard
+The <tt>handle()</tt> method handles mouse and keyboard
 events for the window:
 
 \code
@@ -146,13 +140,13 @@ int MyWindow::handle(int event) {
 }
 \endcode
 
-<P>When <TT>handle()</TT> is called, the OpenGL context is not
+When <tt>handle()</tt> is called, the OpenGL context is not
 set up! If your display changes, you should call
-<TT>redraw()</TT> and let <TT>draw()</TT> do the work. Don't
-call any OpenGL drawing functions from inside <TT>handle()</TT>!
+<tt>redraw()</tt> and let <tt>draw()</tt> do the work. Don't
+call any OpenGL drawing functions from inside <tt>handle()</tt>!
 
-<P>You can call <I>some</I> OpenGL stuff like hit detection and texture
-loading functions by doing: </P>
+You can call <I>some</I> OpenGL stuff like hit detection and texture
+loading functions by doing: 
 
 \code
   case FL_PUSH:
@@ -167,50 +161,44 @@ loading functions by doing: </P>
     detection, loading textures, etc...
 \endcode
 
-<P>Your main program can now create one of your windows by doing
-<TT>new MyWindow(...)</TT>.  You can also use <A
-href="fluid.html#FLUID">FLUID</A> by:
-
-<OL>
-
-	<LI>Putting your class definition in a
-	<tt>MyWindow.H</tt> file.</LI>
-
-	<LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI>
-
-	<LI>In the widget panel fill in the "class"
-	field with <tt>MyWindow</tt>. This will make FLUID
-	produce constructors for your new class.</LI>
-
-	<LI>In the "Extra Code" field put <TT>\#include
-	"MyWindow.H"</TT>, so that the FLUID output
-	file will compile.</LI>
-
-</OL>
-
-<P>You must put <TT>glwindow->show()</TT> in your main code
-after calling <TT>show()</TT> on the window containing the
+Your main program can now create one of your windows by doing
+<tt>new MyWindow(...)</tt>.  You can also use
+<A href="fluid.html#FLUID">FLUID</A>
+by:
+
+-# Putting your class definition in a <tt>MyWindow.H</tt> file.
+   <br>
+-# Creating a <tt>Fl_Box</tt> widget in FLUID.
+   <br>
+-# In the widget panel fill in the "class" field with <tt>MyWindow</tt>.
+   This will make FLUID produce constructors for your new class.
+   <br>
+-# In the "Extra Code" field put <tt>\#include "MyWindow.H"</tt>,
+   so that the FLUID output file will compile.
+
+You must put <tt>glwindow->show()</tt> in your main code
+after calling <tt>show()</tt> on the window containing the
 OpenGL window.
 
-<H2>Using OpenGL in Normal FLTK Windows</H2>
+\section opengl_normal Using OpenGL in Normal FLTK Windows
 
-<P>You can put OpenGL code into an <A
-href="subclassing.html#draw"><TT>Fl_Widget::draw()</TT></A>
-method or into the code for a <A
-href="common.html#boxtypes">boxtype</A> or other places with some
-care.
+You can put OpenGL code into an
+<A href="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>
+method or into the code for a
+<A href="common.html#boxtypes">boxtype</A>
+or other places with some care.
 
-<P>Most importantly, before you show <I>any</I> windows,
+Most importantly, before you show <I>any</I> windows,
 including those that don't have OpenGL drawing, you <B>must</B>
 initialize FLTK so that it knows it is going to use OpenGL. You
 may use any of the symbols described for Fl_Gl_Window::mode()
-to describe how you intend to use OpenGL:</P>
+to describe how you intend to use OpenGL:
 
 \code
 Fl::gl_visual(FL_RGB);
 \endcode
 
-<P>You can then put OpenGL drawing code anywhere you can draw
+You can then put OpenGL drawing code anywhere you can draw
 normally by surrounding it with:
 
 \code
@@ -219,143 +207,145 @@ gl_start();
 gl_finish();
 \endcode
 
-<P><A name="gl_start"><TT>gl_start()</TT></A> and <A
-name="gl_finish"><TT>gl_finish()</TT></A> set up an OpenGL
+<A name="gl_start"><tt>gl_start()</tt></A>
+and
+<A name="gl_finish"><tt>gl_finish()</tt></A>
+set up an OpenGL
 context with an orthographic projection so that 0,0 is the
 lower-left corner of the window and each pixel is one unit. The
-current clipping is reproduced with OpenGL <TT>glScissor()</TT>
+current clipping is reproduced with OpenGL <tt>glScissor()</tt>
 commands. These functions also synchronize the OpenGL graphics stream
 with the drawing done by other X, WIN32, or FLTK functions.
 
-<P>The same context is reused each time. If your code changes
+The same context is reused each time. If your code changes
 the projection transformation or anything else you should use
-<TT>glPushMatrix()</TT> and <TT>glPopMatrix()</TT> functions to
-put the state back before calling <TT>gl_finish()</TT>.</P>
+<tt>glPushMatrix()</tt> and <tt>glPopMatrix()</tt> functions to
+put the state back before calling <tt>gl_finish()</tt>.
 
-<P>You may want to use Fl_Window::current()->h() to
+You may want to use Fl_Window::current()->h() to
 get the drawable height so that you can flip the Y
-coordinates.</P>
+coordinates.
 
-<P>Unfortunately, there are a bunch of limitations you must
-adhere to for maximum portability: </P>
+Unfortunately, there are a bunch of limitations you must
+adhere to for maximum portability: 
 
-<UL>
+\li You must choose a default visual with Fl::gl_visual().
 
-	<LI>You must choose a default visual with Fl::gl_visual().</LI>
+\li You cannot pass <tt>FL_DOUBLE</tt> to Fl::gl_visual().
 
-	<LI>You cannot pass <TT>FL_DOUBLE</TT> to Fl::gl_visual().</LI>
+\li You cannot use Fl_Double_Window or Fl_Overlay_Window.
 
-	<LI>You cannot use Fl_Double_Window or Fl_Overlay_Window.</LI>
+Do <I>not</I> call <tt>gl_start()</tt> or
+<tt>gl_finish()</tt> when drawing into an Fl_Gl_Window !
 
-</UL>
+\section opengl_drawing OpenGL Drawing Functions
 
-<P>Do <I>not</I> call <TT>gl_start()</TT> or
-<TT>gl_finish()</TT> when drawing into an Fl_Gl_Window !
-
-<H2>OpenGL Drawing Functions</H2>
-
-<P>FLTK provides some useful OpenGL drawing functions. They can
+FLTK provides some useful OpenGL drawing functions. They can
 be freely mixed with any OpenGL calls, and are defined by
 including <FL/gl.H> which you should include
-instead of the OpenGL header <TT><GL/gl.h></TT>.
+instead of the OpenGL header <tt><GL/gl.h></tt>.
 
-<H4>void gl_color(Fl_Color)</H4>
+void gl_color(Fl_Color)
 
-<P>Sets the current OpenGL color to a FLTK color. <I>For
-color-index modes it will use <TT>fl_xpixel(c)</TT>, which is
+\par
+Sets the current OpenGL color to a FLTK color. <I>For
+color-index modes it will use <tt>fl_xpixel(c)</tt>, which is
 only right if this window uses the default colormap!</I>
 
-<H4>void gl_rect(int x, int y, int w, int h)
-<BR>void gl_rectf(int x, int y, int w, int h)</H4>
+void gl_rect(int x, int y, int w, int h) <br>
+void gl_rectf(int x, int y, int w, int h)
 
-<P>Outlines or fills a rectangle with the current color. If 
+\par
+Outlines or fills a rectangle with the current color. If 
 Fl_Gl_Window::ortho() has been called, then the rectangle will exactly
 fill the pixel rectangle passed.
 
-<H4>void gl_font(Fl_Font fontid, int size)</H4>
+void gl_font(Fl_Font fontid, int size)
 
-<P>Sets the current OpenGL font to the same font you get by
-calling <A href="drawing.html#fl_font"><TT>fl_font()</TT></A>.
+\par
+Sets the current OpenGL font to the same font you get by calling
+<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
 
-<H4>int gl_height()
-<BR>int gl_descent()
-<BR>float gl_width(const char *)
-<BR>float gl_width(const char *, int n)
-<BR>float gl_width(uchar)</H4>
+int gl_height() <br>
+int gl_descent() <br>
+float gl_width(const char *) <br>
+float gl_width(const char *, int n) <br>
+float gl_width(uchar)
 
-<P>Returns information about the current OpenGL font.
+\par
+Returns information about the current OpenGL font.
 
-<H4>void gl_draw(const char *)
-<BR>void gl_draw(const char *, int n)</H4>
+void gl_draw(const char *) <br>
+void gl_draw(const char *, int n)
 
-<P>Draws a nul-terminated string or an array of <TT>n</TT>
+\par
+Draws a nul-terminated string or an array of <tt>n</tt>
 characters in the current OpenGL font at the current raster
 position.
 
-<H4>void gl_draw(const char *, int x, int y)
-<BR>void gl_draw(const char *, int n, int x, int y)
-<BR>void gl_draw(const char *, float x, float y)
-<BR>void gl_draw(const char *, int n, float x, float y)</H4>
+void gl_draw(const char *, int x, int y) <br>
+void gl_draw(const char *, int n, int x, int y) <br>
+void gl_draw(const char *, float x, float y) <br>
+void gl_draw(const char *, int n, float x, float y)
 
-<P>Draws a nul-terminated string or an array of <TT>n</TT>
+\par
+Draws a nul-terminated string or an array of <tt>n</tt>
 characters in the current OpenGL font at the given position.
 
-<H4>void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)</H4>
+void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)
 
-<P>Draws a string formatted into a box, with newlines and tabs
+\par
+Draws a string formatted into a box, with newlines and tabs
 expanded, other control characters changed to ^X, and aligned
-with the edges or center. Exactly the same output as <A
-href="drawing.html#text"><TT>fl_draw()</TT></A>.
+with the edges or center. Exactly the same output as
+<A href="drawing.html#text"><tt>fl_draw()</tt></A>.
 
-<h2>Speeding up OpenGL</h2>
+\section opengl_speed Speeding up OpenGL
 
-<P>Performance of Fl_Gl_Window may be improved on some types of
+Performance of Fl_Gl_Window may be improved on some types of
 OpenGL implementations, in particular MESA and other software
 emulators, by setting the <tt>GL_SWAP_TYPE</tt> environment
 variable. This variable declares what is in the backbuffer after
 you do a swapbuffers.
 
-<ul>
-
-	<li><tt>setenv GL_SWAP_TYPE COPY</tt>
-
-	<p>This indicates that the back buffer is copied to the
-	front buffer, and still contains it's old data. This is
-	true of many hardware implementations.  Setting this
-	will speed up emulation of overlays, and widgets that
-	can do partial update can take advantage of this as
-	damage() will not be cleared to -1. <p>
-
-	<li><tt>setenv GL_SWAP_TYPE NODAMAGE</tt>
-
-	<p>This indicates that nothing changes the back buffer
-	except drawing into it.  This is true of MESA and Win32
-	software emulation and perhaps some hardware emulation
-	on systems with lots of memory. <p>
-
-	<li>All other values for <tt>GL_SWAP_TYPE</tt>, and not
-	setting the variable, cause FLTK to assume that the
-	back buffer must be completely redrawn after a swap.
-
-</ul>
-
-<p>This is easily tested by running the <TT>gl_overlay</TT> demo
+\li <tt>setenv GL_SWAP_TYPE COPY</tt> <br>
+    <br>
+    This indicates that the back buffer is copied to the
+    front buffer, and still contains it's old data. This is
+    true of many hardware implementations.  Setting this
+    will speed up emulation of overlays, and widgets that
+    can do partial update can take advantage of this as
+    damage() will not be cleared to -1. <p>
+
+\li <tt>setenv GL_SWAP_TYPE NODAMAGE</tt> <br>
+    <br>
+    This indicates that nothing changes the back buffer
+    except drawing into it.  This is true of MESA and Win32
+    software emulation and perhaps some hardware emulation
+    on systems with lots of memory. <p>
+
+\li All other values for <tt>GL_SWAP_TYPE</tt>, and not
+    setting the variable, cause FLTK to assume that the
+    back buffer must be completely redrawn after a swap.
+
+This is easily tested by running the <tt>gl_overlay</tt> demo
 program and seeing if the display is correct when you drag
 another window over it or if you drag the window off the screen
 and back on. You have to exit and run the program again for it
 to see any changes to the environment variable.
 
-<H2>Using OpenGL Optimizer with FLTK</H2>
+\section opengl_optimizer Using OpenGL Optimizer with FLTK
 
-<P><A href="http://www.sgi.com/software/optimizer">OpenGL
-Optimizer</A> is a scene graph toolkit for OpenGL available from
+<A href="http://www.sgi.com/software/optimizer">OpenGL Optimizer</A>
+is a scene graph toolkit for OpenGL available from
 Silicon Graphics for IRIX and Microsoft Windows. It allows you
 to view large scenes without writing a lot of OpenGL code.
 
-<H4>OptimizerWindow Class Definition</H4>
+\par OptimizerWindow Class Definition
 
-<P>To use OpenGL Optimizer with FLTK you'll need to create a
-subclass of <TT>Fl_Gl_Widget</TT> that includes several state
+\par
+To use OpenGL Optimizer with FLTK you'll need to create a
+subclass of <tt>Fl_Gl_Widget</tt> that includes several state
 variables:
 
 \code
@@ -389,15 +379,17 @@ public:
 };
 \endcode
 
-<H4>The camera() Method</H4>
+\par The camera() Method
 
-<P>The <TT>camera()</TT> method sets the camera (projection and
+\par
+The <tt>camera()</tt> method sets the camera (projection and
 viewpoint) to use when drawing the scene. The scene is redrawn after
 this call.
 
-<H4>The draw() Method</H4>
+\par The draw() Method
 
-<P>The <TT>draw()</TT> method performs the needed initialization and does
+\par
+The <tt>draw()</tt> method performs the needed initialization and does
 the actual drawing:
 
 \code
@@ -451,10 +443,11 @@ void OptimizerWindow::draw() {
 }
 \endcode
 
-<H4>The scene() Method</H4>
+\par The scene() Method
 
-<P>The <TT>scene()</TT> method sets the scene to be drawn.  The scene is
-a collection of 3D objects in a <TT>csGroup</TT>.  The scene is redrawn
+\par
+The <tt>scene()</tt> method sets the scene to be drawn.  The scene is
+a collection of 3D objects in a <tt>csGroup</tt>.  The scene is redrawn
 after this call.
 
 <hr>