From d7094249f03ed3d0c609cdac3940e4d679bfad35 Mon Sep 17 00:00:00 2001 From: Manolo Gouy Date: Mon, 7 Sep 2015 15:48:55 +0000 Subject: [PATCH] Documentation: better descriptions of Fl_Gl_Window::mode() and Fl_Gl_Window::can_do(). git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@10857 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Gl_Window.H | 90 +++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 39 deletions(-) diff --git a/FL/Fl_Gl_Window.H b/FL/Fl_Gl_Window.H index 439cc48ed..95333be4e 100644 --- a/FL/Fl_Gl_Window.H +++ b/FL/Fl_Gl_Window.H @@ -3,7 +3,7 @@ // // OpenGL header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2015 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -124,49 +124,61 @@ public: */ void context_valid(char v) {if (v) valid_f_ |= 2; else valid_f_ &= 0xfd;} - /** Returns non-zero if the hardware supports the given or current OpenGL mode. */ + /** Returns non-zero if the hardware supports the given OpenGL mode. */ static int can_do(int m) {return can_do(m,0);} - /** Returns non-zero if the hardware supports the given or current OpenGL mode. */ + /** Returns non-zero if the hardware supports the given OpenGL mode. + \see Fl_Gl_Window::mode(const int *a) */ static int can_do(const int *m) {return can_do(0, m);} - /** Returns non-zero if the hardware supports the given or current OpenGL mode. */ + /** Returns non-zero if the hardware supports the current OpenGL mode. */ int can_do() {return can_do(mode_,alist);} - /** - Set or change the OpenGL capabilites of the window. The value can be - any of the following OR'd together: - - - \c FL_RGB - RGB color (not indexed) - - \c FL_RGB8 - RGB color with at least 8 bits of each color - - \c FL_INDEX - Indexed mode - - \c FL_SINGLE - not double buffered - - \c FL_DOUBLE - double buffered - - \c FL_ACCUM - accumulation buffer - - \c FL_ALPHA - alpha channel in color - - \c FL_DEPTH - depth buffer - - \c FL_STENCIL - stencil buffer - - \c FL_MULTISAMPLE - multisample antialiasing - - FL_RGB and FL_SINGLE have a value of zero, so they - are "on" unless you give FL_INDEX or FL_DOUBLE. - - If the desired combination cannot be done, FLTK will try turning off - FL_MULTISAMPLE. If this also fails the show() will call - Fl::error() and not show the window. - - You can change the mode while the window is displayed. This is most - useful for turning double-buffering on and off. Under X this will - cause the old X window to be destroyed and a new one to be created. If - this is a top-level window this will unfortunately also cause the - window to blink, raise to the top, and be de-iconized, and the xid() - will change, possibly breaking other code. It is best to make the GL - window a child of another window if you wish to do this! - - mode() must not be called within draw() since it - changes the current context. - */ + /** Returns the current OpenGL capabilites of the window. + Don't use this if capabilities were set through Fl_Gl_Window::mode(const int *a). + */ Fl_Mode mode() const {return (Fl_Mode)mode_;} - /** See Fl_Mode mode() const */ + /** + Set or change the OpenGL capabilites of the window. The value can be + any of the following OR'd together: + + - \c FL_RGB - RGB color (not indexed) + - \c FL_RGB8 - RGB color with at least 8 bits of each color + - \c FL_INDEX - Indexed mode + - \c FL_SINGLE - not double buffered + - \c FL_DOUBLE - double buffered + - \c FL_ACCUM - accumulation buffer + - \c FL_ALPHA - alpha channel in color + - \c FL_DEPTH - depth buffer + - \c FL_STENCIL - stencil buffer + - \c FL_MULTISAMPLE - multisample antialiasing + + FL_RGB and FL_SINGLE have a value of zero, so they + are "on" unless you give FL_INDEX or FL_DOUBLE. + + If the desired combination cannot be done, FLTK will try turning off + FL_MULTISAMPLE. If this also fails the show() will call + Fl::error() and not show the window. + + You can change the mode while the window is displayed. This is most + useful for turning double-buffering on and off. Under X this will + cause the old X window to be destroyed and a new one to be created. If + this is a top-level window this will unfortunately also cause the + window to blink, raise to the top, and be de-iconized, and the xid() + will change, possibly breaking other code. It is best to make the GL + window a child of another window if you wish to do this! + + mode() must not be called within draw() since it + changes the current context. + */ int mode(int a) {return mode(a,0);} - /** See Fl_Mode mode() const */ + /** Set the OpenGL capabilites of the window using platform-specific data. + \param a zero-ending array of platform-specific attributes and attribute values +

Unix/Linux platform: attributes are GLX attributes adequate for the 3rd argument of + the glXChooseVisual() function (e.g., GLX_DOUBLEBUFFER). +

MSWindows platform: this member function is of no use. +

Mac OS X platform: attributes belong to the CGLPixelFormatAttribute enumeration + (e.g., kCGLPFADoubleBuffer) and may be followed by adequate attribute values. + The pair kCGLPFAOpenGLProfile, kCGLOGLPVersion_3_2_Core allows to create an OpenGL V3.2 profile + under Mac OS X 10.7 and above. + */ int mode(const int *a) {return mode(0, a);} /** Returns a pointer to the GLContext that this window is using. \see void context(void* v, int destroy_flag) */