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! git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6706 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman
parent
ced863d334
commit
e13df9275c
@ -7,24 +7,28 @@ This chapter discusses using FLTK for your OpenGL applications.
|
||||
\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 @@ applications.
|
||||
To make a subclass of Fl_Gl_Window, you must provide:
|
||||
|
||||
\li A class definition.
|
||||
|
||||
\li A <tt>draw()</tt> method.
|
||||
|
||||
\li A <tt>handle()</tt> method if you need to receive input from the user.
|
||||
\li A \p draw() method.
|
||||
\li A \p handle() 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 @@ glDrawBuffer(GL_BACK);
|
||||
<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 @@ glDrawBuffer(GL_BACK);
|
||||
|
||||
\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 @@ public:
|
||||
};
|
||||
\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 @@ void MyWindow::draw() {
|
||||
|
||||
\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 @@ int MyWindow::handle(int event) {
|
||||
}
|
||||
\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 @@ loading functions by doing:
|
||||
\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_start();
|
||||
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 @@ adhere to for maximum portability:
|
||||
|
||||
\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 *) <br>
|
||||
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 *, float x, float y) <br>
|
||||
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 @@ with the edges or center. Exactly the same output as
|
||||
|
||||
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 @@ you do a swapbuffers.
|
||||
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 @@ to view large scenes without writing a lot of OpenGL code.
|
||||
\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 @@ public:
|
||||
\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 @@ void OptimizerWindow::draw() {
|
||||
\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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user