glfw3native.h (16689B)
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_ */