Author: engelsman Date: 2009-04-09 13:44:31 -0700 (Thu, 09 Apr 2009) New Revision: 6749 Log: converted html tags to doxygen commands in opengl.dox
also corrected function signatures in opengl.dox added doxygen comments to FL/gl.h, src/gl_start.cxx, src/gl_draw.cxx Modified: branches/branch-1.3/FL/gl.h branches/branch-1.3/documentation/src/opengl.dox branches/branch-1.3/src/gl_draw.cxx branches/branch-1.3/src/gl_start.cxx Modified: branches/branch-1.3/FL/gl.h =================================================================== --- branches/branch-1.3/FL/gl.h 2009-04-09 19:00:16 UTC (rev 6748) +++ branches/branch-1.3/FL/gl.h 2009-04-09 20:44:31 UTC (rev 6749) @@ -32,6 +32,22 @@ // http://www.fltk.org/str.php // +/** \file gl.h + * This file defines wrapper functions for OpenGL in FLTK + * + * To use OpenGL from within an FLTK application you MUST use gl_visual() + * to select the default visual before doing show() on any windows. Mesa + * will crash if yoy try to use a visual not returned by glxChooseVidual. + * + * This does not work with Fl_Double_Window's! It will try to draw + * into the front buffer. Depending on the system this will either + * crash or do nothing (when pixmaps are being used as back buffer + * and GL is being done by hardware), work correctly (when GL is done + * with software, such as Mesa), or draw into the front buffer and + * be erased when the buffers are swapped (when double buffer hardware + * is being used) + */ + #ifndef FL_gl_H # define FL_gl_H @@ -56,10 +72,15 @@ FL_EXPORT void gl_start(); FL_EXPORT void gl_finish(); -FL_EXPORT void gl_color(Fl_Color); -inline void gl_color(int c) {gl_color((Fl_Color)c);} // back compatability +FL_EXPORT void gl_color(Fl_Color i); +/** back compatability */ +inline void gl_color(int c) {gl_color((Fl_Color)c);} FL_EXPORT void gl_rect(int x,int y,int w,int h); +/** + Fills the given rectangle with the current color. + \see gl_rect(int x, int y, int w, int h) + */ inline void gl_rectf(int x,int y,int w,int h) {glRecti(x,y,x+w,y+h);} FL_EXPORT void gl_font(int fontid, int size); Modified: branches/branch-1.3/documentation/src/opengl.dox =================================================================== --- branches/branch-1.3/documentation/src/opengl.dox 2009-04-09 19:00:16 UTC (rev 6748) +++ branches/branch-1.3/documentation/src/opengl.dox 2009-04-09 20:44:31 UTC (rev 6749) @@ -20,11 +20,6 @@ \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 \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 @@ -167,6 +162,7 @@ <tt>new MyWindow(...)</tt>. You can also use your new window class in +\ref fluid "FLUID" <A href="fluid.html#FLUID">FLUID</A> by: @@ -189,11 +185,6 @@ \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 \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 @@ -204,30 +195,29 @@ 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 - \anchor opengl_gl_start \anchor opengl_gl_finish -\p gl_start() and \p gl_finish() set up an OpenGL +You can then put OpenGL drawing code anywhere you can draw +normally by surrounding it with +gl_start() and gl_finish() to set up, and later release, 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 \p glScissor() commands. These functions also synchronize the OpenGL graphics stream with the drawing done by other X, WIN32, or FLTK functions. +\code +gl_start(); +... put your OpenGL code here ... +gl_finish(); +\endcode + The same context is reused each time. If your code changes the projection transformation or anything else you should use \p glPushMatrix() and \p glPopMatrix() functions to put the state back before calling \p gl_finish(). -You may want to use <tt>Fl_Window::current()->h()</tt> 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. @@ -273,31 +263,31 @@ 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) +float gl_width(const char *s) <br> +float gl_width(const char *s, int n) <br> +float gl_width(uchar c) \par Returns information about the current OpenGL font. -void gl_draw(const char *) <br> -void gl_draw(const char *, int n) +void gl_draw(const char *s) <br> +void gl_draw(const char *s, int n) \par -Draws a nul-terminated string or an array of \p n< +Draws a nul-terminated string or an array of \p n characters in the current OpenGL font at the current raster position. -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) +void gl_draw(const char *s, int x, int y) <br> +void gl_draw(const char *s, int n, int x, int y) <br> +void gl_draw(const char *s, float x, float y) <br> +void gl_draw(const char *s, int n, float x, float y) \par 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) +void gl_draw(const char *s, int x, int y, int w, int h, Fl_Align) \par Draws a string formatted into a box, with newlines and tabs @@ -316,7 +306,7 @@ \li <tt>setenv GL_SWAP_TYPE COPY</tt> <br> <br> This indicates that the back buffer is copied to the - front buffer, and still contains it's old data. This is + front buffer, and still contains its 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 @@ -333,7 +323,7 @@ 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 \p gl_overlay demo +This is easily tested by running the \ref examples_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 @@ -453,7 +443,7 @@ \par The scene() Method \par -The \p >scene() method sets the scene to be drawn. The scene is +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. Modified: branches/branch-1.3/src/gl_draw.cxx =================================================================== --- branches/branch-1.3/src/gl_draw.cxx 2009-04-09 19:00:16 UTC (rev 6748) +++ branches/branch-1.3/src/gl_draw.cxx 2009-04-09 20:44:31 UTC (rev 6749) @@ -47,10 +47,15 @@ extern XFontStruct* fl_xxfont(); #endif // USE_XFT +/** Returns the current font's height */ int gl_height() {return fl_height();} +/** Returns the current font's descent */ int gl_descent() {return fl_descent();} +/** Returns the width of the string in the current fnt */ double gl_width(const char* s) {return fl_width(s);} +/** Returns the width of n characters of the string in the current font */ double gl_width(const char* s, int n) {return fl_width(s,n);} +/** Returns the width of the character in the current font */ double gl_width(uchar c) {return fl_width(c);} static Fl_Font_Descriptor *gl_fontsize; @@ -65,6 +70,9 @@ # undef USE_OksiD_style_GL_font_selection // turn this off for XFT also #endif +/** + Sets the current OpenGL font to the same font as calling fl_font() + */ void gl_font(int fontid, int size) { fl_font(fontid, size); if (!fl_fontsize->listbase) { @@ -192,6 +200,10 @@ #endif } +/** + Draws an array of n characters of the string in the current font + at the current position. + */ void gl_draw(const char* str, int n) { #ifdef __APPLE__ // Should be converting the text here, as for other platforms??? @@ -223,24 +235,39 @@ #endif } +/** + Draws n charachters of the string in the current font at the given position + */ void gl_draw(const char* str, int n, int x, int y) { glRasterPos2i(x, y); gl_draw(str, n); } +/** + Draws n charachters of the string in the current font at the given position + */ void gl_draw(const char* str, int n, float x, float y) { glRasterPos2f(x, y); gl_draw(str, n); } +/** + Draws a nul-terminated string in the current font at the current position + */ void gl_draw(const char* str) { gl_draw(str, strlen(str)); } +/** + Draws a nul-terminated string in the current font at the given position + */ void gl_draw(const char* str, int x, int y) { gl_draw(str, strlen(str), x, y); } +/** + Draws a nul-terminated string in the current font at the given position + */ void gl_draw(const char* str, float x, float y) { gl_draw(str, strlen(str), x, y); } @@ -250,6 +277,11 @@ gl_draw(str, n); } +/** + 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(). + */ void gl_draw( const char* str, // the (multi-line) string int x, int y, int w, int h, // bounding box @@ -259,6 +291,11 @@ void gl_measure(const char* str, int& x, int& y) {fl_measure(str,x,y);} +/** + Outlines the given rectangle with the current color. + If Fl_Gl_Window::ortho() has been called, then the rectangle will + exactly fill the given pixel rectangle. + */ void gl_rect(int x, int y, int w, int h) { if (w < 0) {w = -w; x = x-w;} if (h < 0) {h = -h; y = y-h;} @@ -276,6 +313,12 @@ extern int fl_overlay_depth; #endif +/** + Sets the curent OpenGL color to an FLTK color. + + For color-index modes it will use fl_xpixel(c), which is only + right if the window uses the default colormap! + */ void gl_color(Fl_Color i) { #if HAVE_GL_OVERLAY #if defined(WIN32) Modified: branches/branch-1.3/src/gl_start.cxx =================================================================== --- branches/branch-1.3/src/gl_start.cxx 2009-04-09 19:00:16 UTC (rev 6748) +++ branches/branch-1.3/src/gl_start.cxx 2009-04-09 20:44:31 UTC (rev 6749) @@ -62,6 +62,7 @@ Fl_Region XRectangleRegion(int x, int y, int w, int h); // in fl_rect.cxx +/** Creates an OpenGL context */ void gl_start() { if (!context) { #if defined(USE_X11) @@ -102,6 +103,7 @@ } } +/** Releases an OpenGL context */ void gl_finish() { glFlush(); #if !defined(WIN32) && !defined(__APPLE__) _______________________________________________ fltk-commit mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-commit
