From 881fb6cb1d64868132287bd9637f4ae1cbc3504c Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Mon, 12 Oct 2026 10:17:33 +0300 Subject: cursor hidden and tablet support --- README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 4b961ef..542b4a6 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,12 @@ with a negative timeout, or waits up to a positive number of milliseconds. Pending input or redraw work returns immediately; call `yasl_display_flush()` after processing input and scheduling redraws. +Call `yasl_surface_set_cursor(surface, YASL_CURSOR_HIDDEN)` to hide the system +mouse and tablet cursor over a surface while continuing to receive pointer +input. The choice persists across motion and re-entry; select another cursor, +such as `YASL_CURSOR_ARROW`, to show it again. `YASL_CURSOR_NONE` is a compatible +alias for `YASL_CURSOR_HIDDEN`. + Include `` to use the optional event loop, file watches, or timers. Timers use one callback model and nanoseconds throughout; use `YASL_MS_TO_NS(5)` for a five-millisecond interval. Add application timers to @@ -82,6 +88,7 @@ Input queues, frame clocks, backend entry points, and protocol helpers are priva Use `yasl_display_caps()` to check optional features. X11 supports CPU pixel buffers, keyboard and pointer input, and clipboard transfer. +Tablet pressure, tilt, and erasers use XInput 2 when the server exposes it. It supports the primary selection and window placement. It does not yet support YASL popups, drag operations, or IME preedit text. Those features return their normal unsupported result. @@ -117,8 +124,9 @@ are declared only in ``; handles are borrowed until destruction. Copy a payload if it must live longer. - Input queues grow rather than silently dropping events at a fixed limit. If allocation fails, pending input is discarded and `YASL_INPUT_RESET` is - delivered before later events. Apps must clear held keys/buttons and input - composition state on this event. + delivered before later events. X11 also sends a reset when input devices are + removed or disabled. Apps must clear held keys/buttons and input composition + state on this event. - Clipboard requests retain their original target. Destroying that target cancels delivery, rather than redirecting the paste to a focused window. Unsupported primary selections are no-ops, never aliases for the clipboard. @@ -155,7 +163,7 @@ ninja -C build test Linux builds include each backend whose dependencies are installed. Wayland needs `wayland-client`, `wayland-cursor`, and `xkbcommon`. -X11 needs `x11` and `xkbcommon`. +X11 needs `x11`, `xi` (libXi), and `xkbcommon`. Use `-Dwayland=enabled` or `-Dx11=enabled` to require a backend. Use `-Dwayland=disabled` or `-Dx11=disabled` to omit a backend. At least one backend must be built. @@ -178,6 +186,69 @@ For memory and undefined-behavior checks, configure a separate build with On macOS, the same option runs native Cocoa window tests. These tests need a desktop session. +## Tablet drawing example + +Build and run the same C application on Wayland, X11, or Cocoa: + +```sh +meson setup build +meson compile -C build +./build/yasl-tablet +./build/yasl-tablet --backend wayland +./build/yasl-tablet --backend x11 +# On macOS: +./build/yasl-tablet --backend cocoa +``` + +Draw with the pen tip: pressure controls brush width. Flip to the eraser to +remove ink. The window shows the selected backend, tool, contact state, raw +pressure (0..65535), percentage, and tilt in degrees, with a live pressure bar, +brush outline, and tilt vector. The system cursor is hidden so the brush overlay +serves as the drawing cursor. Mouse drawing uses a fixed width. Press C or +Space to clear and Escape to quit. Resizing and display scale changes preserve +the drawing. `--smoke-test` presents one frame and exits for automated checks. + +[`examples/tablet.c`](examples/tablet.c) includes only `` and the C +standard library. It uses CPU framebuffers and `yasl_surface_input_poll()` on +every backend. Tablet events arrive as `YASL_INPUT_MOUSE`, distinguished by +`mouse.device == YASL_PTR_DEV_PEN` or `YASL_PTR_DEV_ERASER`; `mouse.pen` contains +pressure and signed tilt. Button 0 is tip contact on every backend. Track tip +press/release events: zero pressure alone does not mean release. Hover and side +buttons do not paint, and focus loss, leave, or `YASL_INPUT_RESET` cancels a stroke. +Stationary pressure changes arrive as motion events and update the brush too. + +`YASL_CAP_TABLET` indicates backend/protocol support, not whether a tablet is +plugged in or which axes it has. Missing axes are zero. Wayland requires the +compositor's `zwp_tablet_manager_v2`; X11 requires XInput 2 and driver-provided +`Abs Pressure`/`Abs Tilt X`/`Abs Tilt Y` valuators. Cocoa handles both tablet mouse +subtypes and native tablet point/proximity events. X11 identifies erasers by +the Wacom tool property or the driver's device name. Hardware and driver +support determine which readings are available. The example displays a message +when the server has no tablet protocol and still allows mouse drawing. + +The test suite checks synthetic Wayland/XInput samples and the drawing behavior +without hardware, including pressure-only changes, sparse axes, eraser input, +hover, release, reset, and scale changes. Linux integration tests launch the +example on isolated Wayland and X11 servers; macOS integration tests also check +Cocoa tablet event translation. Physical tablet testing is still needed to +validate a particular device/driver combination. + +For an end-to-end X11 pressure test without hardware, install Xorg's `dummy` +video driver and `inputtest` input driver, then run: + +```sh +meson configure build -Dx11_tablet_tests=true +meson test -C build tablet-x11-native --print-errorlogs +``` + +This starts an isolated Xorg server with virtual pen and eraser devices, sends +real driver samples, checks YASL's shared events through the example, and verifies +its presented window pixels. It checks stationary pressure changes, release +without valuators, and eraser identification through the driver's tool property. +The test disables automatic physical input/GPU attachment and cleans up its +server. Set `YASL_XORG_MODULE_PATH` to a comma-separated module search path if +the test drivers are outside Xorg's default directories. + ## Quick Example ```c -- cgit v1.2.3