From 09cfc1a1ea00f7edf394e647f1f32e5b0913f564 Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Fri, 17 Oct 2008 11:22:35 +0000 Subject: Removing current broken history documentation/src dir. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6451 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src/opengl.dox | 459 ------------------------------------------- 1 file changed, 459 deletions(-) delete mode 100644 documentation/src/opengl.dox (limited to 'documentation/src/opengl.dox') diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox deleted file mode 100644 index bed6b5d5c..000000000 --- a/documentation/src/opengl.dox +++ /dev/null @@ -1,459 +0,0 @@ -/** - - \page opengl 8 - Using OpenGL - -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 -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 header -file. It will include the file , define -some extra drawing functions provided by FLTK, and include the - header file needed by WIN32 -applications. - -\section opengl_subclass Making a Subclass of Fl_Gl_Window - -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. - -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: - -\code -#ifndef MESA -glDrawBuffer(GL_FRONT_AND_BACK); -#endif // !MESA -... draw stuff here ... -#ifndef MESA -glDrawBuffer(GL_BACK); -#endif // !MESA -\endcode - -
- - - - -
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. - -

- -\subsection opengl_defining Defining the Subclass - -To define the subclass you just subclass the Fl_Gl_Window class: - -\code -class MyWindow : public Fl_Gl_Window { - void draw(); - int handle(int); - -public: - MyWindow(int X, int Y, int W, int H, const char *L) - : Fl_Gl_Window(X, Y, W, H, L) {} -}; -\endcode - -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.) - -\subsection opengl_draw The draw() Method - -The draw() method is where you actually do your OpenGL drawing: - -\code -void MyWindow::draw() { - if (!valid()) { - ... set up projection, viewport, etc ... - ... window size is in w() and h(). - ... valid() is turned on by FLTK after draw() returns - } - ... draw ... -} -\endcode - -\subsection opengl_handle The handle() Method - -The handle() method handles mouse and keyboard -events for the window: - -\code -int MyWindow::handle(int event) { - switch(event) { - case FL_PUSH: - ... mouse down event ... - ... position in Fl::event_x() and Fl::event_y() - return 1; - case FL_DRAG: - ... mouse moved while down event ... - return 1; - case FL_RELEASE: - ... mouse up event ... - return 1; - case FL_FOCUS : - case FL_UNFOCUS : - ... Return 1 if you want keyboard events, 0 otherwise - return 1; - case FL_KEYBOARD: - ... keypress, key is in Fl::event_key(), ascii in Fl::event_text() - ... Return 1 if you understand/use the keyboard event, 0 otherwise... - return 1; - case FL_SHORTCUT: - ... shortcut, key is in Fl::event_key(), ascii in Fl::event_text() - ... Return 1 if you understand/use the shortcut event, 0 otherwise... - return 1; - default: - // pass other events to the base class... - return Fl_Gl_Window::handle(event); - } -} -\endcode - -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: - -\code - case FL_PUSH: - make_current(); // make OpenGL context current - if (!valid()) { - - ... set up projection exactly the same as draw ... - - valid(1); // stop it from doing this next time - } - ... ok to call NON-DRAWING OpenGL code here, such as hit - detection, loading textures, etc... -\endcode - -Your main program can now create one of your windows by doing -new MyWindow(...). You can also use -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. - 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 -OpenGL window. - -\section opengl_normal 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: - -\code -Fl::gl_visual(FL_RGB); -\endcode - -You can then put OpenGL drawing code anywhere you can draw -normally by surrounding it with: - -\code -gl_start(); -... put your OpenGL code here ... -gl_finish(); -\endcode - -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: - -\li You must choose a default visual with Fl::gl_visual(). - -\li You cannot pass 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 ! - -\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 . - -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 -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) - -\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. - -void gl_font(Fl_Font fontid, int size) - -\par -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) - -\par -Returns information about the current OpenGL font. - -void gl_draw(const char *)
-void gl_draw(const char *, int n) - -\par -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) - -\par -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) - -\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 -fl_draw(). - -\section opengl_speed 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. - -\li setenv GL_SWAP_TYPE COPY
-
- 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.

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

- -\li All other values for 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 -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. - -\section opengl_optimizer 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. - -\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 -variables: - -\code -class OptimizerWindow : public Fl_Gl_Window { - csContext *context_; // Initialized to 0 and set by draw()... - csDrawAction *draw_action_; // Draw action... - csGroup *scene_; // Scene to draw... - csCamara *camera_; // Viewport for scene... - - void draw(); - -public: - OptimizerWindow(int X, int Y, int W, int H, const char *L) - : Fl_Gl_Window(X, Y, W, H, L) { - context_ = (csContext *)0; - draw_action_ = (csDrawAction *)0; - scene_ = (csGroup *)0; - camera_ = (csCamera *)0; - } - - void scene(csGroup *g) { scene_ = g; redraw(); } - - void camera(csCamera *c) { - camera_ = c; - if (context_) { - draw_action_->setCamera(camera_); - camera_->draw(draw_action_); - redraw(); - } - } -}; -\endcode - -\par The camera() Method - -\par -The 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 actual drawing: - -\code -void OptimizerWindow::draw() { - if (!context_) { - // This is the first time we've been asked to draw; create the - // Optimizer context for the scene... - -#ifdef WIN32 - context_ = new csContext((HDC)fl_getHDC()); - context_->ref(); - context_->makeCurrent((HDC)fl_getHDC()); -#else - context_ = new csContext(fl_display, fl_visual); - context_->ref(); - context_->makeCurrent(fl_display, fl_window); -#endif // WIN32 - - ... perform other context setup as desired ... - - // Then create the draw action to handle drawing things... - - draw_action_ = new csDrawAction; - if (camera_) { - draw_action_->setCamera(camera_); - camera_->draw(draw_action_); - } - } else { -#ifdef WIN32 - context_->makeCurrent((HDC)fl_getHDC()); -#else - context_->makeCurrent(fl_display, fl_window); -#endif // WIN32 - } - - if (!valid()) { - // Update the viewport for this context... - context_->setViewport(0, 0, w(), h()); - } - - // Clear the window... - context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR, - 0.0f, // Red - 0.0f, // Green - 0.0f, // Blue - 1.0f); // Alpha - - // Then draw the scene (if any)... - if (scene_) - draw_action_->apply(scene_); -} -\endcode - -\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 -after this call. - -\htmlonly -

-[Index]    -[Previous]  7 - Adding and Extending Widgets  -[Next]  9 - Programming with FLUID  -\endhtmlonly -*/ -- cgit v1.2.3