1/*************************************************************************
2 * GLFW 3.4 - www.glfw.org
3 * A library for OpenGL, window and input
4 *------------------------------------------------------------------------
5 * Copyright (c) 2002-2006 Marcus Geelnard
6 * Copyright (c) 2006-2018 Camilla Löwy <elmindreda@glfw.org>
7 *
8 * This software is provided 'as-is', without any express or implied
9 * warranty. In no event will the authors be held liable for any damages
10 * arising from the use of this software.
11 *
12 * Permission is granted to anyone to use this software for any purpose,
13 * including commercial applications, and to alter it and redistribute it
14 * freely, subject to the following restrictions:
15 *
16 * 1. The origin of this software must not be misrepresented; you must not
17 * claim that you wrote the original software. If you use this software
18 * in a product, an acknowledgment in the product documentation would
19 * be appreciated but is not required.
20 *
21 * 2. Altered source versions must be plainly marked as such, and must not
22 * be misrepresented as being the original software.
23 *
24 * 3. This notice may not be removed or altered from any source
25 * distribution.
26 *
27 *************************************************************************/
28
29#ifndef _glfw3_native_h_
30#define _glfw3_native_h_
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36
37/*************************************************************************
38 * Doxygen documentation
39 *************************************************************************/
40
41/*! @file glfw3native.h
42 * @brief The header of the native access functions.
43 *
44 * This is the header file of the native access functions. See @ref native for
45 * more information.
46 */
47/*! @defgroup native Native access
48 * @brief Functions related to accessing native handles.
49 *
50 * **By using the native access functions you assert that you know what you're
51 * doing and how to fix problems caused by using them. If you don't, you
52 * shouldn't be using them.**
53 *
54 * Before the inclusion of @ref glfw3native.h, you may define zero or more
55 * window system API macro and zero or more context creation API macros.
56 *
57 * The chosen backends must match those the library was compiled for. Failure
58 * to do this will cause a link-time error.
59 *
60 * The available window API macros are:
61 * * `GLFW_EXPOSE_NATIVE_WIN32`
62 * * `GLFW_EXPOSE_NATIVE_COCOA`
63 * * `GLFW_EXPOSE_NATIVE_X11`
64 * * `GLFW_EXPOSE_NATIVE_WAYLAND`
65 *
66 * The available context API macros are:
67 * * `GLFW_EXPOSE_NATIVE_WGL`
68 * * `GLFW_EXPOSE_NATIVE_NSGL`
69 * * `GLFW_EXPOSE_NATIVE_GLX`
70 * * `GLFW_EXPOSE_NATIVE_EGL`
71 * * `GLFW_EXPOSE_NATIVE_OSMESA`
72 *
73 * These macros select which of the native access functions that are declared
74 * and which platform-specific headers to include. It is then up your (by
75 * definition platform-specific) code to handle which of these should be
76 * defined.
77 */
78
79
80/*************************************************************************
81 * System headers and types
82 *************************************************************************/
83
84#if defined(GLFW_EXPOSE_NATIVE_WIN32) || defined(GLFW_EXPOSE_NATIVE_WGL)
85 // This is a workaround for the fact that glfw3.h needs to export APIENTRY (for
86 // example to allow applications to correctly declare a GL_ARB_debug_output
87 // callback) but windows.h assumes no one will define APIENTRY before it does
88 #if defined(GLFW_APIENTRY_DEFINED)
89 #undef APIENTRY
90 #undef GLFW_APIENTRY_DEFINED
91 #endif
92// @raysan5: Actually, only HWND handler needs to be defined
93// Including windows.h could suppose symbols re-definition issues (i.e Rectangle type)
94//#include <windows.h>
95 typedef void *PVOID;
96 typedef PVOID HANDLE;
97 typedef HANDLE HWND;
98#elif defined(GLFW_EXPOSE_NATIVE_COCOA) || defined(GLFW_EXPOSE_NATIVE_NSGL)
99 #include <ApplicationServices/ApplicationServices.h>
100 #if defined(__OBJC__)
101 #import <Cocoa/Cocoa.h>
102 #else
103 #include <ApplicationServices/ApplicationServices.h>
104 typedef void* id;
105 #endif
106#elif defined(GLFW_EXPOSE_NATIVE_X11) || defined(GLFW_EXPOSE_NATIVE_GLX)
107 #include <X11/Xlib.h>
108 #include <X11/extensions/Xrandr.h>
109#elif defined(GLFW_EXPOSE_NATIVE_WAYLAND)
110 #include <wayland-client.h>
111#endif
112
113#if defined(GLFW_EXPOSE_NATIVE_WGL)
114 /* WGL is declared by windows.h */
115#endif
116#if defined(GLFW_EXPOSE_NATIVE_NSGL)
117 /* NSGL is declared by Cocoa.h */
118#endif
119#if defined(GLFW_EXPOSE_NATIVE_GLX)
120 #include <GL/glx.h>
121#endif
122#if defined(GLFW_EXPOSE_NATIVE_EGL)
123 #include <EGL/egl.h>
124#endif
125#if defined(GLFW_EXPOSE_NATIVE_OSMESA)
126 #include <GL/osmesa.h>
127#endif
128
129
130/*************************************************************************
131 * Functions
132 *************************************************************************/
133
134#if defined(GLFW_EXPOSE_NATIVE_WIN32)
135/*! @brief Returns the adapter device name of the specified monitor.
136 *
137 * @return The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`)
138 * of the specified monitor, or `NULL` if an [error](@ref error_handling)
139 * occurred.
140 *
141 * @thread_safety This function may be called from any thread. Access is not
142 * synchronized.
143 *
144 * @since Added in version 3.1.
145 *
146 * @ingroup native
147 */
148GLFWAPI const char* glfwGetWin32Adapter(GLFWmonitor* monitor);
149
150/*! @brief Returns the display device name of the specified monitor.
151 *
152 * @return The UTF-8 encoded display device name (for example
153 * `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an
154 * [error](@ref error_handling) occurred.
155 *
156 * @thread_safety This function may be called from any thread. Access is not
157 * synchronized.
158 *
159 * @since Added in version 3.1.
160 *
161 * @ingroup native
162 */
163GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor);
164
165/*! @brief Returns the `HWND` of the specified window.
166 *
167 * @return The `HWND` of the specified window, or `NULL` if an
168 * [error](@ref error_handling) occurred.
169 *
170 * @thread_safety This function may be called from any thread. Access is not
171 * synchronized.
172 *
173 * @since Added in version 3.0.
174 *
175 * @ingroup native
176 */
177GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
178#endif
179
180#if defined(GLFW_EXPOSE_NATIVE_WGL)
181/*! @brief Returns the `HGLRC` of the specified window.
182 *
183 * @return The `HGLRC` of the specified window, or `NULL` if an
184 * [error](@ref error_handling) occurred.
185 *
186 * @thread_safety This function may be called from any thread. Access is not
187 * synchronized.
188 *
189 * @since Added in version 3.0.
190 *
191 * @ingroup native
192 */
193GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
194#endif
195
196#if defined(GLFW_EXPOSE_NATIVE_COCOA)
197/*! @brief Returns the `CGDirectDisplayID` of the specified monitor.
198 *
199 * @return The `CGDirectDisplayID` of the specified monitor, or
200 * `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred.
201 *
202 * @thread_safety This function may be called from any thread. Access is not
203 * synchronized.
204 *
205 * @since Added in version 3.1.
206 *
207 * @ingroup native
208 */
209GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor);
210
211/*! @brief Returns the `NSWindow` of the specified window.
212 *
213 * @return The `NSWindow` of the specified window, or `nil` if an
214 * [error](@ref error_handling) occurred.
215 *
216 * @thread_safety This function may be called from any thread. Access is not
217 * synchronized.
218 *
219 * @since Added in version 3.0.
220 *
221 * @ingroup native
222 */
223GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
224#endif
225
226#if defined(GLFW_EXPOSE_NATIVE_NSGL)
227/*! @brief Returns the `NSOpenGLContext` of the specified window.
228 *
229 * @return The `NSOpenGLContext` of the specified window, or `nil` if an
230 * [error](@ref error_handling) occurred.
231 *
232 * @thread_safety This function may be called from any thread. Access is not
233 * synchronized.
234 *
235 * @since Added in version 3.0.
236 *
237 * @ingroup native
238 */
239GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
240#endif
241
242#if defined(GLFW_EXPOSE_NATIVE_X11)
243/*! @brief Returns the `Display` used by GLFW.
244 *
245 * @return The `Display` used by GLFW, or `NULL` if an
246 * [error](@ref error_handling) occurred.
247 *
248 * @thread_safety This function may be called from any thread. Access is not
249 * synchronized.
250 *
251 * @since Added in version 3.0.
252 *
253 * @ingroup native
254 */
255GLFWAPI Display* glfwGetX11Display(void);
256
257/*! @brief Returns the `RRCrtc` of the specified monitor.
258 *
259 * @return The `RRCrtc` of the specified monitor, or `None` if an
260 * [error](@ref error_handling) occurred.
261 *
262 * @thread_safety This function may be called from any thread. Access is not
263 * synchronized.
264 *
265 * @since Added in version 3.1.
266 *
267 * @ingroup native
268 */
269GLFWAPI RRCrtc glfwGetX11Adapter(GLFWmonitor* monitor);
270
271/*! @brief Returns the `RROutput` of the specified monitor.
272 *
273 * @return The `RROutput` of the specified monitor, or `None` if an
274 * [error](@ref error_handling) occurred.
275 *
276 * @thread_safety This function may be called from any thread. Access is not
277 * synchronized.
278 *
279 * @since Added in version 3.1.
280 *
281 * @ingroup native
282 */
283GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor);
284
285/*! @brief Returns the `Window` of the specified window.
286 *
287 * @return The `Window` of the specified window, or `None` if an
288 * [error](@ref error_handling) occurred.
289 *
290 * @thread_safety This function may be called from any thread. Access is not
291 * synchronized.
292 *
293 * @since Added in version 3.0.
294 *
295 * @ingroup native
296 */
297GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
298
299/*! @brief Sets the current primary selection to the specified string.
300 *
301 * @param[in] string A UTF-8 encoded string.
302 *
303 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
304 * GLFW_PLATFORM_ERROR.
305 *
306 * @pointer_lifetime The specified string is copied before this function
307 * returns.
308 *
309 * @thread_safety This function must only be called from the main thread.
310 *
311 * @sa @ref clipboard
312 * @sa glfwGetX11SelectionString
313 * @sa glfwSetClipboardString
314 *
315 * @since Added in version 3.3.
316 *
317 * @ingroup native
318 */
319GLFWAPI void glfwSetX11SelectionString(const char* string);
320
321/*! @brief Returns the contents of the current primary selection as a string.
322 *
323 * If the selection is empty or if its contents cannot be converted, `NULL`
324 * is returned and a @ref GLFW_FORMAT_UNAVAILABLE error is generated.
325 *
326 * @return The contents of the selection as a UTF-8 encoded string, or `NULL`
327 * if an [error](@ref error_handling) occurred.
328 *
329 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
330 * GLFW_PLATFORM_ERROR.
331 *
332 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
333 * should not free it yourself. It is valid until the next call to @ref
334 * glfwGetX11SelectionString or @ref glfwSetX11SelectionString, or until the
335 * library is terminated.
336 *
337 * @thread_safety This function must only be called from the main thread.
338 *
339 * @sa @ref clipboard
340 * @sa glfwSetX11SelectionString
341 * @sa glfwGetClipboardString
342 *
343 * @since Added in version 3.3.
344 *
345 * @ingroup native
346 */
347GLFWAPI const char* glfwGetX11SelectionString(void);
348#endif
349
350#if defined(GLFW_EXPOSE_NATIVE_GLX)
351/*! @brief Returns the `GLXContext` of the specified window.
352 *
353 * @return The `GLXContext` of the specified window, or `NULL` if an
354 * [error](@ref error_handling) occurred.
355 *
356 * @thread_safety This function may be called from any thread. Access is not
357 * synchronized.
358 *
359 * @since Added in version 3.0.
360 *
361 * @ingroup native
362 */
363GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
364
365/*! @brief Returns the `GLXWindow` of the specified window.
366 *
367 * @return The `GLXWindow` of the specified window, or `None` if an
368 * [error](@ref error_handling) occurred.
369 *
370 * @thread_safety This function may be called from any thread. Access is not
371 * synchronized.
372 *
373 * @since Added in version 3.2.
374 *
375 * @ingroup native
376 */
377GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* window);
378#endif
379
380#if defined(GLFW_EXPOSE_NATIVE_WAYLAND)
381/*! @brief Returns the `struct wl_display*` used by GLFW.
382 *
383 * @return The `struct wl_display*` used by GLFW, or `NULL` if an
384 * [error](@ref error_handling) occurred.
385 *
386 * @thread_safety This function may be called from any thread. Access is not
387 * synchronized.
388 *
389 * @since Added in version 3.2.
390 *
391 * @ingroup native
392 */
393GLFWAPI struct wl_display* glfwGetWaylandDisplay(void);
394
395/*! @brief Returns the `struct wl_output*` of the specified monitor.
396 *
397 * @return The `struct wl_output*` of the specified monitor, or `NULL` if an
398 * [error](@ref error_handling) occurred.
399 *
400 * @thread_safety This function may be called from any thread. Access is not
401 * synchronized.
402 *
403 * @since Added in version 3.2.
404 *
405 * @ingroup native
406 */
407GLFWAPI struct wl_output* glfwGetWaylandMonitor(GLFWmonitor* monitor);
408
409/*! @brief Returns the main `struct wl_surface*` of the specified window.
410 *
411 * @return The main `struct wl_surface*` of the specified window, or `NULL` if
412 * an [error](@ref error_handling) occurred.
413 *
414 * @thread_safety This function may be called from any thread. Access is not
415 * synchronized.
416 *
417 * @since Added in version 3.2.
418 *
419 * @ingroup native
420 */
421GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* window);
422#endif
423
424#if defined(GLFW_EXPOSE_NATIVE_EGL)
425/*! @brief Returns the `EGLDisplay` used by GLFW.
426 *
427 * @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an
428 * [error](@ref error_handling) occurred.
429 *
430 * @thread_safety This function may be called from any thread. Access is not
431 * synchronized.
432 *
433 * @since Added in version 3.0.
434 *
435 * @ingroup native
436 */
437GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
438
439/*! @brief Returns the `EGLContext` of the specified window.
440 *
441 * @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an
442 * [error](@ref error_handling) occurred.
443 *
444 * @thread_safety This function may be called from any thread. Access is not
445 * synchronized.
446 *
447 * @since Added in version 3.0.
448 *
449 * @ingroup native
450 */
451GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
452
453/*! @brief Returns the `EGLSurface` of the specified window.
454 *
455 * @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an
456 * [error](@ref error_handling) occurred.
457 *
458 * @thread_safety This function may be called from any thread. Access is not
459 * synchronized.
460 *
461 * @since Added in version 3.0.
462 *
463 * @ingroup native
464 */
465GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
466#endif
467
468#if defined(GLFW_EXPOSE_NATIVE_OSMESA)
469/*! @brief Retrieves the color buffer associated with the specified window.
470 *
471 * @param[in] window The window whose color buffer to retrieve.
472 * @param[out] width Where to store the width of the color buffer, or `NULL`.
473 * @param[out] height Where to store the height of the color buffer, or `NULL`.
474 * @param[out] format Where to store the OSMesa pixel format of the color
475 * buffer, or `NULL`.
476 * @param[out] buffer Where to store the address of the color buffer, or
477 * `NULL`.
478 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
479 * [error](@ref error_handling) occurred.
480 *
481 * @thread_safety This function may be called from any thread. Access is not
482 * synchronized.
483 *
484 * @since Added in version 3.3.
485 *
486 * @ingroup native
487 */
488GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height, int* format, void** buffer);
489
490/*! @brief Retrieves the depth buffer associated with the specified window.
491 *
492 * @param[in] window The window whose depth buffer to retrieve.
493 * @param[out] width Where to store the width of the depth buffer, or `NULL`.
494 * @param[out] height Where to store the height of the depth buffer, or `NULL`.
495 * @param[out] bytesPerValue Where to store the number of bytes per depth
496 * buffer element, or `NULL`.
497 * @param[out] buffer Where to store the address of the depth buffer, or
498 * `NULL`.
499 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
500 * [error](@ref error_handling) occurred.
501 *
502 * @thread_safety This function may be called from any thread. Access is not
503 * synchronized.
504 *
505 * @since Added in version 3.3.
506 *
507 * @ingroup native
508 */
509GLFWAPI int glfwGetOSMesaDepthBuffer(GLFWwindow* window, int* width, int* height, int* bytesPerValue, void** buffer);
510
511/*! @brief Returns the `OSMesaContext` of the specified window.
512 *
513 * @return The `OSMesaContext` of the specified window, or `NULL` if an
514 * [error](@ref error_handling) occurred.
515 *
516 * @thread_safety This function may be called from any thread. Access is not
517 * synchronized.
518 *
519 * @since Added in version 3.3.
520 *
521 * @ingroup native
522 */
523GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window);
524#endif
525
526#ifdef __cplusplus
527}
528#endif
529
530#endif /* _glfw3_native_h_ */
531
532