diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox index bed6b5d5c..cc88f089f 100644 --- a/documentation/src/opengl.dox +++ b/documentation/src/opengl.dox @@ -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 -Fl_Gl_Window. -Your subclass must implement a draw() 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 -redraw() when the display needs to change, and -(somewhat later) FLTK will call draw(). +\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. + gl_start() and gl_finish() functions around your OpenGL code. -You must include FLTK's header -file. It will include the file , define +You must include FLTK's \p header +file. It will include the file \p , define some extra drawing functions provided by FLTK, and include the - header file needed by WIN32 +\p 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 draw() method. - -\li A handle() 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 FL_DAMAGE_ALL bit is set -in the value returned by damage(). 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); Note: -

If you are using the Mesa graphics library, the call - to glDrawBuffer() 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 Fl_Gl_Window 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 draw() and handle() 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 draw() 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 handle() 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 handle() 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 -redraw() and let draw() do the work. Don't -call any OpenGL drawing functions from inside handle()! +\p redraw() and let \p draw() do the work. Don't +call any OpenGL drawing functions from inside \p handle()! -You can call some 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 -new MyWindow(...). You can also use +new MyWindow(...). + +You can also use your new window class in FLUID by: --# Putting your class definition in a MyWindow.H file. -
--# Creating a Fl_Box widget in FLUID. -
--# In the widget panel fill in the "class" field with MyWindow. +-# 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. -
-# In the "Extra Code" field put \#include "MyWindow.H", so that the FLUID output file will compile. You must put glwindow->show() in your main code -after calling show() 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. + Fl_Widget::draw() method or into the code for a boxtype or other places with some care. -Most importantly, before you show any windows, +Most importantly, before you show \e any windows, including those that don't have OpenGL drawing, you must 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 -gl_start() -and -gl_finish() -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 glScissor() +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 -glPushMatrix() and glPopMatrix() functions to -put the state back before calling gl_finish(). +\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 Fl_Window::current()->h() 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 FL_DOUBLE 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 not call gl_start() or -gl_finish() 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 which you should include -instead of the OpenGL header . +including \p which you should include +instead of the OpenGL header \p . void gl_color(Fl_Color) \par Sets the current OpenGL color to a FLTK color. For -color-index modes it will use fl_xpixel(c), which is +color-index modes it will use \p fl_xpixel(c), which is only right if this window uses the default colormap! void gl_rect(int x, int y, int w, int h)
@@ -279,7 +284,7 @@ void gl_draw(const char *)
void gl_draw(const char *, int n) \par -Draws a nul-terminated string or an array of n +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)
void gl_draw(const char *, int n, float x, float y) \par -Draws a nul-terminated string or an array of n +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 GL_SWAP_TYPE 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 damage() will not be cleared to -1. \li setenv GL_SWAP_TYPE NODAMAGE

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.

+ on systems with lots of memory. -\li All other values for GL_SWAP_TYPE, 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 gl_overlay 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 Fl_Gl_Widget that includes several state +To use +OpenGL Optimizer +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 camera() 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 draw() 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 scene() method sets the scene to be drawn. The scene is -a collection of 3D objects in a csGroup. 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