From 8416a4012ecb985d150fad566659cf59ee1dc3aa Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 13 Sep 2008 15:55:32 +0000 Subject: Doxygen documentation - WP12 and WP13 - first step. Converted the descriptive chapters of the html docs to doxygen format and modified index.dox accordingly. This checkin includes only trivial reformatting, no major rewriting. Added a chapter "Migrating Code from FLTK 1.1 to 1.3". All links on the main page are working now. Todo: - Check doxygen error messages, rewrite pages (html tags, contents). - Fill the new "Migrating..." chapter. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6224 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/opengl.dox | 463 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 463 insertions(+) create mode 100644 documentation/opengl.dox (limited to 'documentation/opengl.dox') diff --git a/documentation/opengl.dox b/documentation/opengl.dox new file mode 100644 index 000000000..87a5c50c2 --- /dev/null +++ b/documentation/opengl.dox @@ -0,0 +1,463 @@ +/** + + \page opengl 8 - Using OpenGL + +

This chapter discusses using FLTK for your OpenGL applications. + +

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 +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(). + +

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 gl_start() and gl_finish() functions around your +OpenGL code.

+ +

You must include FLTK's <FL/gl.h> header +file. It will include the file <GL/gl.h>, define +some extra drawing functions provided by FLTK, and include the +<windows.h> header file needed by WIN32 +applications.

+ +

Making a Subclass of Fl_Gl_Window

+ +

To make a subclass of Fl_Gl_Window, you must provide: + +

+ +

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 +windows you will need to surround the drawing code with the +following code to make sure that both buffers are redrawn: + +

+ +
+ + + + +
Note: + +

If you are using the Mesa graphics library, the call + to 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. + +

+ +

Defining the Subclass

+ +

To define the subclass you just subclass the +Fl_Gl_Window class: + +

+ +

The draw() and 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.) + +

The draw() Method

+ +

The draw() method is where you actually do your +OpenGL drawing: + +

+ +

The handle() Method

+ +

The handle() method handles mouse and keyboard +events for the window: + +

+ +

When 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()! + +

You can call some OpenGL stuff like hit detection and texture +loading functions by doing:

+ + + +

Your main program can now create one of your windows by doing +new MyWindow(...). You can also use FLUID by: + +

    + +
  1. Putting your class definition in a + MyWindow.H file.
    2. + +
  2. Creating a Fl_Box widget in FLUID.
    3. + +
  3. In the widget panel fill in the "class" + field with MyWindow. This will make FLUID + produce constructors for your new class.
    4. + +
  4. In the "Extra Code" field put #include + "MyWindow.H", so that the FLUID output + file will compile.
    5. + +
+ +

You must put glwindow->show() in your main code +after calling show() on the window containing the +OpenGL window. + +

Using OpenGL in Normal FLTK Windows

+ +

You can put OpenGL code into an Fl_Widget::draw() +method or into the code for a boxtype or other places with some +care. + +

Most importantly, before you show 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() +to describe how you intend to use OpenGL:

+ + + +

You can then put OpenGL drawing code anywhere you can draw +normally by surrounding it with: + +

+ +

gl_start() and 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() +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().

+ +

You may want to use Fl_Window::current()->h() to +get the drawable height so that you can flip the Y +coordinates.

+ +

Unfortunately, there are a bunch of limitations you must +adhere to for maximum portability:

+ + + +

Do not call gl_start() or +gl_finish() when drawing into an Fl_Gl_Window! + +

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 <GL/gl.h>. + +

void gl_color(Fl_Color)

+ +

Sets the current OpenGL color to a FLTK color. For +color-index modes it will use 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) +
void gl_rectf(int x, int y, int w, int h)

+ +

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. + +

void gl_font(Fl_Font fontid, int size)

+ +

Sets the current OpenGL font to the same font you get by +calling fl_font(). + +

int gl_height() +
int gl_descent() +
float gl_width(const char *) +
float gl_width(const char *, int n) +
float gl_width(uchar)

+ +

Returns information about the current OpenGL font. + +

void gl_draw(const char *) +
void gl_draw(const char *, int n)

+ +

Draws a nul-terminated string or an array of n +characters in the current OpenGL font at the current raster +position. + +

void gl_draw(const char *, int x, int y) +
void gl_draw(const char *, int n, int x, int y) +
void gl_draw(const char *, float x, float y) +
void gl_draw(const char *, int n, float x, float y)

+ +

Draws a nul-terminated string or an array of 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)

+ +

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 fl_draw(). + +

Speeding up OpenGL

+ +

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 +variable. This variable declares what is in the backbuffer after +you do a swapbuffers. + +

+ +

This is easily tested by running the 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 +to see any changes to the environment variable. + +

Using OpenGL Optimizer with FLTK

+ +

OpenGL +Optimizer 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. + +

OptimizerWindow Class Definition

+ +

To use OpenGL Optimizer with FLTK you'll need to create a +subclass of Fl_Gl_Widget that includes several state +variables: + +

+ +

The camera() Method

+ +

The camera() method sets the camera (projection and +viewpoint) to use when drawing the scene. The scene is redrawn after +this call. + +

The draw() Method

+ +

The draw() method performs the needed initialization and does +the actual drawing: + +

+ +

The scene() Method

+ +

The scene() method sets the scene to be drawn. The scene is +a collection of 3D objects in a csGroup. The scene is redrawn +after this call. + +*/ -- cgit v1.2.3