From 78121ad2d8b1b2fe95d137b6b6baa7a163dd5be6 Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Sat, 3 Jul 2021 10:53:35 +0200 Subject: xcursor: improve documentation --- include/wlr/xcursor.h | 54 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/include/wlr/xcursor.h b/include/wlr/xcursor.h index 9c305407..d21025cc 100644 --- a/include/wlr/xcursor.h +++ b/include/wlr/xcursor.h @@ -44,20 +44,30 @@ #include #include +/** + * A still cursor image. + * + * The buffer contains pixels layed out in a packed DRM_FORMAT_ARGB8888 format. + */ struct wlr_xcursor_image { - uint32_t width; /* actual width */ - uint32_t height; /* actual height */ - uint32_t hotspot_x; /* hot spot x (must be inside image) */ - uint32_t hotspot_y; /* hot spot y (must be inside image) */ - uint32_t delay; /* animation delay to next frame (ms) */ - uint8_t *buffer; + uint32_t width; /* actual width */ + uint32_t height; /* actual height */ + uint32_t hotspot_x; /* hot-spot x (must be inside image) */ + uint32_t hotspot_y; /* hot-spot y (must be inside image) */ + uint32_t delay; /* animation delay to next frame (ms) */ + uint8_t *buffer; /* pixel data */ }; +/** + * A cursor. + * + * If the cursor is animated, it may contain more than a single image. + */ struct wlr_xcursor { unsigned int image_count; struct wlr_xcursor_image **images; char *name; - uint32_t total_delay; /* length of the animation in ms */ + uint32_t total_delay; /* total duration of the animation in ms */ }; /** @@ -71,30 +81,46 @@ struct wlr_xcursor_theme { }; /** - * Loads the named xcursor theme at the given cursor size (in pixels). This is - * useful if you need cursor images for your compositor to use when a - * client-side cursors is not available or you wish to override client-side + * Loads the named Xcursor theme. + * + * This is useful if you need cursor images for your compositor to use when a + * client-side cursor is not available or you wish to override client-side * cursors for a particular UI interaction (such as using a grab cursor when * moving a window around). + * + * The size is given in pixels. + * + * If a cursor theme with the given name couldn't be loaded, a fallback theme + * is loaded. + * + * On error, NULL is returned. */ struct wlr_xcursor_theme *wlr_xcursor_theme_load(const char *name, int size); +/** + * Destroy a cursor theme. + * + * This implicitly destroys all child cursors and cursor images. + */ void wlr_xcursor_theme_destroy(struct wlr_xcursor_theme *theme); /** - * Obtains a wlr_xcursor image for the specified cursor name (e.g. "left_ptr"). + * Obtain a cursor for the specified name (e.g. "left_ptr"). + * + * If the cursor could not be found, NULL is returned. */ struct wlr_xcursor *wlr_xcursor_theme_get_cursor( struct wlr_xcursor_theme *theme, const char *name); /** - * Returns the current frame number for an animated cursor give a monotonic time - * reference. + * Find the frame for a given elapsed time in a cursor animation. + * + * This function converts a timestamp (in ms) to a cursor image index. */ int wlr_xcursor_frame(struct wlr_xcursor *cursor, uint32_t time); /** - * Get the name of the resize cursor image for the given edges. + * Get the name of the resize cursor for the given edges. */ const char *wlr_xcursor_get_resize_name(enum wlr_edges edges); -- cgit v1.2.3