Author: engelsman
Date: 2009-03-21 13:57:29 -0700 (Sat, 21 Mar 2009)
New Revision: 6706
Log:
converted html tags to doxygen commands in documentation/src/opengl.dox
This was just the first round. A lot more work will be needed here
because none of the gl_* functions are doxygenated, and there are
a lot of html links to other pages to be tidied up!
Modified:
branches/branch-1.3/documentation/src/opengl.dox
Modified: branches/branch-1.3/documentation/src/opengl.dox
===================================================================
--- branches/branch-1.3/documentation/src/opengl.dox 2009-03-21 17:08:23 UTC
(rev 6705)
+++ branches/branch-1.3/documentation/src/opengl.dox 2009-03-21 20:57:29 UTC
(rev 6706)
@@ -7,24 +7,28 @@
\section opengl_using Using OpenGL in FLTK
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
+Fl_Gl_Window.
+Your subclass must implement a \p draw() 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>.
+\p redraw() when the display needs to change, and
+(somewhat later) FLTK will call \p draw().
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
+\ref opengl_gl_start "gl_start()" and
+\ref opengl_gl_finish "gl_finish()"
+functions around your OpenGL code.
+
<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
+You must include FLTK's \p <FL/gl.h> header
+file. It will include the file \p <GL/gl.h>, define
some extra drawing functions provided by FLTK, and include the
-<tt><windows.h></tt> header file needed by WIN32
+\p <windows.h> header file needed by WIN32
applications.
\section opengl_subclass Making a Subclass of Fl_Gl_Window
@@ -32,14 +36,12 @@
To make a subclass of Fl_Gl_Window, you must provide:
\li A class definition.
+\li A \p draw() method.
+\li A \p handle() method if you need to receive input from the user.
-\li A <tt>draw()</tt> method.
-
-\li A <tt>handle()</tt> method if you need to receive input from the user.
-
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
+must be redrawn whenever the \p FL_DAMAGE_ALL bit is set
+in the value returned by \p damage(). For double-buffered
windows you will need to surround the drawing code with the
following code to make sure that both buffers are redrawn:
@@ -57,8 +59,8 @@
<TR>
<TD><B>Note:</B>
- <P>If you are using the Mesa graphics library, the call
- to <tt>glDrawBuffer()</tt> is not required and will slow
+ If you are using the Mesa graphics library, the call
+ to \p glDrawBuffer() is not required and will slow
down drawing considerably. The preprocessor instructions
shown above will optimize your code based upon the
graphics library used.
@@ -70,7 +72,7 @@
\subsection opengl_defining Defining the Subclass
-To define the subclass you just subclass the <tt>Fl_Gl_Window</tt> class:
+To define the subclass you just subclass the Fl_Gl_Window class:
\code
class MyWindow : public Fl_Gl_Window {
@@ -83,14 +85,14 @@
};
\endcode
-The <tt>draw()</tt> and <tt>handle()</tt> methods are
+The \p draw() and \p handle() methods are
described below. Like any widget, you can include additional
private and public data in your class (such as scene graph
information, etc.)
\subsection opengl_draw The draw() Method
-The <tt>draw()</tt> method is where you actually do your OpenGL drawing:
+The \p draw() method is where you actually do your OpenGL drawing:
\code
void MyWindow::draw() {
@@ -105,7 +107,7 @@
\subsection opengl_handle The handle() Method
-The <tt>handle()</tt> method handles mouse and keyboard
+The \p handle() method handles mouse and keyboard
events for the window:
\code
@@ -140,12 +142,12 @@
}
\endcode
-When <tt>handle()</tt> is called, the OpenGL context is not
+When \p handle() 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>!
+\p redraw() and let \p draw() do the work. Don't
+call any OpenGL drawing functions from inside \p handle()!
-You can call <I>some</I> OpenGL stuff like hit detection and texture
+You can call \e some OpenGL stuff like hit detection and texture
loading functions by doing:
\code
@@ -162,36 +164,40 @@
\endcode
Your main program can now create one of your windows by doing
-<tt>new MyWindow(...)</tt>. You can also use
+<tt>new MyWindow(...)</tt>.
+
+You can also use your new window class in
<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>.
+-# Putting your class definition in a \p MyWindow.H file.
+-# Creating a Fl_Box widget in FLUID.
+-# In the widget panel fill in the "class" field with \p MyWindow.
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
+after calling \p show() on the window containing the
OpenGL window.
\section opengl_normal Using OpenGL in Normal FLTK Windows
-You can put OpenGL code into an
+You can put OpenGL code into the \p draw() method, as described in
+\ref subclassing_drawing
+in the previous chapter, or into the code for a
+\ref common_boxtypes "boxtype"
+or other places with some care.
+
<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.
-Most importantly, before you show <I>any</I> windows,
+Most importantly, before you show \e any 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()
+may use any of the symbols described for \p Fl_Gl_Window::mode()
to describe how you intend to use OpenGL:
\code
@@ -207,22 +213,21 @@
gl_finish();
\endcode
-<A name="gl_start"><tt>gl_start()</tt></A>
-and
-<A name="gl_finish"><tt>gl_finish()</tt></A>
-set up an OpenGL
+\anchor opengl_gl_start
+\anchor opengl_gl_finish
+\p gl_start() and \p gl_finish() 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 \p glScissor()
commands. These functions also synchronize the OpenGL graphics stream
with the drawing done by other X, WIN32, or FLTK functions.
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 glPushMatrix() and \p glPopMatrix() functions to
+put the state back before calling \p gl_finish().
-You may want to use Fl_Window::current()->h() to
+You may want to use <tt>Fl_Window::current()->h()</tt> to
get the drawable height so that you can flip the Y
coordinates.
@@ -231,25 +236,25 @@
\li You must choose a default visual with Fl::gl_visual().
-\li You cannot pass <tt>FL_DOUBLE</tt> to Fl::gl_visual().
+\li You cannot pass \p FL_DOUBLE to Fl::gl_visual().
\li You cannot use Fl_Double_Window or Fl_Overlay_Window.
-Do <I>not</I> call <tt>gl_start()</tt> or
-<tt>gl_finish()</tt> when drawing into an Fl_Gl_Window !
+Do \e not call \p gl_start() or
+\p gl_finish() when drawing into an Fl_Gl_Window !
\section opengl_drawing OpenGL Drawing Functions
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>.
+including \p <FL/gl.h> which you should include
+instead of the OpenGL header \p <GL/gl.h>.
void gl_color(Fl_Color)
\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
+color-index modes it will use \p fl_xpixel(c), which is
only right if this window uses the default colormap!</I>
void gl_rect(int x, int y, int w, int h) <br>
@@ -279,7 +284,7 @@
void gl_draw(const char *, int n)
\par
-Draws a nul-terminated string or an array of <tt>n</tt>
+Draws a nul-terminated string or an array of \p n<
characters in the current OpenGL font at the current raster
position.
@@ -289,7 +294,7 @@
void gl_draw(const char *, int n, float x, float y)
\par
-Draws a nul-terminated string or an array of <tt>n</tt>
+Draws a nul-terminated string or an array of \p n
characters in the current OpenGL font at the given position.
void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)
@@ -304,7 +309,7 @@
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
+emulators, by setting the \p GL_SWAP_TYPE environment
variable. This variable declares what is in the backbuffer after
you do a swapbuffers.
@@ -315,20 +320,20 @@
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>
+ \p damage() will not be cleared to -1.
\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>
+ on systems with lots of memory.
-\li All other values for <tt>GL_SWAP_TYPE</tt>, and not
+\li All other values for \p GL_SWAP_TYPE, 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
+This is easily tested by running the \p gl_overlay 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
@@ -344,8 +349,10 @@
\par OptimizerWindow Class Definition
\par
-To use OpenGL Optimizer with FLTK you'll need to create a
-subclass of <tt>Fl_Gl_Widget</tt> that includes several state
+To use
+<A href="http://www.sgi.com/software/optimizer";>OpenGL Optimizer</A>
+with FLTK you'll need to create a
+subclass of Fl_Gl_Widget that includes several state
variables:
\code
@@ -382,14 +389,14 @@
\par The camera() Method
\par
-The <tt>camera()</tt> method sets the camera (projection and
+The \p camera() method sets the camera (projection and
viewpoint) to use when drawing the scene. The scene is redrawn after
this call.
\par The draw() Method
\par
-The <tt>draw()</tt> method performs the needed initialization and does
+The \p draw() method performs the needed initialization and does
the actual drawing:
\code
@@ -446,8 +453,8 @@
\par The scene() Method
\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
+The \p >scene() method sets the scene to be drawn. The scene is
+a collection of 3D objects in a \p csGroup. The scene is redrawn
after this call.
\htmlonly
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
