]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/glcanvas.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / 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 };