From dc2f2b2a120f59c69d0f8bd73e2c0dffd6b582a4 Mon Sep 17 00:00:00 2001 From: iddev5 Date: Fri, 24 Dec 2021 12:44:00 +0530 Subject: [PATCH] glfw: improve documentation for native.zig - Added hidden error returns - Improved return types - Updated docs to glfw 3.3.6 --- glfw/src/native.zig | 174 ++++++++++++++++++++++++++++++-------------- 1 file changed, 120 insertions(+), 54 deletions(-) diff --git a/glfw/src/native.zig b/glfw/src/native.zig index ead3bd4a..9e8b107e 100644 --- a/glfw/src/native.zig +++ b/glfw/src/native.zig @@ -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));