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