medfall

A super great game engine
Log | Files | Refs

glfw3native.h (17563B)


      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  *  * `GLFW_EXPOSE_NATIVE_MIR`
     66  *
     67  *  The available context API macros are:
     68  *  * `GLFW_EXPOSE_NATIVE_WGL`
     69  *  * `GLFW_EXPOSE_NATIVE_NSGL`
     70  *  * `GLFW_EXPOSE_NATIVE_GLX`
     71  *  * `GLFW_EXPOSE_NATIVE_EGL`
     72  *  * `GLFW_EXPOSE_NATIVE_OSMESA`
     73  *
     74  *  These macros select which of the native access functions that are declared
     75  *  and which platform-specific headers to include.  It is then up your (by
     76  *  definition platform-specific) code to handle which of these should be
     77  *  defined.
     78  */
     79 
     80 
     81 /*************************************************************************
     82  * System headers and types
     83  *************************************************************************/
     84 
     85 #if defined(GLFW_EXPOSE_NATIVE_WIN32)
     86  // This is a workaround for the fact that glfw3.h needs to export APIENTRY (for
     87  // example to allow applications to correctly declare a GL_ARB_debug_output
     88  // callback) but windows.h assumes no one will define APIENTRY before it does
     89  #undef APIENTRY
     90  #include <windows.h>
     91 #elif defined(GLFW_EXPOSE_NATIVE_COCOA)
     92  #include <ApplicationServices/ApplicationServices.h>
     93  #if defined(__OBJC__)
     94   #import <Cocoa/Cocoa.h>
     95  #else
     96   typedef void* id;
     97  #endif
     98 #elif defined(GLFW_EXPOSE_NATIVE_X11)
     99  #include <X11/Xlib.h>
    100  #include <X11/extensions/Xrandr.h>
    101 #elif defined(GLFW_EXPOSE_NATIVE_WAYLAND)
    102  #include <wayland-client.h>
    103 #elif defined(GLFW_EXPOSE_NATIVE_MIR)
    104  #include <mir_toolkit/mir_client_library.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_MIR)
    419 /*! @brief Returns the `MirConnection*` used by GLFW.
    420  *
    421  *  @return The `MirConnection*` used by GLFW, or `NULL` 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.2.
    428  *
    429  *  @ingroup native
    430  */
    431 GLFWAPI MirConnection* glfwGetMirDisplay(void);
    432 
    433 /*! @brief Returns the Mir output ID of the specified monitor.
    434  *
    435  *  @return The Mir output ID of the specified monitor, or zero 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.2.
    442  *
    443  *  @ingroup native
    444  */
    445 GLFWAPI int glfwGetMirMonitor(GLFWmonitor* monitor);
    446 
    447 /*! @brief Returns the `MirWindow*` of the specified window.
    448  *
    449  *  @return The `MirWindow*` of the specified window, or `NULL` 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.2.
    456  *
    457  *  @ingroup native
    458  */
    459 GLFWAPI MirWindow* glfwGetMirWindow(GLFWwindow* window);
    460 #endif
    461 
    462 #if defined(GLFW_EXPOSE_NATIVE_EGL)
    463 /*! @brief Returns the `EGLDisplay` used by GLFW.
    464  *
    465  *  @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an
    466  *  [error](@ref error_handling) occurred.
    467  *
    468  *  @thread_safety This function may be called from any thread.  Access is not
    469  *  synchronized.
    470  *
    471  *  @since Added in version 3.0.
    472  *
    473  *  @ingroup native
    474  */
    475 GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
    476 
    477 /*! @brief Returns the `EGLContext` of the specified window.
    478  *
    479  *  @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an
    480  *  [error](@ref error_handling) occurred.
    481  *
    482  *  @thread_safety This function may be called from any thread.  Access is not
    483  *  synchronized.
    484  *
    485  *  @since Added in version 3.0.
    486  *
    487  *  @ingroup native
    488  */
    489 GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
    490 
    491 /*! @brief Returns the `EGLSurface` of the specified window.
    492  *
    493  *  @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` 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.0.
    500  *
    501  *  @ingroup native
    502  */
    503 GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
    504 #endif
    505 
    506 #if defined(GLFW_EXPOSE_NATIVE_OSMESA)
    507 /*! @brief Retrieves the color buffer associated with the specified window.
    508  *
    509  *  @param[in] window The window whose color buffer to retrieve.
    510  *  @param[out] width Where to store the width of the color buffer, or `NULL`.
    511  *  @param[out] height Where to store the height of the color buffer, or `NULL`.
    512  *  @param[out] format Where to store the OSMesa pixel format of the color
    513  *  buffer, or `NULL`.
    514  *  @param[out] buffer Where to store the address of the color buffer, or
    515  *  `NULL`.
    516  *  @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
    517  *  [error](@ref error_handling) occurred.
    518  *
    519  *  @thread_safety This function may be called from any thread.  Access is not
    520  *  synchronized.
    521  *
    522  *  @since Added in version 3.3.
    523  *
    524  *  @ingroup native
    525  */
    526 GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height, int* format, void** buffer);
    527 
    528 /*! @brief Retrieves the depth buffer associated with the specified window.
    529  *
    530  *  @param[in] window The window whose depth buffer to retrieve.
    531  *  @param[out] width Where to store the width of the depth buffer, or `NULL`.
    532  *  @param[out] height Where to store the height of the depth buffer, or `NULL`.
    533  *  @param[out] bytesPerValue Where to store the number of bytes per depth
    534  *  buffer element, or `NULL`.
    535  *  @param[out] buffer Where to store the address of the depth buffer, or
    536  *  `NULL`.
    537  *  @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
    538  *  [error](@ref error_handling) occurred.
    539  *
    540  *  @thread_safety This function may be called from any thread.  Access is not
    541  *  synchronized.
    542  *
    543  *  @since Added in version 3.3.
    544  *
    545  *  @ingroup native
    546  */
    547 GLFWAPI int glfwGetOSMesaDepthBuffer(GLFWwindow* window, int* width, int* height, int* bytesPerValue, void** buffer);
    548 
    549 /*! @brief Returns the `OSMesaContext` of the specified window.
    550  *
    551  *  @return The `OSMesaContext` of the specified window, or `NULL` if an
    552  *  [error](@ref error_handling) occurred.
    553  *
    554  *  @thread_safety This function may be called from any thread.  Access is not
    555  *  synchronized.
    556  *
    557  *  @since Added in version 3.3.
    558  *
    559  *  @ingroup native
    560  */
    561 GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window);
    562 #endif
    563 
    564 #ifdef __cplusplus
    565 }
    566 #endif
    567 
    568 #endif /* _glfw3_native_h_ */
    569