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