GLFW

- Documentation
- Download
- Community

Functions
Native access

## Description

By using the native access functions you assert that you know what you're doing and how to fix problems caused by using them. If you don't, you shouldn't be using them.

Before the inclusion of glfw3native.h, you may define zero or more window system API macro and zero or more context creation API macros.

The chosen backends must match those the library was compiled for. Failure to do this will cause a link-time error.

The available window API macros are:

- `GLFW_EXPOSE_NATIVE_WIN32`
- `GLFW_EXPOSE_NATIVE_COCOA`
- `GLFW_EXPOSE_NATIVE_X11`
- `GLFW_EXPOSE_NATIVE_WAYLAND`

The available context API macros are:

- `GLFW_EXPOSE_NATIVE_WGL`
- `GLFW_EXPOSE_NATIVE_NSGL`
- `GLFW_EXPOSE_NATIVE_GLX`
- `GLFW_EXPOSE_NATIVE_EGL`
- `GLFW_EXPOSE_NATIVE_OSMESA`

These macros select which of the native access functions that are declared and which platform-specific headers to include. It is then up your (by definition platform-specific) code to handle which of these should be defined.

If you do not want the platform-specific headers to be included, define `GLFW_NATIVE_INCLUDE_NONE` before including the glfw3native.h header.

#define GLFW_EXPOSE_NATIVE_WIN32
#define GLFW_EXPOSE_NATIVE_WGL
#define GLFW_NATIVE_INCLUDE_NONE
#include <GLFW/glfw3native.h>
glfw3native.h
The header of the native access functions.

## Functions
const char * | glfwGetWin32Adapter (GLFWmonitor *monitor)
| Returns the adapter device name of the specified monitor. More...
const char * | glfwGetWin32Monitor (GLFWmonitor *monitor)
| Returns the display device name of the specified monitor. More...
HWND | glfwGetWin32Window (GLFWwindow *window)
| Returns the `HWND` of the specified window. More...
HGLRC | glfwGetWGLContext (GLFWwindow *window)
| Returns the `HGLRC` of the specified window. More...
CGDirectDisplayID | glfwGetCocoaMonitor (GLFWmonitor *monitor)
| Returns the `CGDirectDisplayID` of the specified monitor. More...
id | glfwGetCocoaWindow (GLFWwindow *window)
| Returns the `NSWindow` of the specified window. More...
id | glfwGetNSGLContext (GLFWwindow *window)
| Returns the `NSOpenGLContext` of the specified window. More...
Display * | glfwGetX11Display (void)
| Returns the `Display` used by GLFW. More...
RRCrtc | glfwGetX11Adapter (GLFWmonitor *monitor)
| Returns the `RRCrtc` of the specified monitor. More...
RROutput | glfwGetX11Monitor (GLFWmonitor *monitor)
| Returns the `RROutput` of the specified monitor. More...
Window | glfwGetX11Window (GLFWwindow *window)
| Returns the `Window` of the specified window. More...
void | glfwSetX11SelectionString (const char *string)
| Sets the current primary selection to the specified string. More...
const char * | glfwGetX11SelectionString (void)
| Returns the contents of the current primary selection as a string. More...
GLXContext | glfwGetGLXContext (GLFWwindow *window)
| Returns the `GLXContext` of the specified window. More...
GLXWindow | glfwGetGLXWindow (GLFWwindow *window)
| Returns the `GLXWindow` of the specified window. More...
struct wl_display * | glfwGetWaylandDisplay (void)
| Returns the `struct wl_display*` used by GLFW. More...
struct wl_output * | glfwGetWaylandMonitor (GLFWmonitor *monitor)
| Returns the `struct wl_output*` of the specified monitor. More...
struct wl_surface * | glfwGetWaylandWindow (GLFWwindow *window)
| Returns the main `struct wl_surface*` of the specified window. More...
EGLDisplay | glfwGetEGLDisplay (void)
| Returns the `EGLDisplay` used by GLFW. More...
EGLContext | glfwGetEGLContext (GLFWwindow *window)
| Returns the `EGLContext` of the specified window. More...
EGLSurface | glfwGetEGLSurface (GLFWwindow *window)
| Returns the `EGLSurface` of the specified window. More...
int | glfwGetOSMesaColorBuffer (GLFWwindow *window, int *width, int *height, int *format, void **buffer)
| Retrieves the color buffer associated with the specified window. More...
int | glfwGetOSMesaDepthBuffer (GLFWwindow *window, int *width, int *height, int *bytesPerValue, void **buffer)
| Retrieves the depth buffer associated with the specified window. More...
OSMesaContext | glfwGetOSMesaContext (GLFWwindow *window)
| Returns the `OSMesaContext` of the specified window. More...

## Function Documentation

## ◆ glfwGetWin32Adapter()

const char * glfwGetWin32Adapter | ( | GLFWmonitor * | monitor | ) |

Returns
  The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`) of the specified monitor, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.1.

## ◆ glfwGetWin32Monitor()

const char * glfwGetWin32Monitor | ( | GLFWmonitor * | monitor | ) |

Returns
  The UTF-8 encoded display device name (for example `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.1.

## ◆ glfwGetWin32Window()

HWND glfwGetWin32Window | ( | GLFWwindow * | window | ) |

Returns
  The `HWND` of the specified window, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Remarks
  The `HDC` associated with the window can be queried with the GetDC function.
  HDC dc = GetDC(glfwGetWin32Window(window));
  glfwGetWin32Window
  HWND glfwGetWin32Window(GLFWwindow *window)
  Returns the HWND of the specified window.
  This DC is private and does not need to be released.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetWGLContext()

HGLRC glfwGetWGLContext | ( | GLFWwindow * | window | ) |

Returns
  The `HGLRC` of the specified window, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Remarks
  The `HDC` associated with the window can be queried with the GetDC function.
  HDC dc = GetDC(glfwGetWin32Window(window));
  This DC is private and does not need to be released.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetCocoaMonitor()

CGDirectDisplayID glfwGetCocoaMonitor | ( | GLFWmonitor * | monitor | ) |

Returns
  The `CGDirectDisplayID` of the specified monitor, or `kCGNullDirectDisplay` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.1.

## ◆ glfwGetCocoaWindow()

id glfwGetCocoaWindow | ( | GLFWwindow * | window | ) |

Returns
  The `NSWindow` of the specified window, or `nil` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetNSGLContext()

id glfwGetNSGLContext | ( | GLFWwindow * | window | ) |

Returns
  The `NSOpenGLContext` of the specified window, or `nil` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetX11Display()

Display * glfwGetX11Display | ( | void |  | ) |

Returns
  The `Display` used by GLFW, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetX11Adapter()

RRCrtc glfwGetX11Adapter | ( | GLFWmonitor * | monitor | ) |

Returns
  The `RRCrtc` of the specified monitor, or `None` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.1.

## ◆ glfwGetX11Monitor()

RROutput glfwGetX11Monitor | ( | GLFWmonitor * | monitor | ) |

Returns
  The `RROutput` of the specified monitor, or `None` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.1.

## ◆ glfwGetX11Window()

Window glfwGetX11Window | ( | GLFWwindow * | window | ) |

Returns
  The `Window` of the specified window, or `None` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwSetX11SelectionString()

void glfwSetX11SelectionString | ( | const char * | string | ) |

Parameters

  [in] | string | A UTF-8 encoded string.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime
  The specified string is copied before this function returns.

Thread safety
  This function must only be called from the main thread.

See also
  Clipboard input and output
  glfwGetX11SelectionString
  glfwSetClipboardString

Since
  Added in version 3.3.

## ◆ glfwGetX11SelectionString()

const char * glfwGetX11SelectionString | ( | void |  | ) |

If the selection is empty or if its contents cannot be converted, `NULL` is returned and a GLFW_FORMAT_UNAVAILABLE error is generated.

Returns
  The contents of the selection as a UTF-8 encoded string, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime
  The returned string is allocated and freed by GLFW. You should not free it yourself. It is valid until the next call to glfwGetX11SelectionString or glfwSetX11SelectionString, or until the library is terminated.

Thread safety
  This function must only be called from the main thread.

See also
  Clipboard input and output
  glfwSetX11SelectionString
  glfwGetClipboardString

Since
  Added in version 3.3.

## ◆ glfwGetGLXContext()

GLXContext glfwGetGLXContext | ( | GLFWwindow * | window | ) |

Returns
  The `GLXContext` of the specified window, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetGLXWindow()

GLXWindow glfwGetGLXWindow | ( | GLFWwindow * | window | ) |

Returns
  The `GLXWindow` of the specified window, or `None` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.2.

## ◆ glfwGetWaylandDisplay()

struct wl_display * glfwGetWaylandDisplay | ( | void |  | ) |

Returns
  The `struct wl_display*` used by GLFW, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.2.

## ◆ glfwGetWaylandMonitor()

struct wl_output * glfwGetWaylandMonitor | ( | GLFWmonitor * | monitor | ) |

Returns
  The `struct wl_output*` of the specified monitor, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.2.

## ◆ glfwGetWaylandWindow()

struct wl_surface * glfwGetWaylandWindow | ( | GLFWwindow * | window | ) |

Returns
  The main `struct wl_surface*` of the specified window, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.2.

## ◆ glfwGetEGLDisplay()

EGLDisplay glfwGetEGLDisplay | ( | void |  | ) |

Returns
  The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Remarks
  Because EGL is initialized on demand, this function will return `EGL_NO_DISPLAY` until the first context has been created via EGL.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetEGLContext()

EGLContext glfwGetEGLContext | ( | GLFWwindow * | window | ) |

Returns
  The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetEGLSurface()

EGLSurface glfwGetEGLSurface | ( | GLFWwindow * | window | ) |

Returns
  The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.0.

## ◆ glfwGetOSMesaColorBuffer()

int glfwGetOSMesaColorBuffer | ( | GLFWwindow * | window,
|  | int * | width,
|  | int * | height,
|  | int * | format,
|  | void ** | buffer
| ) |  |

Parameters

  [in] | window | The window whose color buffer to retrieve.
  [out] | width | Where to store the width of the color buffer, or `NULL`.
  [out] | height | Where to store the height of the color buffer, or `NULL`.
  [out] | format | Where to store the OSMesa pixel format of the color buffer, or `NULL`.
  [out] | buffer | Where to store the address of the color buffer, or `NULL`.

Returns
  `GLFW_TRUE` if successful, or `GLFW_FALSE` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.3.

## ◆ glfwGetOSMesaDepthBuffer()

int glfwGetOSMesaDepthBuffer | ( | GLFWwindow * | window,
|  | int * | width,
|  | int * | height,
|  | int * | bytesPerValue,
|  | void ** | buffer
| ) |  |

Parameters

  [in] | window | The window whose depth buffer to retrieve.
  [out] | width | Where to store the width of the depth buffer, or `NULL`.
  [out] | height | Where to store the height of the depth buffer, or `NULL`.
  [out] | bytesPerValue | Where to store the number of bytes per depth buffer element, or `NULL`.
  [out] | buffer | Where to store the address of the depth buffer, or `NULL`.

Returns
  `GLFW_TRUE` if successful, or `GLFW_FALSE` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.3.

## ◆ glfwGetOSMesaContext()

OSMesaContext glfwGetOSMesaContext | ( | GLFWwindow * | window | ) |

Returns
  The `OSMesaContext` of the specified window, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NO_WINDOW_CONTEXT and GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

Since
  Added in version 3.3.