cursor hidden and tablet support

1 files changed, 16 insertions, 7 deletions

diff --git a/include/yasl/yasl.h b/include/yasl/yasl.h
index 30bf591..77666f8 100644
--- a/include/yasl/yasl.h
+++ b/include/yasl/yasl.h
@@ -78,6 +78,8 @@ enum yasl_display_cap : uint32_t {
     YASL_CAP_CSD               = 1 << 5,
     YASL_CAP_NATIVE_GRAPHICS   = 1 << 6,
     YASL_CAP_FRAME_PACING      = 1 << 7, /* compositor/display-driven draws */
+    /* Backend/protocol supports tablet axes, independent of attached hardware. */
+    YASL_CAP_TABLET            = 1 << 8,
 };
 
 enum yasl_selection : uint8_t {
@@ -103,7 +105,8 @@ enum yasl_cursor {
     YASL_CURSOR_RESIZE_NESW,
     YASL_CURSOR_RESIZE_EW,
     YASL_CURSOR_RESIZE_NS,
-    YASL_CURSOR_NONE,
+    YASL_CURSOR_HIDDEN, /* Hide the system cursor; pointer input is unchanged. */
+    YASL_CURSOR_NONE = YASL_CURSOR_HIDDEN, /* Compatibility alias. */
 };
 
 enum yasl_resize_edge : uint32_t {
@@ -206,9 +209,9 @@ enum yasl_pointer_device {
 };
 
 struct yasl_pointer_pen {
-    uint16_t pressure;
-    int8_t tilt_x;
-    int8_t tilt_y;
+    uint16_t pressure; /* 0..65535, normalized to the device's pressure range. */
+    int8_t tilt_x;     /* Degrees, -90..90; positive toward the right. */
+    int8_t tilt_y;     /* Degrees, -90..90; positive toward the bottom. */
 };
 
 struct yasl_key_event {
@@ -224,12 +227,16 @@ struct yasl_key_event {
 
 struct yasl_mouse_event {
     struct yasl_vector2i pos;
-    int16_t button;
+    int16_t button; /* Press/release: 0 = primary/tip, 1 = middle, 2 = secondary.
+                    * Motion/leave: informational; track presses and releases. */
     int16_t scroll_lines;
     enum yasl_pointer_kind kind;
     enum yasl_pointer_device device;
     uint32_t mods;
     float scroll_delta;
+    /* Pen/eraser samples include the current axes, also on pressure-only
+     * motion. Missing axes and non-tablet devices report zero. A primary
+     * release or leave ends contact; zero pressure alone is not a release. */
     struct yasl_pointer_pen pen;
 };
 
@@ -240,8 +247,8 @@ enum yasl_input_kind {
     YASL_INPUT_PASTE,
     YASL_INPUT_DROP_FILES,
     YASL_INPUT_TEXT,
-    /* Allocation failure broke the input stream. Clear all held keys/buttons
-     * and composition state before processing subsequent events. */
+    /* The input stream was interrupted (e.g. allocation failure or device
+     * removal). Clear held keys/buttons and composition state. */
     YASL_INPUT_RESET,
 };
 
@@ -394,6 +401,8 @@ YASL_API uint32_t yasl_surface_state(const struct yasl_surface *s);
  * Tearing may bypass pacing even when the capability is present. */
 YASL_API struct yasl_timing yasl_surface_timing(const struct yasl_surface *s);
 YASL_API uint64_t yasl_surface_frame_time_ns(struct yasl_surface *s, uint64_t now);
+/* Set the mouse and tablet cursor for this surface, including future entries.
+ * YASL_CURSOR_HIDDEN stays hidden until another cursor is selected. */
 YASL_API void yasl_surface_set_cursor(struct yasl_surface *s, enum yasl_cursor cursor);
 YASL_API void yasl_surface_set_background_color(struct yasl_surface *s, uint32_t bg);