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