From 94c5e361fbb229b0cd6853e2102a7d95f1f358b3 Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Mon, 12 Oct 2026 22:12:02 +0300 Subject: better public interface and doxygen --- include/yasl/native/cocoa.h | 33 +++++++++++++++++++++++++++++---- include/yasl/native/wayland.h | 20 +++++++++++++++++++- include/yasl/native/x11.h | 22 ++++++++++++++++++++-- 3 files changed, 68 insertions(+), 7 deletions(-) (limited to 'include/yasl/native') diff --git a/include/yasl/native/cocoa.h b/include/yasl/native/cocoa.h index 9066a19..9b221cf 100644 --- a/include/yasl/native/cocoa.h +++ b/include/yasl/native/cocoa.h @@ -1,3 +1,7 @@ +/** + * @file + * Typed borrowed Cocoa handles; available on macOS. Use on the main thread. + */ #ifndef YASL_NATIVE_COCOA_H #define YASL_NATIVE_COCOA_H @@ -8,9 +12,9 @@ @class NSWindow; @class NSView; #else -typedef struct objc_object NSApplication; -typedef struct objc_object NSWindow; -typedef struct objc_object NSView; +typedef struct objc_object NSApplication; /**< Opaque Cocoa application in plain C/C++. */ +typedef struct objc_object NSWindow; /**< Opaque Cocoa window in plain C/C++. */ +typedef struct objc_object NSView; /**< Opaque Cocoa view in plain C/C++. */ #endif #ifdef __cplusplus @@ -18,9 +22,30 @@ extern "C" { #endif /* Return borrowed Cocoa handles (expire on display/surface destruction). - * Return NULL / nil if display/surface is not a Cocoa object or destroyed. */ + * Return NULL / nil if display/surface is not a Cocoa object or NULL. */ +/** + * Get the borrowed NSApplication for an object of the matching backend. + * @param d Live display, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on display destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API NSApplication *yasl_cocoa_display_get_application(struct yasl_display *d); +/** + * Get the borrowed NSWindow for an object of the matching backend. + * @param s Live surface, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on surface destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API NSWindow *yasl_cocoa_surface_get_window(struct yasl_surface *s); +/** + * Get the borrowed NSView for an object of the matching backend. + * @param s Live surface, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on surface destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API NSView *yasl_cocoa_surface_get_view(struct yasl_surface *s); #ifdef __cplusplus diff --git a/include/yasl/native/wayland.h b/include/yasl/native/wayland.h index 4a759d4..b11e3b8 100644 --- a/include/yasl/native/wayland.h +++ b/include/yasl/native/wayland.h @@ -1,3 +1,7 @@ +/** + * @file + * Typed borrowed Wayland handles; available when built with Wayland support. + */ #ifndef YASL_NATIVE_WAYLAND_H #define YASL_NATIVE_WAYLAND_H @@ -11,8 +15,22 @@ struct wl_display; struct wl_surface; /* Return borrowed Wayland handles (expire on display/surface destruction). - * Return NULL if display/surface is not a Wayland object or destroyed. */ + * Return NULL if display/surface is not a Wayland object or NULL. */ +/** + * Get the borrowed Wayland connection for an object of the matching backend. + * @param d Live display, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on display destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API struct wl_display *yasl_wayland_display_get_wl_display(struct yasl_display *d); +/** + * Get the borrowed Wayland surface for an object of the matching backend. + * @param s Live surface, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on surface destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API struct wl_surface *yasl_wayland_surface_get_wl_surface(struct yasl_surface *s); #ifdef __cplusplus diff --git a/include/yasl/native/x11.h b/include/yasl/native/x11.h index c0105cb..b719b4b 100644 --- a/include/yasl/native/x11.h +++ b/include/yasl/native/x11.h @@ -1,3 +1,7 @@ +/** + * @file + * Typed borrowed X11 handles; available when built with X11 support. + */ #ifndef YASL_NATIVE_X11_H #define YASL_NATIVE_X11_H @@ -8,11 +12,25 @@ extern "C" { #endif -typedef struct _XDisplay Display; +typedef struct _XDisplay Display; /**< Opaque Xlib connection, compatible with Xlib.h. */ /* Return borrowed X11 handles (expire on display/surface destruction). - * Return NULL / 0 if display/surface is not an X11 object or destroyed. */ + * Return NULL / 0 if display/surface is not an X11 object or NULL. */ +/** + * Get the borrowed X11 Display for an object of the matching backend. + * @param d Live display, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on display destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API Display *yasl_x11_display_get_display(struct yasl_display *d); +/** + * Get the borrowed X11 Window ID for an object of the matching backend. + * @param s Live surface, or NULL. + * @return The handle, or zero/NULL for NULL or a different backend. + * Expires on surface destruction. Available only when this backend is built. + * Never pass a pointer to a destroyed object. + */ YASL_API uintptr_t yasl_x11_surface_get_window(struct yasl_surface *s); #ifdef __cplusplus -- cgit v1.2.3