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