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