1 /*************************************************************************
2  * GLFW 3.2 - www.glfw.org
3  * A library for OpenGL, window and input
4  *------------------------------------------------------------------------
5  * Copyright (c) 2002-2006 Marcus Geelnard
6  * Copyright (c) 2006-2010 Camilla Berglund <elmindreda@elmindreda.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
33 extern "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  *
49  *  **By using the native access functions you assert that you know what you're
50  *  doing and how to fix problems caused by using them.  If you don't, you
51  *  shouldn't be using them.**
52  *
53  *  Before the inclusion of @ref glfw3native.h, you may define exactly one
54  *  window system API macro and zero or more context creation API macros.
55  *
56  *  The chosen backends must match those the library was compiled for.  Failure
57  *  to do this will cause a link-time error.
58  *
59  *  The available window API macros are:
60  *  * `GLFW_EXPOSE_NATIVE_WIN32`
61  *  * `GLFW_EXPOSE_NATIVE_COCOA`
62  *  * `GLFW_EXPOSE_NATIVE_X11`
63  *  * `GLFW_EXPOSE_NATIVE_WAYLAND`
64  *  * `GLFW_EXPOSE_NATIVE_MIR`
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  *
72  *  These macros select which of the native access functions that are declared
73  *  and which platform-specific headers to include.  It is then up your (by
74  *  definition platform-specific) code to handle which of these should be
75  *  defined.
76  */
77 
78 
79 /*************************************************************************
80  * System headers and types
81  *************************************************************************/
82 
83 #if defined(GLFW_EXPOSE_NATIVE_WIN32)
84  // This is a workaround for the fact that glfw3.h needs to export APIENTRY (for
85  // example to allow applications to correctly declare a GL_ARB_debug_output
86  // callback) but windows.h assumes no one will define APIENTRY before it does
87  #undef APIENTRY
88  #include <windows.h>
89 #elif defined(GLFW_EXPOSE_NATIVE_COCOA)
90  #include <ApplicationServices/ApplicationServices.h>
91  #if defined(__OBJC__)
92   #import <Cocoa/Cocoa.h>
93  #else
94   typedef void* id;
95  #endif
96 #elif defined(GLFW_EXPOSE_NATIVE_X11)
97  #include <X11/Xlib.h>
98  #include <X11/extensions/Xrandr.h>
99 #elif defined(GLFW_EXPOSE_NATIVE_WAYLAND)
100  #include <wayland-client.h>
101 #elif defined(GLFW_EXPOSE_NATIVE_MIR)
102  #include <mir_toolkit/mir_client_library.h>
103 #endif
104 
105 #if defined(GLFW_EXPOSE_NATIVE_WGL)
106  /* WGL is declared by windows.h */
107 #endif
108 #if defined(GLFW_EXPOSE_NATIVE_NSGL)
109  /* NSGL is declared by Cocoa.h */
110 #endif
111 #if defined(GLFW_EXPOSE_NATIVE_GLX)
112  #include <GL/glx.h>
113 #endif
114 #if defined(GLFW_EXPOSE_NATIVE_EGL)
115  #include <EGL/egl.h>
116 #endif
117 
118 
119 /*************************************************************************
120  * Functions
121  *************************************************************************/
122 
123 #if defined(GLFW_EXPOSE_NATIVE_WIN32)
124 /*! @brief Returns the adapter device name of the specified monitor.
125  *
126  *  @return The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`)
127  *  of the specified monitor, or `NULL` if an [error](@ref error_handling)
128  *  occurred.
129  *
130  *  @thread_safety This function may be called from any thread.  Access is not
131  *  synchronized.
132  *
133  *  @since Added in version 3.1.
134  *
135  *  @ingroup native
136  */
137 GLFWAPI const char* glfwGetWin32Adapter(GLFWmonitor* monitor);
138 
139 /*! @brief Returns the display device name of the specified monitor.
140  *
141  *  @return The UTF-8 encoded display device name (for example
142  *  `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an
143  *  [error](@ref error_handling) occurred.
144  *
145  *  @thread_safety This function may be called from any thread.  Access is not
146  *  synchronized.
147  *
148  *  @since Added in version 3.1.
149  *
150  *  @ingroup native
151  */
152 GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor);
153 
154 /*! @brief Returns the `HWND` of the specified window.
155  *
156  *  @return The `HWND` of the specified window, or `NULL` if an
157  *  [error](@ref error_handling) occurred.
158  *
159  *  @thread_safety This function may be called from any thread.  Access is not
160  *  synchronized.
161  *
162  *  @since Added in version 3.0.
163  *
164  *  @ingroup native
165  */
166 GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
167 #endif
168 
169 #if defined(GLFW_EXPOSE_NATIVE_WGL)
170 /*! @brief Returns the `HGLRC` of the specified window.
171  *
172  *  @return The `HGLRC` of the specified window, or `NULL` if an
173  *  [error](@ref error_handling) occurred.
174  *
175  *  @thread_safety This function may be called from any thread.  Access is not
176  *  synchronized.
177  *
178  *  @since Added in version 3.0.
179  *
180  *  @ingroup native
181  */
182 GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
183 #endif
184 
185 #if defined(GLFW_EXPOSE_NATIVE_COCOA)
186 /*! @brief Returns the `CGDirectDisplayID` of the specified monitor.
187  *
188  *  @return The `CGDirectDisplayID` of the specified monitor, or
189  *  `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred.
190  *
191  *  @thread_safety This function may be called from any thread.  Access is not
192  *  synchronized.
193  *
194  *  @since Added in version 3.1.
195  *
196  *  @ingroup native
197  */
198 GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor);
199 
200 /*! @brief Returns the `NSWindow` of the specified window.
201  *
202  *  @return The `NSWindow` of the specified window, or `nil` if an
203  *  [error](@ref error_handling) occurred.
204  *
205  *  @thread_safety This function may be called from any thread.  Access is not
206  *  synchronized.
207  *
208  *  @since Added in version 3.0.
209  *
210  *  @ingroup native
211  */
212 GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
213 #endif
214 
215 #if defined(GLFW_EXPOSE_NATIVE_NSGL)
216 /*! @brief Returns the `NSOpenGLContext` of the specified window.
217  *
218  *  @return The `NSOpenGLContext` of the specified window, or `nil` if an
219  *  [error](@ref error_handling) occurred.
220  *
221  *  @thread_safety This function may be called from any thread.  Access is not
222  *  synchronized.
223  *
224  *  @since Added in version 3.0.
225  *
226  *  @ingroup native
227  */
228 GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
229 #endif
230 
231 #if defined(GLFW_EXPOSE_NATIVE_X11)
232 /*! @brief Returns the `Display` used by GLFW.
233  *
234  *  @return The `Display` used by GLFW, or `NULL` if an
235  *  [error](@ref error_handling) occurred.
236  *
237  *  @thread_safety This function may be called from any thread.  Access is not
238  *  synchronized.
239  *
240  *  @since Added in version 3.0.
241  *
242  *  @ingroup native
243  */
244 GLFWAPI Display* glfwGetX11Display(void);
245 
246 /*! @brief Returns the `RRCrtc` of the specified monitor.
247  *
248  *  @return The `RRCrtc` of the specified monitor, or `None` if an
249  *  [error](@ref error_handling) occurred.
250  *
251  *  @thread_safety This function may be called from any thread.  Access is not
252  *  synchronized.
253  *
254  *  @since Added in version 3.1.
255  *
256  *  @ingroup native
257  */
258 GLFWAPI RRCrtc glfwGetX11Adapter(GLFWmonitor* monitor);
259 
260 /*! @brief Returns the `RROutput` of the specified monitor.
261  *
262  *  @return The `RROutput` of the specified monitor, or `None` if an
263  *  [error](@ref error_handling) occurred.
264  *
265  *  @thread_safety This function may be called from any thread.  Access is not
266  *  synchronized.
267  *
268  *  @since Added in version 3.1.
269  *
270  *  @ingroup native
271  */
272 GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor);
273 
274 /*! @brief Returns the `Window` of the specified window.
275  *
276  *  @return The `Window` of the specified window, or `None` if an
277  *  [error](@ref error_handling) occurred.
278  *
279  *  @thread_safety This function may be called from any thread.  Access is not
280  *  synchronized.
281  *
282  *  @since Added in version 3.0.
283  *
284  *  @ingroup native
285  */
286 GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
287 #endif
288 
289 #if defined(GLFW_EXPOSE_NATIVE_GLX)
290 /*! @brief Returns the `GLXContext` of the specified window.
291  *
292  *  @return The `GLXContext` of the specified window, or `NULL` if an
293  *  [error](@ref error_handling) occurred.
294  *
295  *  @thread_safety This function may be called from any thread.  Access is not
296  *  synchronized.
297  *
298  *  @since Added in version 3.0.
299  *
300  *  @ingroup native
301  */
302 GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
303 
304 /*! @brief Returns the `GLXWindow` of the specified window.
305  *
306  *  @return The `GLXWindow` of the specified window, or `None` if an
307  *  [error](@ref error_handling) occurred.
308  *
309  *  @thread_safety This function may be called from any thread.  Access is not
310  *  synchronized.
311  *
312  *  @since Added in version 3.2.
313  *
314  *  @ingroup native
315  */
316 GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* window);
317 #endif
318 
319 #if defined(GLFW_EXPOSE_NATIVE_WAYLAND)
320 /*! @brief Returns the `struct wl_display*` used by GLFW.
321  *
322  *  @return The `struct wl_display*` used by GLFW, or `NULL` if an
323  *  [error](@ref error_handling) occurred.
324  *
325  *  @thread_safety This function may be called from any thread.  Access is not
326  *  synchronized.
327  *
328  *  @since Added in version 3.2.
329  *
330  *  @ingroup native
331  */
332 GLFWAPI struct wl_display* glfwGetWaylandDisplay(void);
333 
334 /*! @brief Returns the `struct wl_output*` of the specified monitor.
335  *
336  *  @return The `struct wl_output*` of the specified monitor, or `NULL` if an
337  *  [error](@ref error_handling) occurred.
338  *
339  *  @thread_safety This function may be called from any thread.  Access is not
340  *  synchronized.
341  *
342  *  @since Added in version 3.2.
343  *
344  *  @ingroup native
345  */
346 GLFWAPI struct wl_output* glfwGetWaylandMonitor(GLFWmonitor* monitor);
347 
348 /*! @brief Returns the main `struct wl_surface*` of the specified window.
349  *
350  *  @return The main `struct wl_surface*` of the specified window, or `NULL` if
351  *  an [error](@ref error_handling) occurred.
352  *
353  *  @thread_safety This function may be called from any thread.  Access is not
354  *  synchronized.
355  *
356  *  @since Added in version 3.2.
357  *
358  *  @ingroup native
359  */
360 GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* window);
361 #endif
362 
363 #if defined(GLFW_EXPOSE_NATIVE_MIR)
364 /*! @brief Returns the `MirConnection*` used by GLFW.
365  *
366  *  @return The `MirConnection*` used by GLFW, or `NULL` if an
367  *  [error](@ref error_handling) occurred.
368  *
369  *  @thread_safety This function may be called from any thread.  Access is not
370  *  synchronized.
371  *
372  *  @since Added in version 3.2.
373  *
374  *  @ingroup native
375  */
376 GLFWAPI MirConnection* glfwGetMirDisplay(void);
377 
378 /*! @brief Returns the Mir output ID of the specified monitor.
379  *
380  *  @return The Mir output ID of the specified monitor, or zero if an
381  *  [error](@ref error_handling) occurred.
382  *
383  *  @thread_safety This function may be called from any thread.  Access is not
384  *  synchronized.
385  *
386  *  @since Added in version 3.2.
387  *
388  *  @ingroup native
389  */
390 GLFWAPI int glfwGetMirMonitor(GLFWmonitor* monitor);
391 
392 /*! @brief Returns the `MirSurface*` of the specified window.
393  *
394  *  @return The `MirSurface*` of the specified window, or `NULL` if an
395  *  [error](@ref error_handling) occurred.
396  *
397  *  @thread_safety This function may be called from any thread.  Access is not
398  *  synchronized.
399  *
400  *  @since Added in version 3.2.
401  *
402  *  @ingroup native
403  */
404 GLFWAPI MirSurface* glfwGetMirWindow(GLFWwindow* window);
405 #endif
406 
407 #if defined(GLFW_EXPOSE_NATIVE_EGL)
408 /*! @brief Returns the `EGLDisplay` used by GLFW.
409  *
410  *  @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an
411  *  [error](@ref error_handling) occurred.
412  *
413  *  @thread_safety This function may be called from any thread.  Access is not
414  *  synchronized.
415  *
416  *  @since Added in version 3.0.
417  *
418  *  @ingroup native
419  */
420 GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
421 
422 /*! @brief Returns the `EGLContext` of the specified window.
423  *
424  *  @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an
425  *  [error](@ref error_handling) occurred.
426  *
427  *  @thread_safety This function may be called from any thread.  Access is not
428  *  synchronized.
429  *
430  *  @since Added in version 3.0.
431  *
432  *  @ingroup native
433  */
434 GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
435 
436 /*! @brief Returns the `EGLSurface` of the specified window.
437  *
438  *  @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an
439  *  [error](@ref error_handling) occurred.
440  *
441  *  @thread_safety This function may be called from any thread.  Access is not
442  *  synchronized.
443  *
444  *  @since Added in version 3.0.
445  *
446  *  @ingroup native
447  */
448 GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
449 #endif
450 
451 #ifdef __cplusplus
452 }
453 #endif
454 
455 #endif /* _glfw3_native_h_ */
456 
457