git.sesse.net Git - pistorm/blob - raylib_pi4_test/external/glfw/include/GLFW/glfw3native.h

   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