interface/wx/glcanvas.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        glcanvas.h
   3 // Purpose:     interface of wxGLContext and wxGLCanvas
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxGLContext
  11
  12     An instance of a wxGLContext represents the state of an OpenGL state
  13     machine and the connection between OpenGL and the system.
  14
  15     The OpenGL state includes everything that can be set with the OpenGL API:
  16     colors, rendering variables, display lists, texture objects, etc. Although
  17     it is possible to have multiple rendering contexts share display lists in
  18     order to save resources, this method is hardly used today any more, because
  19     display lists are only a tiny fraction of the overall state.
  20
  21     Therefore, one rendering context is usually used with or bound to multiple
  22     output windows in turn, so that the application has access to the complete
  23     and identical state while rendering into each window.
  24
  25     Binding (making current) a rendering context with another instance of a
  26     wxGLCanvas however works only if the other wxGLCanvas was created with the
  27     same attributes as the wxGLCanvas from which the wxGLContext was
  28     initialized. (This applies to sharing display lists among contexts
  29     analogously.)
  30
  31     Note that some wxGLContext features are extremely platform-specific - its
  32     best to check your native platform's glcanvas header (on windows
  33     include/wx/msw/glcanvas.h) to see what features your native platform
  34     provides.
  35
  36     @library{wxgl}
  37     @category{gl}
  38
  39     @see wxGLCanvas
  40 */
  41 class wxGLContext : public wxObject
  42 {
  43 public:
  44     /**
  45         Constructor.
  46
  47         @param win
  48             The canvas that is used to initialize this context. This parameter
  49             is needed only temporarily, and the caller may do anything with it
  50             (e.g. destroy the window) after the constructor returned. @n
  51             It will be possible to bind (make current) this context to any
  52             other wxGLCanvas that has been created with equivalent attributes
  53             as win.
  54         @param other
  55             Context to share display lists with or @NULL (the default) for no
  56             sharing.
  57     */
  58     wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL);
  59
  60     /**
  61         Makes the OpenGL state that is represented by this rendering context
  62         current with the wxGLCanvas @e win.
  63
  64         @note @a win can be a different wxGLCanvas window than the one that was
  65               passed to the constructor of this rendering context. If @e RC is
  66               an object of type wxGLContext, the statements
  67               @e "RC.SetCurrent(win);" and @e "win.SetCurrent(RC);" are
  68               equivalent, see wxGLCanvas::SetCurrent().
  69     */
  70     virtual bool SetCurrent(const wxGLCanvas& win) const;
  71 };
  72
  73 /**
  74     @anchor wxGL_FLAGS
  75
  76     Constants for use with wxGLCanvas.
  77
  78     @note Not all implementations support options such as stereo, auxiliary
  79           buffers, alpha channel, and accumulator buffer, use
  80           wxGLCanvas::IsDisplaySupported() to check for individual attributes
  81           support.
  82  */
  83 enum
  84 {
  85     /// Use true color palette (on if no attributes at all specified).
  86     WX_GL_RGBA = 1,
  87
  88     /// Specifies the number of bits for buffer if not WX_GL_RGBA.
  89     WX_GL_BUFFER_SIZE,
  90
  91     /// Must be followed by 0 for main buffer, >0 for overlay, <0 for underlay.
  92     WX_GL_LEVEL,
  93
  94     /// Use double buffering if present (on if no attributes specified).
  95     WX_GL_DOUBLEBUFFER,
  96
  97     /// Use stereoscopic display.
  98     WX_GL_STEREO,
  99
 100     /// Specifies number of auxiliary buffers.
 101     WX_GL_AUX_BUFFERS,
 102
 103     /// Use red buffer with most bits (> MIN_RED bits)
 104     WX_GL_MIN_RED,
 105
 106     /// Use green buffer with most bits (> MIN_GREEN bits)
 107     WX_GL_MIN_GREEN,
 108
 109     /// Use blue buffer with most bits (> MIN_BLUE bits)
 110     WX_GL_MIN_BLUE,
 111
 112     /// Use alpha buffer with most bits (> MIN_ALPHA bits)
 113     WX_GL_MIN_ALPHA,
 114
 115     /// Specifies number of bits for Z-buffer (typically 0, 16 or 32).
 116     WX_GL_DEPTH_SIZE,
 117
 118     /// Specifies number of bits for stencil buffer.
 119     WX_GL_STENCIL_SIZE,
 120
 121     /// Specifies minimal number of red accumulator bits.
 122     WX_GL_MIN_ACCUM_RED,
 123
 124     /// Specifies minimal number of green accumulator bits.
 125     WX_GL_MIN_ACCUM_GREEN,
 126
 127     /// Specifies minimal number of blue accumulator bits.
 128     WX_GL_MIN_ACCUM_BLUE,
 129
 130     /// Specifies minimal number of alpha accumulator bits.
 131     WX_GL_MIN_ACCUM_ALPHA,
 132
 133     /// 1 for multisampling support (antialiasing)
 134     WX_GL_SAMPLE_BUFFERS,
 135
 136     /// 4 for 2x2 antialising supersampling on most graphics cards
 137     WX_GL_SAMPLES
 138
 139 };
 140
 141 /**
 142     @class wxGLCanvas
 143
 144     wxGLCanvas is a class for displaying OpenGL graphics. It is always used in
 145     conjunction with wxGLContext as the context can only be made current (i.e.
 146     active for the OpenGL commands) when it is associated to a wxGLCanvas.
 147
 148     More precisely, you first need to create a wxGLCanvas window and then
 149     create an instance of a wxGLContext that is initialized with this
 150     wxGLCanvas and then later use either SetCurrent() with the instance of the
 151     wxGLContext or wxGLContext::SetCurrent() with the instance of the
 152     wxGLCanvas (which might be not the same as was used for the creation of the
 153     context) to bind the OpenGL state that is represented by the rendering
 154     context to the canvas, and then finally call SwapBuffers() to swap the
 155     buffers of the OpenGL canvas and thus show your current output.
 156
 157     Notice that versions of wxWidgets previous to 2.9 used to implicitly create a
 158     wxGLContext inside wxGLCanvas itself. This is still supported in the
 159     current version but is deprecated now and will be removed in the future,
 160     please update your code to create the rendering contexts explicitly.
 161
 162     To set up the attributes for the canvas (number of bits for the depth
 163     buffer, number of bits for the stencil buffer and so on) you should set up
 164     the correct values of the @e attribList parameter. The values that should
 165     be set up and their meanings will be described below.
 166
 167     @note
 168         On those platforms which use a configure script (e.g. Linux and Mac OS)
 169         OpenGL support is automatically enabled if the relative headers and
 170         libraries are found.
 171         To switch it on under the other platforms (e.g. Windows), you need to edit
 172         the @c setup.h file and set @c wxUSE_GLCANVAS to @c 1 and then also pass
 173         @c USE_OPENGL=1 to the make utility. You may also need to add @c opengl32.lib
 174         and @c glu32.lib to the list of the libraries your program is linked with.
 175
 176     @library{wxgl}
 177     @category{gl}
 178
 179     @see wxGLContext
 180 */
 181 class wxGLCanvas : public wxWindow
 182 {
 183 public:
 184     /**
 185         Creates a window with the given parameters. Notice that you need to
 186         create and use a wxGLContext to output to this window.
 187
 188         If @a attribList is not specified, double buffered RGBA mode is used.
 189
 190         @param parent
 191             Pointer to a parent window.
 192         @param id
 193             Window identifier. If -1, will automatically create an identifier.
 194         @param pos
 195             Window position. wxDefaultPosition is (-1, -1) which indicates that
 196             wxWidgets should generate a default position for the window.
 197         @param size
 198             Window size. wxDefaultSize is (-1, -1) which indicates that
 199             wxWidgets should generate a default size for the window. If no
 200             suitable size can be found, the window will be sized to 20x20
 201             pixels so that the window is visible but obviously not correctly
 202             sized.
 203         @param style
 204             Window style.
 205         @param name
 206             Window name.
 207         @param attribList
 208             Array of integers. With this parameter you can set the device
 209             context attributes associated to this window. This array is
 210             zero-terminated: it should be set up using @ref wxGL_FLAGS
 211             constants. If a constant should be followed by a value, put it in
 212             the next array position. For example, WX_GL_DEPTH_SIZE should be
 213             followed by the value that indicates the number of bits for the
 214             depth buffer, e.g:
 215             @code
 216             attribList[n++] = WX_GL_DEPTH_SIZE;
 217             attribList[n++] = 32;
 218             attribList[n] = 0; // terminate the list
 219             @endcode
 220             If the attribute list is not specified at all, i.e. if this
 221             parameter is @NULL, the default attributes including WX_GL_RGBA and
 222             WX_GL_DOUBLEBUFFER are used. But notice that if you do specify some
 223             attributes you also need to explicitly include these two default
 224             attributes in the list if you need them.
 225         @param palette
 226             Palette for indexed colour (i.e. non WX_GL_RGBA) mode. Ignored
 227             under most platforms.
 228     */
 229     wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY,
 230                const int* attribList = NULL,
 231                const wxPoint& pos = wxDefaultPosition,
 232                const wxSize& size = wxDefaultSize,
 233                long style = 0,
 234                const wxString& name = "GLCanvas",
 235                const wxPalette& palette = wxNullPalette);
 236
 237     /**
 238         Determines if a canvas having the specified attributes is available.
 239
 240         @param attribList
 241             See @a attribList for wxGLCanvas().
 242
 243         @return @true if attributes are supported.
 244     */
 245     static bool IsDisplaySupported(const int* attribList = NULL);
 246
 247     /**
 248         Sets the current colour for this window (using @c glcolor3f()), using
 249         the wxWidgets colour database to find a named colour.
 250     */
 251     bool SetColour(const wxString& colour);
 252
 253     /**
 254         Makes the OpenGL state that is represented by the OpenGL rendering
 255         context @a context current, i.e. it will be used by all subsequent
 256         OpenGL calls.
 257
 258         This is equivalent to wxGLContext::SetCurrent() called with this window
 259         as parameter.
 260
 261         @note This function may only be called when the window is shown on
 262               screen, in particular it can't usually be called from the
 263               constructor as the window isn't yet shown at this moment.
 264
 265         @return @false if an error occurred.
 266     */
 267     bool SetCurrent(const wxGLContext& context) const;
 268
 269     /**
 270         Swaps the double-buffer of this window, making the back-buffer the
 271         front-buffer and vice versa, so that the output of the previous OpenGL
 272         commands is displayed on the window.
 273
 274         @return @false if an error occurred.
 275     */
 276     virtual bool SwapBuffers();
 277 };