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 |
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 | * @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 | */ |
148 | GLFWAPI 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 | */ |
163 | GLFWAPI 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 | */ |
177 | GLFWAPI 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 | */ |
193 | GLFWAPI 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 | */ |
209 | GLFWAPI 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 | */ |
223 | GLFWAPI 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 | */ |
239 | GLFWAPI 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 | */ |
255 | GLFWAPI 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 | */ |
269 | GLFWAPI 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 | */ |
283 | GLFWAPI 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 | */ |
297 | GLFWAPI 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 | */ |
319 | GLFWAPI 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 | */ |
347 | GLFWAPI 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 | */ |
363 | GLFWAPI 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 | */ |
377 | GLFWAPI 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 | */ |
393 | GLFWAPI 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 | */ |
407 | GLFWAPI 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 | */ |
421 | GLFWAPI 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 | */ |
437 | GLFWAPI 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 | */ |
451 | GLFWAPI 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 | */ |
465 | GLFWAPI 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 | */ |
488 | GLFWAPI 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 | */ |
509 | GLFWAPI 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 | */ |
523 | GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window); |
524 | #endif |
525 | |
526 | #ifdef __cplusplus |
527 | } |
528 | #endif |
529 | |
530 | #endif /* _glfw3_native_h_ */ |
531 | |
532 | |