interface/wx/glcanvas.h

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