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