diff options
| author | Michael R Sweet <michael.r.sweet@gmail.com> | 2002-01-06 13:40:32 +0000 |
|---|---|---|
| committer | Michael R Sweet <michael.r.sweet@gmail.com> | 2002-01-06 13:40:32 +0000 |
| commit | 2d6a98560e1f3f027180be34cfc625eabfb32f05 (patch) | |
| tree | a48208d7420cfcdf1f8fa614b9fa66c8002163a0 /documentation/opengl.html | |
| parent | de9f6763537e7152279a4f5a19a70437e7a70940 (diff) | |
Doco and dist file updates.
Add fltk-config man page.
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1911 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation/opengl.html')
| -rw-r--r-- | documentation/opengl.html | 457 |
1 files changed, 274 insertions, 183 deletions
diff --git a/documentation/opengl.html b/documentation/opengl.html index b390e46b9..ee2a2e08f 100644 --- a/documentation/opengl.html +++ b/documentation/opengl.html @@ -1,35 +1,53 @@ -<HTML><BODY> -<H1 ALIGN=RIGHT><A NAME=opengl>9 - Using OpenGL</A></H1> - This chapter discusses using FLTK for your OpenGL applications. +<HTML> +<BODY> +<H1 ALIGN=RIGHT><A NAME=opengl>8 - Using OpenGL</A></H1> + +<P>This chapter discusses using FLTK for your OpenGL applications. + <H2>Using OpenGL in FLTK</H2> -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 OpenGL calls to draw the display. Your main program -should call <TT>redraw()</TT> when the display needs to change, and + +<P>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 +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>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 <A href=#gl_start><TT> -gl_start()</TT></A> and <A href=#gl_finish><TT>gl_finish()</TT></A> -functions around your OpenGL code. </P> -<P>You must include FLTK's <TT><FL/gl.h></TT> header file. It will -include the file <TT><GL/gl.h></TT>, define some extra drawing -functions provided by FLTK, and include the <TT><windows.h></TT> header -file needed by WIN32 applications. </P> + +<P>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 <A +href="#gl_start"><TT>gl_start()</TT></A> and <A +href=#gl_finish><TT>gl_finish()</TT></A> functions around your +OpenGL code.</P> + +<P>You must include FLTK's <TT><FL/gl.h></TT> header +file. It will include the file <TT><GL/gl.h></TT>, define +some extra drawing functions provided by FLTK, and include the +<TT><windows.h></TT> header file needed by WIN32 +applications.</P> + <H2>Making a Subclass of Fl_Gl_Window</H2> -To make a subclass of Fl_Gl_Window, you must provide: + +<P>To make a subclass of Fl_Gl_Window, you must provide: + <UL> -<LI>A class definition. </LI> -<LI>A <TT>draw()</TT> method. </LI> -<LI>A <TT>handle()</TT> method (if you need to receive input from the -user). </LI> + + <LI>A class definition.</LI> + + <LI>A <TT>draw()</TT> method.</LI> + + <LI>A <TT>handle()</TT> method if you need to receive + input from the user.</LI> + </UL> -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 windows you will -need to surround the drawing code with the following code to make sure -that both buffers are redrawn: -<ul><pre> + +<P>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 +windows you will need to surround the drawing code with the +following code to make sure that both buffers are redrawn: + +<UL><PRE> #ifndef MESA glDrawBuffer(GL_FRONT_AND_BACK); #endif // !MESA @@ -37,15 +55,29 @@ glDrawBuffer(GL_FRONT_AND_BACK); #ifndef MESA glDrawBuffer(GL_BACK); #endif // !MESA -</pre></ul> -<B>Note:</B> If you are using the Mesa graphics library, the call to -<tt>glDrawBuffer()</tt> is not required and will slow down drawing -considerably. The preprocessor instructions shown above will optimize -your code based upon the graphics library used. +</PRE></UL> + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<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 + down drawing considerably. The preprocessor instructions + shown above will optimize your code based upon the + graphics library used. + + </TD> + +</TR> +</TABLE></CENTER> + <H3>Defining the Subclass</H3> -To define the subclass you just subclass the <TT>Fl_Gl_Window</TT> class: -<UL> -<PRE> + +<P>To define the subclass you just subclass the +<TT>Fl_Gl_Window</TT> class: + +<UL><PRE> class MyWindow : public Fl_Gl_Window { void draw(); int handle(int); @@ -54,16 +86,19 @@ public: MyWindow(int X, int Y, int W, int H, const char *L) : Fl_Gl_Window(X, Y, W, H, L) {} }; -</PRE> -</UL> - The <TT>draw()</TT> and <TT>handle()</TT> methods are described below. - Like any widget, you can include additional private and public data in -your class (such as scene graph information, etc.) +</PRE></UL> + +<P>The <TT>draw()</TT> and <TT>handle()</TT> methods are +described below. Like any widget, you can include additional +private and public data in your class (such as scene graph +information, etc.) + <H3>The draw() Method</H3> - The <TT>draw()</TT> method is where you actually do your OpenGL -drawing: -<UL> -<PRE> + +<P>The <TT>draw()</TT> method is where you actually do your +OpenGL drawing: + +<UL><PRE> void MyWindow::draw() { if (!valid()) { ... set up projection, viewport, etc ... @@ -72,13 +107,14 @@ void MyWindow::draw() { } ... draw ... } -</PRE> -</UL> +</PRE></UL> + <H3>The handle() Method</H3> - The <TT>handle()</TT> method handles mouse and keyboard events for the -window: -<UL> -<PRE> + +<P>The <TT>handle()</TT> method handles mouse and keyboard +events for the window: + +<UL><PRE> int MyWindow::handle(int event) { switch(event) { case FL_PUSH: @@ -108,16 +144,17 @@ int MyWindow::handle(int event) { return Fl_Gl_Window::handle(event); } } -</PRE> -</UL> -When <TT>handle()</TT> 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>! +</PRE></UL> + +<P>When <TT>handle()</TT> 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>You can call <I>some</I> OpenGL stuff like hit detection and texture loading functions by doing: </P> -<UL> -<PRE> + +<UL><PRE> case FL_PUSH: make_current(); // make OpenGL context current if (!valid()) { @@ -126,155 +163,205 @@ loading functions by doing: </P> } ... ok to call NON-DRAWING OpenGL code here, such as hit detection, loading textures, etc... -</PRE> -</UL> -Your main program can now create one of your windows by doing <TT>new -MyWindow(...)</TT>. You can also use <A href=FLUID.html#FLUID>FLUID</A> -by: +</PRE></UL> + +<P>Your main program can now create one of your windows by doing +<TT>new MyWindow(...)</TT>. You can also use <A +href="FLUID.html#FLUID">FLUID</A> by: + <OL> -<LI>Putting your class definition in a <tt>MyWindow.H</tt> file. </LI> -<LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI> -<LI>In the widget panel fill in the "class" field with <tt>MyWindow</tt>. -This will make FLUID produce constructors for your new class. </LI> -<LI>In the "Extra Code" field put <TT>#include "MyWindow.H"</TT>, so that -the FLUID output file will compile. </LI> + + <LI>Putting your class definition in a + <tt>MyWindow.H</tt> file.</LI> + + <LI>Creating a <tt>Fl_Box</tt> widget in FLUID.</LI> + + <LI>In the widget panel fill in the "class" + field with <tt>MyWindow</tt>. This will make FLUID + produce constructors for your new class.</LI> + + <LI>In the "Extra Code" field put <TT>#include + "MyWindow.H"</TT>, so that the FLUID output + file will compile.</LI> + </OL> -You must put <TT>glwindow->show()</TT> in your main code after calling <TT> -show()</TT> on the window containing the OpenGL window. + +<P>You must put <TT>glwindow->show()</TT> in your main code +after calling <TT>show()</TT> on the window containing the +OpenGL window. + <H2>Using OpenGL in Normal FLTK Windows</H2> -You can put OpenGL code into an <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. -<P>Most importantly, before you show <I>any</I> 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 <A href=Fl_Gl_Window.html#Fl_Gl_Window.mode><TT> -Fl_Gl_Window::mode()</TT></A> to describe how you intend to use OpenGL: </P> -<UL> -<PRE> + +<P>You can put OpenGL code into an <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. + +<P>Most importantly, before you show <I>any</I> 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 <A +href="Fl_Gl_Window.html#Fl_Gl_Window.mode"><TT>Fl_Gl_Window::mode()</TT></A> +to describe how you intend to use OpenGL:</P> + +<UL><PRE> Fl::gl_visual(FL_RGB); -</PRE> -</UL> -You can then put OpenGL drawing code anywhere you can draw normally by -surrounding it with: -<UL> -<PRE> +</PRE></UL> + +<P>You can then put OpenGL drawing code anywhere you can draw +normally by surrounding it with: + +<UL><PRE> gl_start(); ... put your OpenGL code here ... gl_finish(); -</PRE> -</UL> -<A name=gl_start><TT>gl_start()</TT></A> and <A name=gl_finish><TT> -gl_finish()</TT></A> 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> commands. These also synchronize the OpenGL graphics -stream with the drawing done by other X, WIN32, or FLTK functions. -<P>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> -<P>You may want to use <TT>Fl_Window::current()->h()</TT> to get the -drawable height so that you can flip the Y coordinates. </P> -<P>Unfortunately, there are a bunch of limitations you must adhere to -for maximum portability: </P> +</PRE></UL> + +<P><A name="gl_start"><TT>gl_start()</TT></A> and <A +name="gl_finish"><TT>gl_finish()</TT></A> 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> +commands. These functions also synchronize the OpenGL graphics stream +with the drawing done by other X, WIN32, or FLTK functions. + +<P>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> + +<P>You may want to use <TT>Fl_Window::current()->h()</TT> to +get the drawable height so that you can flip the Y +coordinates.</P> + +<P>Unfortunately, there are a bunch of limitations you must +adhere to for maximum portability: </P> + <UL> -<LI>You must choose a default visual with <A href=functions.html#gl_visual> -<TT>Fl::gl_visual()</TT></A>. </LI> -<LI>You cannot pass <TT>FL_DOUBLE</TT> to <TT>Fl::gl_visual()</TT>.</LI> -<LI>You cannot use <TT>Fl_Double_Window</TT> or <TT>Fl_Overlay_Window</TT>.</LI> + + <LI>You must choose a default visual with <A + href="functions.html#gl_visual"><TT>Fl::gl_visual()</TT></A>.</LI> + + <LI>You cannot pass <TT>FL_DOUBLE</TT> to + <TT>Fl::gl_visual()</TT>.</LI> + + <LI>You cannot use <TT>Fl_Double_Window</TT> or + <TT>Fl_Overlay_Window</TT>.</LI> + </UL> -Do <I>not</I> call <TT>gl_start()</TT> or <TT>gl_finish()</TT> when -drawing into an <TT>Fl_Gl_Window</TT>! + +<P>Do <I>not</I> call <TT>gl_start()</TT> or +<TT>gl_finish()</TT> when drawing into an <TT>Fl_Gl_Window</TT>! + <H2>OpenGL Drawing Functions</H2> -FLTK provides some useful OpenGL drawing functions. They can be -freely mixed with any OpenGL calls, and are defined by including <TT> -<FL/gl.H></TT> (which you should include instead of the OpenGL header <TT> -<GL/gl.h></TT>). + +<P>FLTK provides some useful OpenGL drawing functions. They can +be freely mixed with any OpenGL calls, and are defined by +including <TT><FL/gl.H></TT> which you should include +instead of the OpenGL header <TT><GL/gl.h></TT>. + <H4>void gl_color(Fl_Color)</H4> -Set the current color to a FLTK color. <I>For color-index modes -it will use <TT>fl_xpixel(c)</TT>, which is only right if this window -uses the default colormap!</I> + +<P>Sets the current OpenGL color to a FLTK color. <I>For +color-index modes it will use <TT>fl_xpixel(c)</TT>, which is +only right if this window uses the default colormap!</I> + <H4>void gl_rect(int x, int y, int w, int h) -<BR> void gl_rectf(int x, int y, int w, int h)</H4> -Outline or fill a rectangle with the current color. If -<A HREF="Fl_Gl_Window.html#Fl_Gl_Window.ortho"><TT>Fl_Gl_Window::ortho()</TT></A> +<BR>void gl_rectf(int x, int y, int w, int h)</H4> + +<P>Outlines or fills a rectangle with the current color. If <A +HREF="Fl_Gl_Window.html#Fl_Gl_Window.ortho"><TT>Fl_Gl_Window::ortho()</TT></A> has been called, then the rectangle will exactly fill the pixel rectangle passed. + <H4>void gl_font(Fl_Font fontid, int size)</H4> -Set the current OpenGL font to the same font you get by calling <A href=drawing.html#fl_font> -<TT>fl_font()</TT></A>. + +<P>Sets the current OpenGL font to the same font you get by +calling <A href="drawing.html#fl_font"><TT>fl_font()</TT></A>. + <H4>int gl_height() -<BR> int gl_descent() -<BR> float gl_width(const char *) -<BR> float gl_width(const char *, int n) -<BR> float gl_width(uchar)</H4> - Return information about the current OpenGL font. +<BR>int gl_descent() +<BR>float gl_width(const char *) +<BR>float gl_width(const char *, int n) +<BR>float gl_width(uchar)</H4> + +<P>Returns information about the current OpenGL font. + <H4>void gl_draw(const char *) -<BR> void gl_draw(const char *, int n)</H4> -Draw a nul-terminated string or an array of <TT>n</TT> characters in -the current OpenGL font at the current raster position. +<BR>void gl_draw(const char *, int n)</H4> + +<P>Draws a nul-terminated string or an array of <TT>n</TT> +characters in the current OpenGL font at the current raster +position. + <H4>void gl_draw(const char *, int x, int y) -<BR> void gl_draw(const char *, int n, int x, int y) -<BR> void gl_draw(const char *, float x, float y) -<BR> void gl_draw(const char *, int n, float x, float y)</H4> - Draw a nul-terminated string or an array of <TT>n</TT> characters in -the current OpenGL font at the given position. +<BR>void gl_draw(const char *, int n, int x, int y) +<BR>void gl_draw(const char *, float x, float y) +<BR>void gl_draw(const char *, int n, float x, float y)</H4> + +<P>Draws a nul-terminated string or an array of <TT>n</TT> +characters in the current OpenGL font at the given position. + <H4>void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)</H4> - Draw 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 <A href="drawing.html#text"><TT>fl_draw()</TT></A> -. +<P>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 <A +href="drawing.html#text"><TT>fl_draw()</TT></A>. <h2>Speeding up OpenGL</h2> -Performance of Fl_Gl_Window may be improved on some types of OpenGL -implementations (in particular MESA or other software emulators) by -setting the <tt>GL_SWAP_TYPE</tt> environment variable. This variable -declares what is in the back buffer after you do a swapbuffers. +<P>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 +variable. This variable declares what is in the backbuffer after +you do a swapbuffers. <ul> -<li><tt>setenv GL_SWAP_TYPE COPY</tt> + <li><tt>setenv GL_SWAP_TYPE COPY</tt> -<p>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. -<p> + <p>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. <p> -<li><tt>setenv GL_SWAP_TYPE NODAMAGE</tt> + <li><tt>setenv GL_SWAP_TYPE NODAMAGE</tt> -<p>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> + <p>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> -<li>All other values for <tt>GL_SWAP_TYPE</tt>, and not setting the variable, -cause fltk to assumme that the back buffer must be completely -redrawn after a swap. + <li>All other values for <tt>GL_SWAP_TYPE</tt>, and not + setting the variable, cause FLTK to assumme that the + back buffer must be completely redrawn after a swap. </ul> -<p>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. +<p>This is easily tested by running the <TT>gl_overlay</TT> 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. <H2>Using OpenGL Optimizer with FLTK</H2> -<A href=http://www.sgi.com/software/optimizer>OpenGL Optimizer</A> is a -scene graph toolkit for OpenGL available from Silicon Graphics for IRIX -and Microsoft Windows. Versions are in the works for Solaris and -HP-UX. It allows you to view large scenes without writing a lot of -OpenGL code. + +<P><A href="http://www.sgi.com/software/optimizer">OpenGL +Optimizer</A> 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. + <H4>OptimizerWindow Class Definition</H4> - To use OpenGL Optimizer with FLTK you'll need to create a subclass of <TT> -Fl_Gl_Widget</TT> that includes several state variables: -<UL> -<PRE> + +<P>To use OpenGL Optimizer with FLTK you'll need to create a +subclass of <TT>Fl_Gl_Widget</TT> that includes several state +variables: + +<UL><PRE> class OptimizerWindow : public Fl_Gl_Window { csContext *context_; // Initialized to 0 and set by draw()... csDrawAction *draw_action_; // Draw action... @@ -303,18 +390,20 @@ public: } } }; -</PRE> -</UL> +</PRE></UL> <H4>The camera() Method</H4> - The <TT>camera()</TT> method sets the camera (projection and + +<P>The <TT>camera()</TT> method sets the camera (projection and viewpoint) to use when drawing the scene. The scene is redrawn after this call. + <H4>The draw() Method</H4> - The <TT>draw()</TT> method performs the needed initialization and does + +<P>The <TT>draw()</TT> method performs the needed initialization and does the actual drawing: -<UL> -<PRE> + +<UL><PRE> void OptimizerWindow::draw() { if (!context_) { // This is the first time we've been asked to draw; create the @@ -353,7 +442,6 @@ void OptimizerWindow::draw() { } // Clear the window... - context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR, 0.0f, // Red 0.0f, // Green @@ -361,13 +449,16 @@ void OptimizerWindow::draw() { 1.0f); // Alpha // Then draw the scene (if any)... - if (scene_) draw_action_->apply(scene_); } -</PRE> -</UL> +</PRE></UL> + <H4>The scene() Method</H4> - The <TT>scene()</TT> method sets the scene to be drawn. The scene is + +<P>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 -after this call. </BODY></HTML> +after this call. + +</BODY> +</HTML> |