1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gdk.GLContext;
26 
27 private import gdk.Display;
28 private import gdk.DrawContext;
29 private import gdk.Surface;
30 private import gdk.c.functions;
31 public  import gdk.c.types;
32 private import glib.ErrorG;
33 private import glib.GException;
34 private import gobject.ObjectG;
35 
36 
37 /**
38  * `GdkGLContext` is an object representing a platform-specific
39  * OpenGL draw context.
40  * 
41  * `GdkGLContext`s are created for a surface using
42  * [method@Gdk.Surface.create_gl_context], and the context will match
43  * the the characteristics of the surface.
44  * 
45  * A `GdkGLContext` is not tied to any particular normal framebuffer.
46  * For instance, it cannot draw to the surface back buffer. The GDK
47  * repaint system is in full control of the painting to that. Instead,
48  * you can create render buffers or textures and use [func@cairo_draw_from_gl]
49  * in the draw function of your widget to draw them. Then GDK will handle
50  * the integration of your rendering with that of other widgets.
51  * 
52  * Support for `GdkGLContext` is platform-specific and context creation
53  * can fail, returning %NULL context.
54  * 
55  * A `GdkGLContext` has to be made "current" in order to start using
56  * it, otherwise any OpenGL call will be ignored.
57  * 
58  * ## Creating a new OpenGL context
59  * 
60  * In order to create a new `GdkGLContext` instance you need a `GdkSurface`,
61  * which you typically get during the realize call of a widget.
62  * 
63  * A `GdkGLContext` is not realized until either [method@Gdk.GLContext.make_current]
64  * or [method@Gdk.GLContext.realize] is called. It is possible to specify
65  * details of the GL context like the OpenGL version to be used, or whether
66  * the GL context should have extra state validation enabled after calling
67  * [method@Gdk.Surface.create_gl_context] by calling [method@Gdk.GLContext.realize].
68  * If the realization fails you have the option to change the settings of
69  * the `GdkGLContext` and try again.
70  * 
71  * ## Using a GdkGLContext
72  * 
73  * You will need to make the `GdkGLContext` the current context before issuing
74  * OpenGL calls; the system sends OpenGL commands to whichever context is current.
75  * It is possible to have multiple contexts, so you always need to ensure that
76  * the one which you want to draw with is the current one before issuing commands:
77  * 
78  * ```c
79  * gdk_gl_context_make_current (context);
80  * ```
81  * 
82  * You can now perform your drawing using OpenGL commands.
83  * 
84  * You can check which `GdkGLContext` is the current one by using
85  * [func@Gdk.GLContext.get_current]; you can also unset any `GdkGLContext`
86  * that is currently set by calling [func@Gdk.GLContext.clear_current].
87  */
88 public class GLContext : DrawContext
89 {
90 	/** the main Gtk struct */
91 	protected GdkGLContext* gdkGLContext;
92 
93 	/** Get the main Gtk struct */
94 	public GdkGLContext* getGLContextStruct(bool transferOwnership = false)
95 	{
96 		if (transferOwnership)
97 			ownedRef = false;
98 		return gdkGLContext;
99 	}
100 
101 	/** the main Gtk struct as a void* */
102 	protected override void* getStruct()
103 	{
104 		return cast(void*)gdkGLContext;
105 	}
106 
107 	/**
108 	 * Sets our main struct and passes it to the parent class.
109 	 */
110 	public this (GdkGLContext* gdkGLContext, bool ownedRef = false)
111 	{
112 		this.gdkGLContext = gdkGLContext;
113 		super(cast(GdkDrawContext*)gdkGLContext, ownedRef);
114 	}
115 
116 
117 	/** */
118 	public static GType getType()
119 	{
120 		return gdk_gl_context_get_type();
121 	}
122 
123 	/**
124 	 * Clears the current `GdkGLContext`.
125 	 *
126 	 * Any OpenGL call after this function returns will be ignored
127 	 * until [method@Gdk.GLContext.make_current] is called.
128 	 */
129 	public static void clearCurrent()
130 	{
131 		gdk_gl_context_clear_current();
132 	}
133 
134 	/**
135 	 * Retrieves the current `GdkGLContext`.
136 	 *
137 	 * Returns: the current `GdkGLContext`, or %NULL
138 	 */
139 	public static GLContext getCurrent()
140 	{
141 		auto __p = gdk_gl_context_get_current();
142 
143 		if(__p is null)
144 		{
145 			return null;
146 		}
147 
148 		return ObjectG.getDObject!(GLContext)(cast(GdkGLContext*) __p);
149 	}
150 
151 	/**
152 	 * Retrieves whether the context is doing extra validations and runtime checking.
153 	 *
154 	 * See [method@Gdk.GLContext.set_debug_enabled].
155 	 *
156 	 * Returns: %TRUE if debugging is enabled
157 	 */
158 	public bool getDebugEnabled()
159 	{
160 		return gdk_gl_context_get_debug_enabled(gdkGLContext) != 0;
161 	}
162 
163 	/**
164 	 * Retrieves the display the @context is created for
165 	 *
166 	 * Returns: a `GdkDisplay` or %NULL
167 	 */
168 	public override Display getDisplay()
169 	{
170 		auto __p = gdk_gl_context_get_display(gdkGLContext);
171 
172 		if(__p is null)
173 		{
174 			return null;
175 		}
176 
177 		return ObjectG.getDObject!(Display)(cast(GdkDisplay*) __p);
178 	}
179 
180 	/**
181 	 * Retrieves whether the context is forward-compatible.
182 	 *
183 	 * See [method@Gdk.GLContext.set_forward_compatible].
184 	 *
185 	 * Returns: %TRUE if the context should be forward-compatible
186 	 */
187 	public bool getForwardCompatible()
188 	{
189 		return gdk_gl_context_get_forward_compatible(gdkGLContext) != 0;
190 	}
191 
192 	/**
193 	 * Retrieves required OpenGL version.
194 	 *
195 	 * See [method@Gdk.GLContext.set_required_version].
196 	 *
197 	 * Params:
198 	 *     major = return location for the major version to request
199 	 *     minor = return location for the minor version to request
200 	 */
201 	public void getRequiredVersion(out int major, out int minor)
202 	{
203 		gdk_gl_context_get_required_version(gdkGLContext, &major, &minor);
204 	}
205 
206 	/**
207 	 * Retrieves the `GdkGLContext` that this @context share data with.
208 	 *
209 	 * Returns: a `GdkGLContext` or %NULL
210 	 */
211 	public GLContext getSharedContext()
212 	{
213 		auto __p = gdk_gl_context_get_shared_context(gdkGLContext);
214 
215 		if(__p is null)
216 		{
217 			return null;
218 		}
219 
220 		return ObjectG.getDObject!(GLContext)(cast(GdkGLContext*) __p);
221 	}
222 
223 	/**
224 	 * Retrieves the surface used by the @context.
225 	 *
226 	 * Returns: a `GdkSurface` or %NULL
227 	 */
228 	public override Surface getSurface()
229 	{
230 		auto __p = gdk_gl_context_get_surface(gdkGLContext);
231 
232 		if(__p is null)
233 		{
234 			return null;
235 		}
236 
237 		return ObjectG.getDObject!(Surface)(cast(GdkSurface*) __p);
238 	}
239 
240 	/**
241 	 * Checks whether the @context is using an OpenGL or OpenGL ES profile.
242 	 *
243 	 * Returns: %TRUE if the `GdkGLContext` is using an OpenGL ES profile
244 	 */
245 	public bool getUseEs()
246 	{
247 		return gdk_gl_context_get_use_es(gdkGLContext) != 0;
248 	}
249 
250 	/**
251 	 * Retrieves the OpenGL version of the @context.
252 	 *
253 	 * The @context must be realized prior to calling this function.
254 	 *
255 	 * Params:
256 	 *     major = return location for the major version
257 	 *     minor = return location for the minor version
258 	 */
259 	public void getVersion(out int major, out int minor)
260 	{
261 		gdk_gl_context_get_version(gdkGLContext, &major, &minor);
262 	}
263 
264 	/**
265 	 * Whether the `GdkGLContext` is in legacy mode or not.
266 	 *
267 	 * The `GdkGLContext` must be realized before calling this function.
268 	 *
269 	 * When realizing a GL context, GDK will try to use the OpenGL 3.2 core
270 	 * profile; this profile removes all the OpenGL API that was deprecated
271 	 * prior to the 3.2 version of the specification. If the realization is
272 	 * successful, this function will return %FALSE.
273 	 *
274 	 * If the underlying OpenGL implementation does not support core profiles,
275 	 * GDK will fall back to a pre-3.2 compatibility profile, and this function
276 	 * will return %TRUE.
277 	 *
278 	 * You can use the value returned by this function to decide which kind
279 	 * of OpenGL API to use, or whether to do extension discovery, or what
280 	 * kind of shader programs to load.
281 	 *
282 	 * Returns: %TRUE if the GL context is in legacy mode
283 	 */
284 	public bool isLegacy()
285 	{
286 		return gdk_gl_context_is_legacy(gdkGLContext) != 0;
287 	}
288 
289 	/**
290 	 * Makes the @context the current one.
291 	 */
292 	public void makeCurrent()
293 	{
294 		gdk_gl_context_make_current(gdkGLContext);
295 	}
296 
297 	/**
298 	 * Realizes the given `GdkGLContext`.
299 	 *
300 	 * It is safe to call this function on a realized `GdkGLContext`.
301 	 *
302 	 * Returns: %TRUE if the context is realized
303 	 *
304 	 * Throws: GException on failure.
305 	 */
306 	public bool realize()
307 	{
308 		GError* err = null;
309 
310 		auto __p = gdk_gl_context_realize(gdkGLContext, &err) != 0;
311 
312 		if (err !is null)
313 		{
314 			throw new GException( new ErrorG(err) );
315 		}
316 
317 		return __p;
318 	}
319 
320 	/**
321 	 * Sets whether the `GdkGLContext` should perform extra validations and
322 	 * runtime checking.
323 	 *
324 	 * This is useful during development, but has additional overhead.
325 	 *
326 	 * The `GdkGLContext` must not be realized or made current prior to
327 	 * calling this function.
328 	 *
329 	 * Params:
330 	 *     enabled = whether to enable debugging in the context
331 	 */
332 	public void setDebugEnabled(bool enabled)
333 	{
334 		gdk_gl_context_set_debug_enabled(gdkGLContext, enabled);
335 	}
336 
337 	/**
338 	 * Sets whether the `GdkGLContext` should be forward-compatible.
339 	 *
340 	 * Forward-compatible contexts must not support OpenGL functionality that
341 	 * has been marked as deprecated in the requested version; non-forward
342 	 * compatible contexts, on the other hand, must support both deprecated and
343 	 * non deprecated functionality.
344 	 *
345 	 * The `GdkGLContext` must not be realized or made current prior to calling
346 	 * this function.
347 	 *
348 	 * Params:
349 	 *     compatible = whether the context should be forward-compatible
350 	 */
351 	public void setForwardCompatible(bool compatible)
352 	{
353 		gdk_gl_context_set_forward_compatible(gdkGLContext, compatible);
354 	}
355 
356 	/**
357 	 * Sets the major and minor version of OpenGL to request.
358 	 *
359 	 * Setting @major and @minor to zero will use the default values.
360 	 *
361 	 * The `GdkGLContext` must not be realized or made current prior to calling
362 	 * this function.
363 	 *
364 	 * Params:
365 	 *     major = the major version to request
366 	 *     minor = the minor version to request
367 	 */
368 	public void setRequiredVersion(int major, int minor)
369 	{
370 		gdk_gl_context_set_required_version(gdkGLContext, major, minor);
371 	}
372 
373 	/**
374 	 * Requests that GDK create an OpenGL ES context instead of an OpenGL one.
375 	 *
376 	 * Not all platforms support OpenGL ES.
377 	 *
378 	 * The @context must not have been realized.
379 	 *
380 	 * By default, GDK will attempt to automatically detect whether the
381 	 * underlying GL implementation is OpenGL or OpenGL ES once the @context
382 	 * is realized.
383 	 *
384 	 * You should check the return value of [method@Gdk.GLContext.get_use_es]
385 	 * after calling [method@Gdk.GLContext.realize] to decide whether to use
386 	 * the OpenGL or OpenGL ES API, extensions, or shaders.
387 	 *
388 	 * Params:
389 	 *     useEs = whether the context should use OpenGL ES instead of OpenGL,
390 	 *         or -1 to allow auto-detection
391 	 */
392 	public void setUseEs(int useEs)
393 	{
394 		gdk_gl_context_set_use_es(gdkGLContext, useEs);
395 	}
396 }