interface/glcanvas.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        glcanvas.h
   3 // Purpose:     documentation for wxGLContext class
   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     @seealso
  42     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 is needed
  52         only temporarily,
  53         and the caller may do anything with it (e.g. destroy the window) after the
  54         constructor returned.
  55
  56         It will be possible to bind (make current) this context to any other wxGLCanvas
  57         that has been created
  58         with equivalent attributes as win.
  59
  60         @param other
  61         Context to share display lists with or @NULL (the default) for no sharing.
  62     */
  63     wxGLContext(wxGLCanvas* win, const wxGLContext* other=@NULL);
  64
  65     /**
  66         Makes the OpenGL state that is represented by this rendering context current
  67         with the wxGLCanvas @e win.
  68         Note that @e win can be a different wxGLCanvas window than the one that was
  69         passed to the constructor of this rendering context.
  70         If  @e RC  is an object of type wxGLContext, the statements @e
  71         RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent,
  72         see wxGLCanvas::SetCurrent.
  73     */
  74     void SetCurrent(const wxGLCanvas& win);
  75 };
  76
  77
  78 /**
  79     @class wxGLCanvas
  80     @wxheader{glcanvas.h}
  81
  82     wxGLCanvas is a class for displaying OpenGL graphics. It is always used in
  83     conjunction with wxGLContext as the context can only be
  84     be made current (i.e. active for the OpenGL commands) when it is associated to
  85     a wxGLCanvas.
  86
  87     More precisely, you first need to create a wxGLCanvas window and then create an
  88     instance of a wxGLContext that is initialized with this
  89     wxGLCanvas and then later use either wxGLCanvas::SetCurrent
  90     with the instance of the wxGLContext or
  91     wxGLContext::SetCurrent with the instance of
  92     the wxGLCanvas (which might be not the same as was used
  93     for the creation of the context) to bind the OpenGL state that is represented
  94     by the rendering context to the canvas, and then finally call
  95     wxGLCanvas::SwapBuffers to swap the buffers of
  96     the OpenGL canvas and thus show your current output.
  97
  98     Notice that previous versions of wxWidgets used to implicitly create a
  99     wxGLContext inside wxGLCanvas itself. This is still supported in the current
 100     version but is deprecated now and will be removed in the future, please update
 101     your code to create the rendering contexts explicitly.
 102
 103     To set up the attributes for the canvas (number of bits for the depth buffer,
 104     number of bits for the stencil buffer and so on) you should set up the correct
 105     values of
 106     the @e attribList parameter. The values that should be set up and their
 107     meanings will be described below.
 108
 109     Notice that OpenGL is not enabled by default. To switch it on, you need to edit
 110     setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also need
 111     to have to add @c opengl32.lib and @c glu32.lib to the list of libraries
 112     your program is linked with). On Unix, pass @c --with-opengl to configure.
 113
 114     @library{wxgl}
 115     @category{gl}
 116
 117     @seealso
 118     wxGLContext
 119 */
 120 class wxGLCanvas : public wxWindow
 121 {
 122 public:
 123     /**
 124         Creates a window with the given parameters. Notice that you need to create and
 125         use a wxGLContext to output to this window.
 126
 127         If
 128
 129         @param attribList is not specified, double buffered RGBA mode is used.
 130
 131         parent
 132         Pointer to a parent window.
 133
 134         @param id
 135         Window identifier. If -1, will automatically create an identifier.
 136
 137         @param pos
 138         Window position. wxDefaultPosition is (-1, -1) which indicates that wxWidgets
 139         should generate a default position for the window.
 140
 141         @param size
 142         Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should
 143         generate a default size for the window. If no suitable size can be found, the
 144         window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized.
 145
 146         @param style
 147         Window style.
 148
 149         @param name
 150         Window name.
 151
 152         @param attribList
 153         Array of integers. With this parameter you can set the device context
 154         attributes associated to this window.
 155         This array is zero-terminated: it should be set up with constants described in
 156         the table above.
 157         If a constant should be followed by a value, put it in the next array position.
 158         For example, the WX_GL_DEPTH_SIZE should be followed by the value that
 159         indicates the number of
 160         bits for the depth buffer, so:
 161
 162         @param palette
 163         Palette for indexed colour (i.e. non WX_GL_RGBA) mode.
 164         Ignored under most platforms.
 165     */
 166     wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY,
 167                const int* attribList = @NULL,
 168                const wxPoint& pos = wxDefaultPosition,
 169                const wxSize& size = wxDefaultSize,
 170                long style=0,
 171                const wxString& name="GLCanvas",
 172                const wxPalette& palette = wxNullPalette);
 173
 174     /**
 175         Determines if a canvas having the specified attributes is available.
 176
 177         Returns @true if attributes are supported.
 178
 179         @param attribList
 180         See attribList for wxGLCanvas().
 181     */
 182     static bool IsDisplaySupported(const int * attribList = @NULL);
 183
 184     /**
 185         Sets the current colour for this window (using @c glcolor3f()), using the
 186         wxWidgets colour database to find a named colour.
 187     */
 188     void SetColour(const wxString& colour);
 189
 190     /**
 191         Makes the OpenGL state that is represented by the OpenGL rendering context
 192         @e context current, i.e. it will be used by all subsequent OpenGL calls.
 193
 194         This is equivalent to wxGLContext::SetCurrent
 195         called with this window as parameter.
 196
 197         Note that this function may only be called when the window is shown on screen,
 198         in particular it can't usually be called from the constructor as the window
 199         isn't yet shown at this moment.
 200
 201         Returns @false if an error occurred.
 202     */
 203     bool SetCurrent(const wxGLContext context);
 204
 205     /**
 206         Swaps the double-buffer of this window, making the back-buffer the front-buffer
 207         and vice versa,
 208         so that the output of the previous OpenGL commands is displayed on the window.
 209
 210         Returns @false if an error occurred.
 211     */
 212     bool SwapBuffers();
 213 };