glfw3native.h (20034B)
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-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 * If you do not want the platform-specific headers to be included, define 79 * `GLFW_NATIVE_INCLUDE_NONE` before including the @ref glfw3native.h header. 80 * 81 * @code 82 * #define GLFW_EXPOSE_NATIVE_WIN32 83 * #define GLFW_EXPOSE_NATIVE_WGL 84 * #define GLFW_NATIVE_INCLUDE_NONE 85 * #include <GLFW/glfw3native.h> 86 * @endcode 87 */ 88 89 90 /************************************************************************* 91 * System headers and types 92 *************************************************************************/ 93 94 #if !defined(GLFW_NATIVE_INCLUDE_NONE) 95 96 #if defined(GLFW_EXPOSE_NATIVE_WIN32) || defined(GLFW_EXPOSE_NATIVE_WGL) 97 /* This is a workaround for the fact that glfw3.h needs to export APIENTRY (for 98 * example to allow applications to correctly declare a GL_KHR_debug callback) 99 * but windows.h assumes no one will define APIENTRY before it does 100 */ 101 #if defined(GLFW_APIENTRY_DEFINED) 102 #undef APIENTRY 103 #undef GLFW_APIENTRY_DEFINED 104 #endif 105 #include <windows.h> 106 #elif defined(GLFW_EXPOSE_NATIVE_COCOA) || defined(GLFW_EXPOSE_NATIVE_NSGL) 107 #if defined(__OBJC__) 108 #import <Cocoa/Cocoa.h> 109 #else 110 #include <ApplicationServices/ApplicationServices.h> 111 #include <objc/objc.h> 112 #endif 113 #elif defined(GLFW_EXPOSE_NATIVE_X11) || defined(GLFW_EXPOSE_NATIVE_GLX) 114 #include <X11/Xlib.h> 115 #include <X11/extensions/Xrandr.h> 116 #elif defined(GLFW_EXPOSE_NATIVE_WAYLAND) 117 #include <wayland-client.h> 118 #endif 119 120 #if defined(GLFW_EXPOSE_NATIVE_WGL) 121 /* WGL is declared by windows.h */ 122 #endif 123 #if defined(GLFW_EXPOSE_NATIVE_NSGL) 124 /* NSGL is declared by Cocoa.h */ 125 #endif 126 #if defined(GLFW_EXPOSE_NATIVE_GLX) 127 /* This is a workaround for the fact that glfw3.h defines GLAPIENTRY because by 128 * default it also acts as an OpenGL header 129 * However, glx.h will include gl.h, which will define it unconditionally 130 */ 131 #if defined(GLFW_GLAPIENTRY_DEFINED) 132 #undef GLAPIENTRY 133 #undef GLFW_GLAPIENTRY_DEFINED 134 #endif 135 #include <GL/glx.h> 136 #endif 137 #if defined(GLFW_EXPOSE_NATIVE_EGL) 138 #include <EGL/egl.h> 139 #endif 140 #if defined(GLFW_EXPOSE_NATIVE_OSMESA) 141 /* This is a workaround for the fact that glfw3.h defines GLAPIENTRY because by 142 * default it also acts as an OpenGL header 143 * However, osmesa.h will include gl.h, which will define it unconditionally 144 */ 145 #if defined(GLFW_GLAPIENTRY_DEFINED) 146 #undef GLAPIENTRY 147 #undef GLFW_GLAPIENTRY_DEFINED 148 #endif 149 #include <GL/osmesa.h> 150 #endif 151 152 #endif /*GLFW_NATIVE_INCLUDE_NONE*/ 153 154 155 /************************************************************************* 156 * Functions 157 *************************************************************************/ 158 159 #if defined(GLFW_EXPOSE_NATIVE_WIN32) 160 /*! @brief Returns the adapter device name of the specified monitor. 161 * 162 * @return The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`) 163 * of the specified monitor, or `NULL` if an [error](@ref error_handling) 164 * occurred. 165 * 166 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 167 * 168 * @thread_safety This function may be called from any thread. Access is not 169 * synchronized. 170 * 171 * @since Added in version 3.1. 172 * 173 * @ingroup native 174 */ 175 GLFWAPI const char* glfwGetWin32Adapter(GLFWmonitor* monitor); 176 177 /*! @brief Returns the display device name of the specified monitor. 178 * 179 * @return The UTF-8 encoded display device name (for example 180 * `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an 181 * [error](@ref error_handling) occurred. 182 * 183 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 184 * 185 * @thread_safety This function may be called from any thread. Access is not 186 * synchronized. 187 * 188 * @since Added in version 3.1. 189 * 190 * @ingroup native 191 */ 192 GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor); 193 194 /*! @brief Returns the `HWND` of the specified window. 195 * 196 * @return The `HWND` of the specified window, or `NULL` if an 197 * [error](@ref error_handling) occurred. 198 * 199 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 200 * 201 * @remark The `HDC` associated with the window can be queried with the 202 * [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc) 203 * function. 204 * @code 205 * HDC dc = GetDC(glfwGetWin32Window(window)); 206 * @endcode 207 * This DC is private and does not need to be released. 208 * 209 * @thread_safety This function may be called from any thread. Access is not 210 * synchronized. 211 * 212 * @since Added in version 3.0. 213 * 214 * @ingroup native 215 */ 216 GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); 217 #endif 218 219 #if defined(GLFW_EXPOSE_NATIVE_WGL) 220 /*! @brief Returns the `HGLRC` of the specified window. 221 * 222 * @return The `HGLRC` of the specified window, or `NULL` if an 223 * [error](@ref error_handling) occurred. 224 * 225 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 226 * GLFW_NOT_INITIALIZED. 227 * 228 * @remark The `HDC` associated with the window can be queried with the 229 * [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc) 230 * function. 231 * @code 232 * HDC dc = GetDC(glfwGetWin32Window(window)); 233 * @endcode 234 * This DC is private and does not need to be released. 235 * 236 * @thread_safety This function may be called from any thread. Access is not 237 * synchronized. 238 * 239 * @since Added in version 3.0. 240 * 241 * @ingroup native 242 */ 243 GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window); 244 #endif 245 246 #if defined(GLFW_EXPOSE_NATIVE_COCOA) 247 /*! @brief Returns the `CGDirectDisplayID` of the specified monitor. 248 * 249 * @return The `CGDirectDisplayID` of the specified monitor, or 250 * `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred. 251 * 252 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 253 * 254 * @thread_safety This function may be called from any thread. Access is not 255 * synchronized. 256 * 257 * @since Added in version 3.1. 258 * 259 * @ingroup native 260 */ 261 GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor); 262 263 /*! @brief Returns the `NSWindow` of the specified window. 264 * 265 * @return The `NSWindow` of the specified window, or `nil` if an 266 * [error](@ref error_handling) occurred. 267 * 268 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 269 * 270 * @thread_safety This function may be called from any thread. Access is not 271 * synchronized. 272 * 273 * @since Added in version 3.0. 274 * 275 * @ingroup native 276 */ 277 GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); 278 #endif 279 280 #if defined(GLFW_EXPOSE_NATIVE_NSGL) 281 /*! @brief Returns the `NSOpenGLContext` of the specified window. 282 * 283 * @return The `NSOpenGLContext` of the specified window, or `nil` if an 284 * [error](@ref error_handling) occurred. 285 * 286 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 287 * GLFW_NOT_INITIALIZED. 288 * 289 * @thread_safety This function may be called from any thread. Access is not 290 * synchronized. 291 * 292 * @since Added in version 3.0. 293 * 294 * @ingroup native 295 */ 296 GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); 297 #endif 298 299 #if defined(GLFW_EXPOSE_NATIVE_X11) 300 /*! @brief Returns the `Display` used by GLFW. 301 * 302 * @return The `Display` used by GLFW, or `NULL` if an 303 * [error](@ref error_handling) occurred. 304 * 305 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 306 * 307 * @thread_safety This function may be called from any thread. Access is not 308 * synchronized. 309 * 310 * @since Added in version 3.0. 311 * 312 * @ingroup native 313 */ 314 GLFWAPI Display* glfwGetX11Display(void); 315 316 /*! @brief Returns the `RRCrtc` of the specified monitor. 317 * 318 * @return The `RRCrtc` of the specified monitor, or `None` if an 319 * [error](@ref error_handling) occurred. 320 * 321 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 322 * 323 * @thread_safety This function may be called from any thread. Access is not 324 * synchronized. 325 * 326 * @since Added in version 3.1. 327 * 328 * @ingroup native 329 */ 330 GLFWAPI RRCrtc glfwGetX11Adapter(GLFWmonitor* monitor); 331 332 /*! @brief Returns the `RROutput` of the specified monitor. 333 * 334 * @return The `RROutput` of the specified monitor, or `None` if an 335 * [error](@ref error_handling) occurred. 336 * 337 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 338 * 339 * @thread_safety This function may be called from any thread. Access is not 340 * synchronized. 341 * 342 * @since Added in version 3.1. 343 * 344 * @ingroup native 345 */ 346 GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor); 347 348 /*! @brief Returns the `Window` of the specified window. 349 * 350 * @return The `Window` of the specified window, or `None` if an 351 * [error](@ref error_handling) occurred. 352 * 353 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 354 * 355 * @thread_safety This function may be called from any thread. Access is not 356 * synchronized. 357 * 358 * @since Added in version 3.0. 359 * 360 * @ingroup native 361 */ 362 GLFWAPI Window glfwGetX11Window(GLFWwindow* window); 363 364 /*! @brief Sets the current primary selection to the specified string. 365 * 366 * @param[in] string A UTF-8 encoded string. 367 * 368 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 369 * GLFW_PLATFORM_ERROR. 370 * 371 * @pointer_lifetime The specified string is copied before this function 372 * returns. 373 * 374 * @thread_safety This function must only be called from the main thread. 375 * 376 * @sa @ref clipboard 377 * @sa glfwGetX11SelectionString 378 * @sa glfwSetClipboardString 379 * 380 * @since Added in version 3.3. 381 * 382 * @ingroup native 383 */ 384 GLFWAPI void glfwSetX11SelectionString(const char* string); 385 386 /*! @brief Returns the contents of the current primary selection as a string. 387 * 388 * If the selection is empty or if its contents cannot be converted, `NULL` 389 * is returned and a @ref GLFW_FORMAT_UNAVAILABLE error is generated. 390 * 391 * @return The contents of the selection as a UTF-8 encoded string, or `NULL` 392 * if an [error](@ref error_handling) occurred. 393 * 394 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 395 * GLFW_PLATFORM_ERROR. 396 * 397 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 398 * should not free it yourself. It is valid until the next call to @ref 399 * glfwGetX11SelectionString or @ref glfwSetX11SelectionString, or until the 400 * library is terminated. 401 * 402 * @thread_safety This function must only be called from the main thread. 403 * 404 * @sa @ref clipboard 405 * @sa glfwSetX11SelectionString 406 * @sa glfwGetClipboardString 407 * 408 * @since Added in version 3.3. 409 * 410 * @ingroup native 411 */ 412 GLFWAPI const char* glfwGetX11SelectionString(void); 413 #endif 414 415 #if defined(GLFW_EXPOSE_NATIVE_GLX) 416 /*! @brief Returns the `GLXContext` of the specified window. 417 * 418 * @return The `GLXContext` of the specified window, or `NULL` if an 419 * [error](@ref error_handling) occurred. 420 * 421 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 422 * GLFW_NOT_INITIALIZED. 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 GLXContext glfwGetGLXContext(GLFWwindow* window); 432 433 /*! @brief Returns the `GLXWindow` of the specified window. 434 * 435 * @return The `GLXWindow` of the specified window, or `None` if an 436 * [error](@ref error_handling) occurred. 437 * 438 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 439 * GLFW_NOT_INITIALIZED. 440 * 441 * @thread_safety This function may be called from any thread. Access is not 442 * synchronized. 443 * 444 * @since Added in version 3.2. 445 * 446 * @ingroup native 447 */ 448 GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* window); 449 #endif 450 451 #if defined(GLFW_EXPOSE_NATIVE_WAYLAND) 452 /*! @brief Returns the `struct wl_display*` used by GLFW. 453 * 454 * @return The `struct wl_display*` used by GLFW, or `NULL` if an 455 * [error](@ref error_handling) occurred. 456 * 457 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 458 * 459 * @thread_safety This function may be called from any thread. Access is not 460 * synchronized. 461 * 462 * @since Added in version 3.2. 463 * 464 * @ingroup native 465 */ 466 GLFWAPI struct wl_display* glfwGetWaylandDisplay(void); 467 468 /*! @brief Returns the `struct wl_output*` of the specified monitor. 469 * 470 * @return The `struct wl_output*` of the specified monitor, or `NULL` if an 471 * [error](@ref error_handling) occurred. 472 * 473 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 474 * 475 * @thread_safety This function may be called from any thread. Access is not 476 * synchronized. 477 * 478 * @since Added in version 3.2. 479 * 480 * @ingroup native 481 */ 482 GLFWAPI struct wl_output* glfwGetWaylandMonitor(GLFWmonitor* monitor); 483 484 /*! @brief Returns the main `struct wl_surface*` of the specified window. 485 * 486 * @return The main `struct wl_surface*` of the specified window, or `NULL` if 487 * an [error](@ref error_handling) occurred. 488 * 489 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 490 * 491 * @thread_safety This function may be called from any thread. Access is not 492 * synchronized. 493 * 494 * @since Added in version 3.2. 495 * 496 * @ingroup native 497 */ 498 GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* window); 499 #endif 500 501 #if defined(GLFW_EXPOSE_NATIVE_EGL) 502 /*! @brief Returns the `EGLDisplay` used by GLFW. 503 * 504 * @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an 505 * [error](@ref error_handling) occurred. 506 * 507 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 508 * 509 * @remark Because EGL is initialized on demand, this function will return 510 * `EGL_NO_DISPLAY` until the first context has been created via EGL. 511 * 512 * @thread_safety This function may be called from any thread. Access is not 513 * synchronized. 514 * 515 * @since Added in version 3.0. 516 * 517 * @ingroup native 518 */ 519 GLFWAPI EGLDisplay glfwGetEGLDisplay(void); 520 521 /*! @brief Returns the `EGLContext` of the specified window. 522 * 523 * @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an 524 * [error](@ref error_handling) occurred. 525 * 526 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 527 * GLFW_NOT_INITIALIZED. 528 * 529 * @thread_safety This function may be called from any thread. Access is not 530 * synchronized. 531 * 532 * @since Added in version 3.0. 533 * 534 * @ingroup native 535 */ 536 GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window); 537 538 /*! @brief Returns the `EGLSurface` of the specified window. 539 * 540 * @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an 541 * [error](@ref error_handling) occurred. 542 * 543 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 544 * GLFW_NOT_INITIALIZED. 545 * 546 * @thread_safety This function may be called from any thread. Access is not 547 * synchronized. 548 * 549 * @since Added in version 3.0. 550 * 551 * @ingroup native 552 */ 553 GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window); 554 #endif 555 556 #if defined(GLFW_EXPOSE_NATIVE_OSMESA) 557 /*! @brief Retrieves the color buffer associated with the specified window. 558 * 559 * @param[in] window The window whose color buffer to retrieve. 560 * @param[out] width Where to store the width of the color buffer, or `NULL`. 561 * @param[out] height Where to store the height of the color buffer, or `NULL`. 562 * @param[out] format Where to store the OSMesa pixel format of the color 563 * buffer, or `NULL`. 564 * @param[out] buffer Where to store the address of the color buffer, or 565 * `NULL`. 566 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 567 * [error](@ref error_handling) occurred. 568 * 569 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 570 * GLFW_NOT_INITIALIZED. 571 * 572 * @thread_safety This function may be called from any thread. Access is not 573 * synchronized. 574 * 575 * @since Added in version 3.3. 576 * 577 * @ingroup native 578 */ 579 GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height, int* format, void** buffer); 580 581 /*! @brief Retrieves the depth buffer associated with the specified window. 582 * 583 * @param[in] window The window whose depth buffer to retrieve. 584 * @param[out] width Where to store the width of the depth buffer, or `NULL`. 585 * @param[out] height Where to store the height of the depth buffer, or `NULL`. 586 * @param[out] bytesPerValue Where to store the number of bytes per depth 587 * buffer element, or `NULL`. 588 * @param[out] buffer Where to store the address of the depth buffer, or 589 * `NULL`. 590 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 591 * [error](@ref error_handling) occurred. 592 * 593 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 594 * GLFW_NOT_INITIALIZED. 595 * 596 * @thread_safety This function may be called from any thread. Access is not 597 * synchronized. 598 * 599 * @since Added in version 3.3. 600 * 601 * @ingroup native 602 */ 603 GLFWAPI int glfwGetOSMesaDepthBuffer(GLFWwindow* window, int* width, int* height, int* bytesPerValue, void** buffer); 604 605 /*! @brief Returns the `OSMesaContext` of the specified window. 606 * 607 * @return The `OSMesaContext` of the specified window, or `NULL` if an 608 * [error](@ref error_handling) occurred. 609 * 610 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 611 * GLFW_NOT_INITIALIZED. 612 * 613 * @thread_safety This function may be called from any thread. Access is not 614 * synchronized. 615 * 616 * @since Added in version 3.3. 617 * 618 * @ingroup native 619 */ 620 GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window); 621 #endif 622 623 #ifdef __cplusplus 624 } 625 #endif 626 627 #endif /* _glfw3_native_h_ */ 628