zig/mach
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

glfw: improve documentation for native.zig

Browse source 
- Added hidden error returns
- Improved return types
- Updated docs to glfw 3.3.6
This commit is contained in:
iddev5 2021-12-24 12:44:00 +05:30 • committed by Stephen Gutekanst
parent 494eb81b56
commit dc2f2b2a12
1 changed files with 120 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

174
glfw/src/native.zig
View file

@ -20,6 +20,25 @@ const BackendOptions = struct {
osmesa: bool = false,
};
/// This function returns a type which allows provides an interface to access
/// the native handles based on backends selected.
///
/// The available window API options are:
/// * win32
/// * cocoa
/// * x11
/// * wayland
///
/// The available context API options are:
///
/// * wgl
/// * nsgl
/// * glx
/// * egl
/// * osmesa
///
/// The chosen backends must match those the library was compiled for. Failure to do so
/// will cause a link-time error.
pub fn Native(comptime options: BackendOptions) type {
const native = @cImport({
@cDefine("GLFW_INCLUDE_VULKAN", "1");
@ -40,8 +59,12 @@ pub fn Native(comptime options: BackendOptions) type {
return struct {
/// Returns the adapter device name of the specified monitor.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// return: The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`) of the
/// specified monitor.
///
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWin32Adapter(monitor: Monitor) [*:0]const u8 {
internal_debug.assertInitialized();
const adapter = native.glfwGetWin32Adapter(@ptrCast(*native.GLFWmonitor, monitor.handle));
@ -54,8 +77,12 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the display device name of the specified monitor.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// return: The UTF-8 encoded display device name (for example `\\.\DISPLAY1\Monitor0`)
/// of the specified monitor.
///
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWin32Monitor(monitor: Monitor) [*:0]const u8 {
internal_debug.assertInitialized();
const mon = native.glfwWin32Monitor(@ptrCast(*native.GLFWmonitor, monitor.handle));
@ -68,8 +95,17 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `HWND` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// The `HDC` associated with the window can be queried with the
/// [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc)
/// function.
/// ```
/// const dc = std.os.windows.user32.GetDC(native.getWin32Window(window));
/// ```
/// This DC is private and does not need to be released.
///
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWin32Window(window: Window) std.os.windows.HWND {
internal_debug.assertInitialized();
const win = native.glfwGetWin32Window(@ptrCast(*native.GLFWwindow, window.handle));
@ -82,8 +118,17 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `HGLRC` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// The `HDC` associated with the window can be queried with the
/// [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc)
/// function.
/// ```
/// const dc = std.os.windows.user32.GetDC(native.getWin32Window(window));
/// ```
/// This DC is private and does not need to be released.
///
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWGLContext(window: Window) error{NoWindowContext}!std.os.windows.HGLRC {
internal_debug.assertInitialized();
const context = native.glfwGetWGLContext(@ptrCast(*native.GLFWwindow, window.handle));
@ -97,8 +142,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `CGDirectDisplayID` of the specified monitor.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getCocoaMonitor(monitor: Monitor) u32 {
internal_debug.assertInitialized();
const mon = native.glfwGetCocoaMonitor(@ptrCast(*native.GLFWmonitor, monitor.handle));
@ -111,8 +157,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `NSWindow` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getCocoaWindow(window: Window) u32 {
internal_debug.assertInitialized();
const win = native.glfwGetCocoaWindow(@ptrCast(*native.GLFWwindow, window.handle));
@ -125,8 +172,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `NSWindow` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitialized, glfw.Error.NoWindowContext.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getNSGLContext(window: Window) error{NoWindowContext}!u32 {
internal_debug.assertInitialized();
const context = native.glfwGetNSGLContext(@ptrCast(*native.GLFWwindow, window.handle));
@ -140,9 +188,10 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `Display` used by GLFW.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
pub fn getX11Display() ?*anyopaque {
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getX11Display() *anyopaque {
internal_debug.assertInitialized();
const display = native.glfwGetX11Display();
getError() catch |err| return switch (err) {
@ -154,8 +203,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `RRCrtc` of the specified monitor.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getX11Adapter(monitor: Monitor) u32 {
internal_debug.assertInitialized();
const adapter = native.glfwGetX11Adapter(@ptrCast(*native.GLFWMonitor, monitor.handle));
@ -168,8 +218,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `RROutput` of the specified monitor.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getX11Monitor(monitor: Monitor) u32 {
internal_debug.assertInitialized();
const mon = native.glfwGetX11Monitor(@ptrCast(*native.GLFWmonitor, monitor.handle));
@ -182,8 +233,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `Window` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getX11Window(window: Window) u32 {
internal_debug.assertInitialized();
const win = native.glfwGetX11Window(@ptrCast(*native.GLFWwindow, window.handle));
@ -196,11 +248,11 @@ pub fn Native(comptime options: BackendOptions) type {
/// Sets the current primary selection to the specified string.
///
/// Possible errors include error.PlatformError
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// The specified string is copied before this function returns.
///
/// @thread_safety This function must only be called from the main thread.
/// thread_safety: This function must only be called from the main thread.
pub fn setX11SelectionString(string: [*:0]const u8) error{PlatformError}!void {
internal_debug.assertInitialized();
native.glfwSetX11SelectionString(string);
@ -213,18 +265,19 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the contents of the current primary selection as a string.
///
/// Possible errors include error.PlatformError
/// Possible errors include glfw.Error.NotInitialized and glfw.Error.PlatformError.
///
/// The returned string is allocated and freed by GLFW. You should not free it
/// yourself. It is valid until the next call to getX11SelectionString or
/// setX11SelectionString, or until the library is terminated.
///
/// @thread_safety This function must only be called from the main thread.
pub fn getX11SelectionString() [*:0]const u8 {
/// thread_safety: This function must only be called from the main thread.
pub fn getX11SelectionString() error{FormatUnavailable}![*:0]const u8 {
internal_debug.assertInitialized();
const str = native.glfwGetX11SelectionString();
getError() catch |err| return switch (err) {
Error.NotInitialized => unreachable,
Error.FormatUnavailable => |e| @errSetCast(error{FormatUnavailable}, e),
else => unreachable,
};
return str;
@ -232,8 +285,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `GLXContext` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NoWindowContext and glfw.Error.NotInitialized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getGLXContext(window: Window) error{NoWindowContext}!*anyopaque {
internal_debug.assertInitialized();
const context = native.glfwGetGLXContext(@ptrCast(*native.GLFWwindow, window.handle));
@ -247,8 +301,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `GLXWindow` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NoWindowContext and glfw.Error.NotInitialized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getGLXWindow(window: Window) error{NoWindowContext}!*anyopaque {
internal_debug.assertInitialized();
const win = native.glfwGetGLXWindow(@ptrCast(*native.GLFWwindow, window.handle));
@ -262,8 +317,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `*wl_display` used by GLFW.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWaylandDisplay() *anyopaque {
internal_debug.assertInitialized();
const display = native.glfwGetWaylandDisplay();
@ -276,8 +332,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `*wl_output` of the specified monitor.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWaylandMonitor(monitor: Monitor) *anyopaque {
internal_debug.assertInitialized();
const mon = native.glfwGetWaylandMonitor(@ptrCast(*native.GLFWmonitor, monitor.handle));
@ -290,8 +347,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `*wl_surface` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getWaylandWindow(window: Window) *anyopaque {
internal_debug.assertInitialized();
const win = native.glfwGetWaylandWindow(@ptrCast(*native.GLFWwindow, window.handle));
@ -304,8 +362,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `EGLDisplay` used by GLFW.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getEGLDisplay() *anyopaque {
internal_debug.assertInitialized();
const display = native.glfwGetEGLDisplay();
@ -318,8 +377,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `EGLContext` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized and glfw.Error.NoWindowContext.
///
/// thread_safety This function may be called from any thread. Access is not synchronized.
pub fn getEGLContext(window: Window) error{NoWindowContext}!*anyopaque {
internal_debug.assertInitialized();
const context = native.glfwGetEGLContext(@ptrCast(*native.GLFWwindow, window.handle));
@ -333,8 +393,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the `EGLSurface` of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized and glfw.Error.NoWindowContext.
///
/// thread_safety This function may be called from any thread. Access is not synchronized.
pub fn getEGLSurface(window: Window) error{NoWindowContext}!*anyopaque {
internal_debug.assertInitialized();
const surface = native.glfwGetEGLSurface(@ptrCast(*native.GLFWwindow, window.handle));
@ -355,15 +416,17 @@ pub fn Native(comptime options: BackendOptions) type {
/// Retrieves the color buffer associated with the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
pub fn getOSMesaColorBuffer(window: Window) error{PlatformError}!OSMesaColorBuffer {
/// Possible errors include glfw.Error.NotInitalized, glfw.Error.NoWindowContext
/// and glfw.Error.PlatformError.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getOSMesaColorBuffer(window: Window) error{ PlatformError, NoWindowContext }!OSMesaColorBuffer {
internal_debug.assertInitialized();
var buf: OSMesaColorBuffer = undefined;
_ = native.glfwGetOSMesaColorBuffer(@ptrCast(*native.GLFWwindow, window.handle), &buf.width, &buf.height, &buf.format, &buf.buffer);
getError() catch |err| return switch (err) {
Error.NotInitialized => unreachable,
Error.PlatformError => |e| @errSetCast(error{PlatformError}, e),
Error.PlatformError, Error.NoWindowContext => |e| @errSetCast(error{ PlatformError, NoWindowContext }, e),
else => unreachable,
};
return buf;
@ -378,15 +441,17 @@ pub fn Native(comptime options: BackendOptions) type {
/// Retrieves the depth buffer associated with the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
pub fn getOSMesaDepthBuffer(window: Window) error{PlatformError}!OSMesaDepthBuffer {
/// Possible errors include glfw.Error.NotInitalized, glfw.Error.NoWindowContext
/// and glfw.Error.PlatformError.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getOSMesaDepthBuffer(window: Window) error{ PlatformError, NoWindowContext }!OSMesaDepthBuffer {
internal_debug.assertInitialized();
var buf: OSMesaDepthBuffer = undefined;
_ = native.glfwGetOSMesaDepthBuffer(@ptrCast(*native.GLFWwindow, window.handle), &buf.width, &buf.height, &buf.bytes_per_value, &buf.buffer);
getError() catch |err| return switch (err) {
Error.NotInitialized => unreachable,
Error.PlatformError => |e| @errSetCast(error{PlatformError}, e),
Error.PlatformError, Error.NoWindowContext => |e| @errSetCast(error{ PlatformError, NoWindowContext }, e),
else => unreachable,
};
return buf;
@ -394,8 +459,9 @@ pub fn Native(comptime options: BackendOptions) type {
/// Returns the 'OSMesaContext' of the specified window.
///
/// @thread_safety This function may be called from any thread. Access is not
/// synchronized.
/// Possible errors include glfw.Error.NotInitalized and glfw.Error.NoWindowContext.
///
/// thread_safety: This function may be called from any thread. Access is not synchronized.
pub fn getOSMesaContext(window: Window) error{NoWindowContext}!*anyopaque {
internal_debug.assertInitialized();
const context = native.glfwGetOSMesa(@ptrCast(*native.GLFWwindow, window.handle));