interface/wx/glcanvas.h

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