1 /************************************************************************* 2 * GLFW 3.3 - www.glfw.org 3 * A library for OpenGL, window and input 4 *------------------------------------------------------------------------ 5 * Copyright (c) 2002-2006 Marcus Geelnard 6 * Copyright (c) 2006-2016 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) 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 #include <windows.h> 93 #elif defined(GLFW_EXPOSE_NATIVE_COCOA) 94 #include <ApplicationServices/ApplicationServices.h> 95 #if defined(__OBJC__) 96 #import <Cocoa/Cocoa.h> 97 #else 98 typedef void* id; 99 #endif 100 #elif defined(GLFW_EXPOSE_NATIVE_X11) 101 #include <X11/Xlib.h> 102 #include <X11/extensions/Xrandr.h> 103 #elif defined(GLFW_EXPOSE_NATIVE_WAYLAND) 104 #include <wayland-client.h> 105 #endif 106 107 #if defined(GLFW_EXPOSE_NATIVE_WGL) 108 /* WGL is declared by windows.h */ 109 #endif 110 #if defined(GLFW_EXPOSE_NATIVE_NSGL) 111 /* NSGL is declared by Cocoa.h */ 112 #endif 113 #if defined(GLFW_EXPOSE_NATIVE_GLX) 114 #include <GL/glx.h> 115 #endif 116 #if defined(GLFW_EXPOSE_NATIVE_EGL) 117 #include <EGL/egl.h> 118 #endif 119 #if defined(GLFW_EXPOSE_NATIVE_OSMESA) 120 #include <GL/osmesa.h> 121 #endif 122 123 124 /************************************************************************* 125 * Functions 126 *************************************************************************/ 127 128 #if defined(GLFW_EXPOSE_NATIVE_WIN32) 129 /*! @brief Returns the adapter device name of the specified monitor. 130 * 131 * @return The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`) 132 * of the specified monitor, or `NULL` if an [error](@ref error_handling) 133 * occurred. 134 * 135 * @thread_safety This function may be called from any thread. Access is not 136 * synchronized. 137 * 138 * @since Added in version 3.1. 139 * 140 * @ingroup native 141 */ 142 GLFWAPI const char* glfwGetWin32Adapter(GLFWmonitor* monitor); 143 144 /*! @brief Returns the display device name of the specified monitor. 145 * 146 * @return The UTF-8 encoded display device name (for example 147 * `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an 148 * [error](@ref error_handling) occurred. 149 * 150 * @thread_safety This function may be called from any thread. Access is not 151 * synchronized. 152 * 153 * @since Added in version 3.1. 154 * 155 * @ingroup native 156 */ 157 GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor); 158 159 /*! @brief Returns the `HWND` of the specified window. 160 * 161 * @return The `HWND` of the specified window, or `NULL` if an 162 * [error](@ref error_handling) occurred. 163 * 164 * @thread_safety This function may be called from any thread. Access is not 165 * synchronized. 166 * 167 * @since Added in version 3.0. 168 * 169 * @ingroup native 170 */ 171 GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); 172 #endif 173 174 #if defined(GLFW_EXPOSE_NATIVE_WGL) 175 /*! @brief Returns the `HGLRC` of the specified window. 176 * 177 * @return The `HGLRC` of the specified window, or `NULL` if an 178 * [error](@ref error_handling) occurred. 179 * 180 * @thread_safety This function may be called from any thread. Access is not 181 * synchronized. 182 * 183 * @since Added in version 3.0. 184 * 185 * @ingroup native 186 */ 187 GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window); 188 #endif 189 190 #if defined(GLFW_EXPOSE_NATIVE_COCOA) 191 /*! @brief Returns the `CGDirectDisplayID` of the specified monitor. 192 * 193 * @return The `CGDirectDisplayID` of the specified monitor, or 194 * `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred. 195 * 196 * @thread_safety This function may be called from any thread. Access is not 197 * synchronized. 198 * 199 * @since Added in version 3.1. 200 * 201 * @ingroup native 202 */ 203 GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor); 204 205 /*! @brief Returns the `NSWindow` of the specified window. 206 * 207 * @return The `NSWindow` of the specified window, or `nil` if an 208 * [error](@ref error_handling) occurred. 209 * 210 * @thread_safety This function may be called from any thread. Access is not 211 * synchronized. 212 * 213 * @since Added in version 3.0. 214 * 215 * @ingroup native 216 */ 217 GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); 218 #endif 219 220 #if defined(GLFW_EXPOSE_NATIVE_NSGL) 221 /*! @brief Returns the `NSOpenGLContext` of the specified window. 222 * 223 * @return The `NSOpenGLContext` of the specified window, or `nil` if an 224 * [error](@ref error_handling) occurred. 225 * 226 * @thread_safety This function may be called from any thread. Access is not 227 * synchronized. 228 * 229 * @since Added in version 3.0. 230 * 231 * @ingroup native 232 */ 233 GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); 234 #endif 235 236 #if defined(GLFW_EXPOSE_NATIVE_X11) 237 /*! @brief Returns the `Display` used by GLFW. 238 * 239 * @return The `Display` used by GLFW, or `NULL` if an 240 * [error](@ref error_handling) occurred. 241 * 242 * @thread_safety This function may be called from any thread. Access is not 243 * synchronized. 244 * 245 * @since Added in version 3.0. 246 * 247 * @ingroup native 248 */ 249 GLFWAPI Display* glfwGetX11Display(void); 250 251 /*! @brief Returns the `RRCrtc` of the specified monitor. 252 * 253 * @return The `RRCrtc` of the specified monitor, or `None` if an 254 * [error](@ref error_handling) occurred. 255 * 256 * @thread_safety This function may be called from any thread. Access is not 257 * synchronized. 258 * 259 * @since Added in version 3.1. 260 * 261 * @ingroup native 262 */ 263 GLFWAPI RRCrtc glfwGetX11Adapter(GLFWmonitor* monitor); 264 265 /*! @brief Returns the `RROutput` of the specified monitor. 266 * 267 * @return The `RROutput` of the specified monitor, or `None` if an 268 * [error](@ref error_handling) occurred. 269 * 270 * @thread_safety This function may be called from any thread. Access is not 271 * synchronized. 272 * 273 * @since Added in version 3.1. 274 * 275 * @ingroup native 276 */ 277 GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor); 278 279 /*! @brief Returns the `Window` of the specified window. 280 * 281 * @return The `Window` of the specified window, or `None` if an 282 * [error](@ref error_handling) occurred. 283 * 284 * @thread_safety This function may be called from any thread. Access is not 285 * synchronized. 286 * 287 * @since Added in version 3.0. 288 * 289 * @ingroup native 290 */ 291 GLFWAPI Window glfwGetX11Window(GLFWwindow* window); 292 293 /*! @brief Sets the current primary selection to the specified string. 294 * 295 * @param[in] string A UTF-8 encoded string. 296 * 297 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 298 * GLFW_PLATFORM_ERROR. 299 * 300 * @pointer_lifetime The specified string is copied before this function 301 * returns. 302 * 303 * @thread_safety This function must only be called from the main thread. 304 * 305 * @sa @ref clipboard 306 * @sa glfwGetX11SelectionString 307 * @sa glfwSetClipboardString 308 * 309 * @since Added in version 3.3. 310 * 311 * @ingroup native 312 */ 313 GLFWAPI void glfwSetX11SelectionString(const char* string); 314 315 /*! @brief Returns the contents of the current primary selection as a string. 316 * 317 * If the selection is empty or if its contents cannot be converted, `NULL` 318 * is returned and a @ref GLFW_FORMAT_UNAVAILABLE error is generated. 319 * 320 * @return The contents of the selection as a UTF-8 encoded string, or `NULL` 321 * if an [error](@ref error_handling) occurred. 322 * 323 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 324 * GLFW_PLATFORM_ERROR. 325 * 326 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 327 * should not free it yourself. It is valid until the next call to @ref 328 * glfwGetX11SelectionString or @ref glfwSetX11SelectionString, or until the 329 * library is terminated. 330 * 331 * @thread_safety This function must only be called from the main thread. 332 * 333 * @sa @ref clipboard 334 * @sa glfwSetX11SelectionString 335 * @sa glfwGetClipboardString 336 * 337 * @since Added in version 3.3. 338 * 339 * @ingroup native 340 */ 341 GLFWAPI const char* glfwGetX11SelectionString(void); 342 #endif 343 344 #if defined(GLFW_EXPOSE_NATIVE_GLX) 345 /*! @brief Returns the `GLXContext` of the specified window. 346 * 347 * @return The `GLXContext` of the specified window, or `NULL` if an 348 * [error](@ref error_handling) occurred. 349 * 350 * @thread_safety This function may be called from any thread. Access is not 351 * synchronized. 352 * 353 * @since Added in version 3.0. 354 * 355 * @ingroup native 356 */ 357 GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window); 358 359 /*! @brief Returns the `GLXWindow` of the specified window. 360 * 361 * @return The `GLXWindow` of the specified window, or `None` if an 362 * [error](@ref error_handling) occurred. 363 * 364 * @thread_safety This function may be called from any thread. Access is not 365 * synchronized. 366 * 367 * @since Added in version 3.2. 368 * 369 * @ingroup native 370 */ 371 GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* window); 372 #endif 373 374 #if defined(GLFW_EXPOSE_NATIVE_WAYLAND) 375 /*! @brief Returns the `struct wl_display*` used by GLFW. 376 * 377 * @return The `struct wl_display*` used by GLFW, or `NULL` if an 378 * [error](@ref error_handling) occurred. 379 * 380 * @thread_safety This function may be called from any thread. Access is not 381 * synchronized. 382 * 383 * @since Added in version 3.2. 384 * 385 * @ingroup native 386 */ 387 GLFWAPI struct wl_display* glfwGetWaylandDisplay(void); 388 389 /*! @brief Returns the `struct wl_output*` of the specified monitor. 390 * 391 * @return The `struct wl_output*` of the specified monitor, or `NULL` if an 392 * [error](@ref error_handling) occurred. 393 * 394 * @thread_safety This function may be called from any thread. Access is not 395 * synchronized. 396 * 397 * @since Added in version 3.2. 398 * 399 * @ingroup native 400 */ 401 GLFWAPI struct wl_output* glfwGetWaylandMonitor(GLFWmonitor* monitor); 402 403 /*! @brief Returns the main `struct wl_surface*` of the specified window. 404 * 405 * @return The main `struct wl_surface*` of the specified window, or `NULL` if 406 * an [error](@ref error_handling) occurred. 407 * 408 * @thread_safety This function may be called from any thread. Access is not 409 * synchronized. 410 * 411 * @since Added in version 3.2. 412 * 413 * @ingroup native 414 */ 415 GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* window); 416 #endif 417 418 #if defined(GLFW_EXPOSE_NATIVE_EGL) 419 /*! @brief Returns the `EGLDisplay` used by GLFW. 420 * 421 * @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an 422 * [error](@ref error_handling) occurred. 423 * 424 * @thread_safety This function may be called from any thread. Access is not 425 * synchronized. 426 * 427 * @since Added in version 3.0. 428 * 429 * @ingroup native 430 */ 431 GLFWAPI EGLDisplay glfwGetEGLDisplay(void); 432 433 /*! @brief Returns the `EGLContext` of the specified window. 434 * 435 * @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an 436 * [error](@ref error_handling) occurred. 437 * 438 * @thread_safety This function may be called from any thread. Access is not 439 * synchronized. 440 * 441 * @since Added in version 3.0. 442 * 443 * @ingroup native 444 */ 445 GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window); 446 447 /*! @brief Returns the `EGLSurface` of the specified window. 448 * 449 * @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an 450 * [error](@ref error_handling) occurred. 451 * 452 * @thread_safety This function may be called from any thread. Access is not 453 * synchronized. 454 * 455 * @since Added in version 3.0. 456 * 457 * @ingroup native 458 */ 459 GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window); 460 #endif 461 462 #if defined(GLFW_EXPOSE_NATIVE_OSMESA) 463 /*! @brief Retrieves the color buffer associated with the specified window. 464 * 465 * @param[in] window The window whose color buffer to retrieve. 466 * @param[out] width Where to store the width of the color buffer, or `NULL`. 467 * @param[out] height Where to store the height of the color buffer, or `NULL`. 468 * @param[out] format Where to store the OSMesa pixel format of the color 469 * buffer, or `NULL`. 470 * @param[out] buffer Where to store the address of the color buffer, or 471 * `NULL`. 472 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 473 * [error](@ref error_handling) occurred. 474 * 475 * @thread_safety This function may be called from any thread. Access is not 476 * synchronized. 477 * 478 * @since Added in version 3.3. 479 * 480 * @ingroup native 481 */ 482 GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height, int* format, void** buffer); 483 484 /*! @brief Retrieves the depth buffer associated with the specified window. 485 * 486 * @param[in] window The window whose depth buffer to retrieve. 487 * @param[out] width Where to store the width of the depth buffer, or `NULL`. 488 * @param[out] height Where to store the height of the depth buffer, or `NULL`. 489 * @param[out] bytesPerValue Where to store the number of bytes per depth 490 * buffer element, or `NULL`. 491 * @param[out] buffer Where to store the address of the depth buffer, or 492 * `NULL`. 493 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 494 * [error](@ref error_handling) occurred. 495 * 496 * @thread_safety This function may be called from any thread. Access is not 497 * synchronized. 498 * 499 * @since Added in version 3.3. 500 * 501 * @ingroup native 502 */ 503 GLFWAPI int glfwGetOSMesaDepthBuffer(GLFWwindow* window, int* width, int* height, int* bytesPerValue, void** buffer); 504 505 /*! @brief Returns the `OSMesaContext` of the specified window. 506 * 507 * @return The `OSMesaContext` of the specified window, or `NULL` if an 508 * [error](@ref error_handling) occurred. 509 * 510 * @thread_safety This function may be called from any thread. Access is not 511 * synchronized. 512 * 513 * @since Added in version 3.3. 514 * 515 * @ingroup native 516 */ 517 GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window); 518 #endif 519 520 #ifdef __cplusplus 521 } 522 #endif 523 524 #endif /* _glfw3_native_h_ */ 525 526