glfw3native.h (18803B)
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 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_KHR_debug callback) 87 // 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) || defined(GLFW_EXPOSE_NATIVE_NSGL) 94 #if defined(__OBJC__) 95 #import <Cocoa/Cocoa.h> 96 #else 97 #include <ApplicationServices/ApplicationServices.h> 98 typedef void* id; 99 #endif 100 #elif defined(GLFW_EXPOSE_NATIVE_X11) || defined(GLFW_EXPOSE_NATIVE_GLX) 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 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 136 * 137 * @thread_safety This function may be called from any thread. Access is not 138 * synchronized. 139 * 140 * @since Added in version 3.1. 141 * 142 * @ingroup native 143 */ 144 GLFWAPI const char* glfwGetWin32Adapter(GLFWmonitor* monitor); 145 146 /*! @brief Returns the display device name of the specified monitor. 147 * 148 * @return The UTF-8 encoded display device name (for example 149 * `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an 150 * [error](@ref error_handling) occurred. 151 * 152 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 153 * 154 * @thread_safety This function may be called from any thread. Access is not 155 * synchronized. 156 * 157 * @since Added in version 3.1. 158 * 159 * @ingroup native 160 */ 161 GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor); 162 163 /*! @brief Returns the `HWND` of the specified window. 164 * 165 * @return The `HWND` of the specified window, or `NULL` if an 166 * [error](@ref error_handling) occurred. 167 * 168 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 169 * 170 * @remark The `HDC` associated with the window can be queried with the 171 * [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc) 172 * function. 173 * @code 174 * HDC dc = GetDC(glfwGetWin32Window(window)); 175 * @endcode 176 * This DC is private and does not need to be released. 177 * 178 * @thread_safety This function may be called from any thread. Access is not 179 * synchronized. 180 * 181 * @since Added in version 3.0. 182 * 183 * @ingroup native 184 */ 185 GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window); 186 #endif 187 188 #if defined(GLFW_EXPOSE_NATIVE_WGL) 189 /*! @brief Returns the `HGLRC` of the specified window. 190 * 191 * @return The `HGLRC` of the specified window, or `NULL` if an 192 * [error](@ref error_handling) occurred. 193 * 194 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 195 * GLFW_NOT_INITIALIZED. 196 * 197 * @remark The `HDC` associated with the window can be queried with the 198 * [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc) 199 * function. 200 * @code 201 * HDC dc = GetDC(glfwGetWin32Window(window)); 202 * @endcode 203 * This DC is private and does not need to be released. 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 HGLRC glfwGetWGLContext(GLFWwindow* window); 213 #endif 214 215 #if defined(GLFW_EXPOSE_NATIVE_COCOA) 216 /*! @brief Returns the `CGDirectDisplayID` of the specified monitor. 217 * 218 * @return The `CGDirectDisplayID` of the specified monitor, or 219 * `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred. 220 * 221 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 222 * 223 * @thread_safety This function may be called from any thread. Access is not 224 * synchronized. 225 * 226 * @since Added in version 3.1. 227 * 228 * @ingroup native 229 */ 230 GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor); 231 232 /*! @brief Returns the `NSWindow` of the specified window. 233 * 234 * @return The `NSWindow` of the specified window, or `nil` if an 235 * [error](@ref error_handling) occurred. 236 * 237 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 238 * 239 * @thread_safety This function may be called from any thread. Access is not 240 * synchronized. 241 * 242 * @since Added in version 3.0. 243 * 244 * @ingroup native 245 */ 246 GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window); 247 #endif 248 249 #if defined(GLFW_EXPOSE_NATIVE_NSGL) 250 /*! @brief Returns the `NSOpenGLContext` of the specified window. 251 * 252 * @return The `NSOpenGLContext` of the specified window, or `nil` if an 253 * [error](@ref error_handling) occurred. 254 * 255 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 256 * GLFW_NOT_INITIALIZED. 257 * 258 * @thread_safety This function may be called from any thread. Access is not 259 * synchronized. 260 * 261 * @since Added in version 3.0. 262 * 263 * @ingroup native 264 */ 265 GLFWAPI id glfwGetNSGLContext(GLFWwindow* window); 266 #endif 267 268 #if defined(GLFW_EXPOSE_NATIVE_X11) 269 /*! @brief Returns the `Display` used by GLFW. 270 * 271 * @return The `Display` used by GLFW, or `NULL` if an 272 * [error](@ref error_handling) occurred. 273 * 274 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 275 * 276 * @thread_safety This function may be called from any thread. Access is not 277 * synchronized. 278 * 279 * @since Added in version 3.0. 280 * 281 * @ingroup native 282 */ 283 GLFWAPI Display* glfwGetX11Display(void); 284 285 /*! @brief Returns the `RRCrtc` of the specified monitor. 286 * 287 * @return The `RRCrtc` of the specified monitor, or `None` if an 288 * [error](@ref error_handling) occurred. 289 * 290 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 291 * 292 * @thread_safety This function may be called from any thread. Access is not 293 * synchronized. 294 * 295 * @since Added in version 3.1. 296 * 297 * @ingroup native 298 */ 299 GLFWAPI RRCrtc glfwGetX11Adapter(GLFWmonitor* monitor); 300 301 /*! @brief Returns the `RROutput` of the specified monitor. 302 * 303 * @return The `RROutput` of the specified monitor, or `None` if an 304 * [error](@ref error_handling) occurred. 305 * 306 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 307 * 308 * @thread_safety This function may be called from any thread. Access is not 309 * synchronized. 310 * 311 * @since Added in version 3.1. 312 * 313 * @ingroup native 314 */ 315 GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor); 316 317 /*! @brief Returns the `Window` of the specified window. 318 * 319 * @return The `Window` of the specified window, or `None` if an 320 * [error](@ref error_handling) occurred. 321 * 322 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 323 * 324 * @thread_safety This function may be called from any thread. Access is not 325 * synchronized. 326 * 327 * @since Added in version 3.0. 328 * 329 * @ingroup native 330 */ 331 GLFWAPI Window glfwGetX11Window(GLFWwindow* window); 332 333 /*! @brief Sets the current primary selection to the specified string. 334 * 335 * @param[in] string A UTF-8 encoded string. 336 * 337 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 338 * GLFW_PLATFORM_ERROR. 339 * 340 * @pointer_lifetime The specified string is copied before this function 341 * returns. 342 * 343 * @thread_safety This function must only be called from the main thread. 344 * 345 * @sa @ref clipboard 346 * @sa glfwGetX11SelectionString 347 * @sa glfwSetClipboardString 348 * 349 * @since Added in version 3.3. 350 * 351 * @ingroup native 352 */ 353 GLFWAPI void glfwSetX11SelectionString(const char* string); 354 355 /*! @brief Returns the contents of the current primary selection as a string. 356 * 357 * If the selection is empty or if its contents cannot be converted, `NULL` 358 * is returned and a @ref GLFW_FORMAT_UNAVAILABLE error is generated. 359 * 360 * @return The contents of the selection as a UTF-8 encoded string, or `NULL` 361 * if an [error](@ref error_handling) occurred. 362 * 363 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 364 * GLFW_PLATFORM_ERROR. 365 * 366 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 367 * should not free it yourself. It is valid until the next call to @ref 368 * glfwGetX11SelectionString or @ref glfwSetX11SelectionString, or until the 369 * library is terminated. 370 * 371 * @thread_safety This function must only be called from the main thread. 372 * 373 * @sa @ref clipboard 374 * @sa glfwSetX11SelectionString 375 * @sa glfwGetClipboardString 376 * 377 * @since Added in version 3.3. 378 * 379 * @ingroup native 380 */ 381 GLFWAPI const char* glfwGetX11SelectionString(void); 382 #endif 383 384 #if defined(GLFW_EXPOSE_NATIVE_GLX) 385 /*! @brief Returns the `GLXContext` of the specified window. 386 * 387 * @return The `GLXContext` of the specified window, or `NULL` if an 388 * [error](@ref error_handling) occurred. 389 * 390 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 391 * GLFW_NOT_INITIALIZED. 392 * 393 * @thread_safety This function may be called from any thread. Access is not 394 * synchronized. 395 * 396 * @since Added in version 3.0. 397 * 398 * @ingroup native 399 */ 400 GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window); 401 402 /*! @brief Returns the `GLXWindow` of the specified window. 403 * 404 * @return The `GLXWindow` of the specified window, or `None` if an 405 * [error](@ref error_handling) occurred. 406 * 407 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 408 * GLFW_NOT_INITIALIZED. 409 * 410 * @thread_safety This function may be called from any thread. Access is not 411 * synchronized. 412 * 413 * @since Added in version 3.2. 414 * 415 * @ingroup native 416 */ 417 GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* window); 418 #endif 419 420 #if defined(GLFW_EXPOSE_NATIVE_WAYLAND) 421 /*! @brief Returns the `struct wl_display*` used by GLFW. 422 * 423 * @return The `struct wl_display*` used by GLFW, or `NULL` if an 424 * [error](@ref error_handling) occurred. 425 * 426 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 427 * 428 * @thread_safety This function may be called from any thread. Access is not 429 * synchronized. 430 * 431 * @since Added in version 3.2. 432 * 433 * @ingroup native 434 */ 435 GLFWAPI struct wl_display* glfwGetWaylandDisplay(void); 436 437 /*! @brief Returns the `struct wl_output*` of the specified monitor. 438 * 439 * @return The `struct wl_output*` of the specified monitor, or `NULL` if an 440 * [error](@ref error_handling) occurred. 441 * 442 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 443 * 444 * @thread_safety This function may be called from any thread. Access is not 445 * synchronized. 446 * 447 * @since Added in version 3.2. 448 * 449 * @ingroup native 450 */ 451 GLFWAPI struct wl_output* glfwGetWaylandMonitor(GLFWmonitor* monitor); 452 453 /*! @brief Returns the main `struct wl_surface*` of the specified window. 454 * 455 * @return The main `struct wl_surface*` of the specified window, or `NULL` if 456 * an [error](@ref error_handling) occurred. 457 * 458 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 459 * 460 * @thread_safety This function may be called from any thread. Access is not 461 * synchronized. 462 * 463 * @since Added in version 3.2. 464 * 465 * @ingroup native 466 */ 467 GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* window); 468 #endif 469 470 #if defined(GLFW_EXPOSE_NATIVE_EGL) 471 /*! @brief Returns the `EGLDisplay` used by GLFW. 472 * 473 * @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an 474 * [error](@ref error_handling) occurred. 475 * 476 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 477 * 478 * @thread_safety This function may be called from any thread. Access is not 479 * synchronized. 480 * 481 * @since Added in version 3.0. 482 * 483 * @ingroup native 484 */ 485 GLFWAPI EGLDisplay glfwGetEGLDisplay(void); 486 487 /*! @brief Returns the `EGLContext` of the specified window. 488 * 489 * @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an 490 * [error](@ref error_handling) occurred. 491 * 492 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 493 * GLFW_NOT_INITIALIZED. 494 * 495 * @thread_safety This function may be called from any thread. Access is not 496 * synchronized. 497 * 498 * @since Added in version 3.0. 499 * 500 * @ingroup native 501 */ 502 GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window); 503 504 /*! @brief Returns the `EGLSurface` of the specified window. 505 * 506 * @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an 507 * [error](@ref error_handling) occurred. 508 * 509 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 510 * GLFW_NOT_INITIALIZED. 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 EGLSurface glfwGetEGLSurface(GLFWwindow* window); 520 #endif 521 522 #if defined(GLFW_EXPOSE_NATIVE_OSMESA) 523 /*! @brief Retrieves the color buffer associated with the specified window. 524 * 525 * @param[in] window The window whose color buffer to retrieve. 526 * @param[out] width Where to store the width of the color buffer, or `NULL`. 527 * @param[out] height Where to store the height of the color buffer, or `NULL`. 528 * @param[out] format Where to store the OSMesa pixel format of the color 529 * buffer, or `NULL`. 530 * @param[out] buffer Where to store the address of the color buffer, or 531 * `NULL`. 532 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 533 * [error](@ref error_handling) occurred. 534 * 535 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 536 * GLFW_NOT_INITIALIZED. 537 * 538 * @thread_safety This function may be called from any thread. Access is not 539 * synchronized. 540 * 541 * @since Added in version 3.3. 542 * 543 * @ingroup native 544 */ 545 GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height, int* format, void** buffer); 546 547 /*! @brief Retrieves the depth buffer associated with the specified window. 548 * 549 * @param[in] window The window whose depth buffer to retrieve. 550 * @param[out] width Where to store the width of the depth buffer, or `NULL`. 551 * @param[out] height Where to store the height of the depth buffer, or `NULL`. 552 * @param[out] bytesPerValue Where to store the number of bytes per depth 553 * buffer element, or `NULL`. 554 * @param[out] buffer Where to store the address of the depth buffer, or 555 * `NULL`. 556 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 557 * [error](@ref error_handling) occurred. 558 * 559 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 560 * GLFW_NOT_INITIALIZED. 561 * 562 * @thread_safety This function may be called from any thread. Access is not 563 * synchronized. 564 * 565 * @since Added in version 3.3. 566 * 567 * @ingroup native 568 */ 569 GLFWAPI int glfwGetOSMesaDepthBuffer(GLFWwindow* window, int* width, int* height, int* bytesPerValue, void** buffer); 570 571 /*! @brief Returns the `OSMesaContext` of the specified window. 572 * 573 * @return The `OSMesaContext` of the specified window, or `NULL` if an 574 * [error](@ref error_handling) occurred. 575 * 576 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref 577 * GLFW_NOT_INITIALIZED. 578 * 579 * @thread_safety This function may be called from any thread. Access is not 580 * synchronized. 581 * 582 * @since Added in version 3.3. 583 * 584 * @ingroup native 585 */ 586 GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window); 587 #endif 588 589 #ifdef __cplusplus 590 } 591 #endif 592 593 #endif /* _glfw3_native_h_ */ 594