diff options
53 files changed, 3579 insertions, 631 deletions
@@ -1,4 +1,5 @@ build/ +build-docs/ .cache/ *.o *.a diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..88674ca --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing + +YASL focuses on desktop surfaces for applications that own their renderer. +Read the [API policy](docs/api-policy.md) and [application guide](docs/guide.md) +before changing public behavior. Keep backend details in native extensions and +make common operations usable through the portable headers. + +For a bug report, include the revision, operating system, selected backend from +`yasl_display_backend()`, capability mask, compiler, build options, reproduction +steps, and a small example if possible. For input issues include the relevant +event fields, layout/device/driver, and whether the issue occurs on another +backend. Report observations separately from expected behavior. + +Build and test with: + +```sh +meson setup build +meson compile -C build +meson test -C build --print-errorlogs +``` + +See [testing](docs/testing.md) for isolated Linux integration tests, sanitizer +builds, and native tablet tests. Changes to shared behavior need both backend +configurations checked. Cocoa changes need a macOS desktop build/test; Linux +success alone does not validate them. Keep changes focused and describe any +platforms that were not exercised. + +Document public behavior in the installed header first: argument validity, +units, ownership/lifetime, return/error behavior, thread requirements, callback +rules, and unsupported results. Update guides/examples when the workflow +changes. Use zero-initialized specs and check fallible operations in examples. +Build the reference with `doxygen Doxyfile`; warnings are errors. Do not edit +vendored generated protocol files for unrelated changes. + +Use the existing C style and `yasl_`/`YASL_` public names. Run the tests relevant +to the changed behavior, including shared exports and public C/C++ compilation. +For a pull request, explain the observable problem, resulting behavior, and +validation, including any native tests still needed. Contributions use the +project's MIT license. diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..406abac --- /dev/null +++ b/Doxyfile @@ -0,0 +1,25 @@ +PROJECT_NAME = YASL +PROJECT_BRIEF = "Desktop surfaces for application-owned rendering" +OUTPUT_DIRECTORY = build-docs +INPUT = include/yasl docs +RECURSIVE = YES +FILE_PATTERNS = *.h *.md *.dox +EXAMPLE_PATH = examples +FILTER_PATTERNS = *.md="python3 docs/doxygen_filter.py" +USE_MDFILE_AS_MAINPAGE = docs/getting-started.md +EXTRACT_ALL = NO +EXTRACT_STATIC = YES +JAVADOC_AUTOBRIEF = YES +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = YASL_API= __cplusplus +GENERATE_HTML = YES +GENERATE_LATEX = NO +SOURCE_BROWSER = YES +FULL_PATH_NAMES = NO +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_AS_ERROR = FAIL_ON_WARNINGS @@ -1,321 +1,74 @@ -# YASL (Yet Another Surface Library) - -YASL is a minimal, modern, and high-performance desktop window surface library written in C. - -It provides window creation, frame pacing, high-DPI scaling, and input routing without bundling audio, physics, or game engine components. - -## Features - -- **Lean Core**: No audio, no font rendering, and no widget toolkit overhead. -- **Wayland Protocol Coverage**: - - `xdg-shell` toplevels and hierarchical popups (`xdg_popup` + `xdg_positioner`). - - Fractional scaling via `wp_fractional_scale_v1` and `wp_viewporter`. - - Presentation feedback and refresh rate timing via `wp_presentation` and `wp_fifo_v1`. - - Cursor shapes via `wp_cursor_shape_device_v1`. - - Graphics tablets and stylus input via `zwp_tablet_v2` (pressure, tilt, eraser). - - Text Input Method (IME) composition via `zwp_text_input_v3`. - - Primary selection and clipboard transfers via `wl_data_device` and `zwp_primary_selection_v1`. - - Interactive client-side window move and resize triggers (`xdg_toplevel_move`, `xdg_toplevel_resize`). -- **macOS Cocoa & Metal**: - - Native `NSWindow` and `CAMetalLayer` presentation. - - Vsync pacing via `CADisplayLink`. -- **Zero Framework Leaks**: - - Self-contained UTF-8 validation. - - Self-contained event queue. - - No terminal-specific telemetry or hardcoded application names. - -## Public API - -Include `<yasl/yasl.h>` for surface creation, drawing, input, and display dispatch. -`yasl_surface_geometry()` returns device-pixel size and scale together. -`yasl_display_dispatch(display, timeout_ms)` polls with zero, waits indefinitely -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 `<yasl/loop.h>` 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 -`yasl_display_loop(display)`. Add surface timers with `yasl_surface_add_timer()` -when they should be canceled automatically on surface destruction. - -Include `<yasl/native.h>` for platform handles and application-managed native -rendering. These extensions are separate from the portable CPU drawing API. -`<yasl/timing.h>` contains the public timing result types. - -## Backend selection - -YASL selects the native window backend at runtime. -Leave `yasl_display_spec.backend` at zero to use this mode. -`YASL_BACKEND_AUTO` has the same effect. -You can also pass NULL as the display spec. - -On Linux, YASL tries Wayland first in a Wayland session. -It uses `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`, and `XDG_SESSION_TYPE` to detect that session. -In other sessions, it tries X11 first. -If the first backend cannot open, it tries the other built backend. -On macOS, it uses Cocoa. - -Set `backend` to request one backend: - -```c -struct yasl_display_spec spec = { - .app_id = "org.example.app", - .backend = YASL_BACKEND_X11, -}; -struct yasl_display *display = yasl_display_open(loop, &spec); -``` - -Use `YASL_BACKEND_WAYLAND` to request Wayland. -Use `YASL_BACKEND_COCOA` to request Cocoa. -An explicit request never falls back to another backend. -Open returns NULL if the requested backend cannot open. -It sets `errno` to `ENOSYS` for a backend that was not built. -It sets `errno` to `EINVAL` for an invalid backend value. - -Call `yasl_display_backend(display)` to read the selected backend. -All surfaces on a display use that backend. -Open separate displays to use Wayland and X11 in one process. -The public API needs no window system headers. -Shared libraries export only the functions declared in the installed YASL headers. -Input queues, frame clocks, backend entry points, and protocol helpers are private implementation details. -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, window placement, and drag operations. -It does not yet support YASL popups or IME preedit text. -Those features return their normal unsupported result. - -The surface spec needs no native graphics device for CPU drawing. -On Cocoa, YASL creates its own Metal device for this mode. -An app that renders with Metal includes `<yasl/native.h>` and calls -`yasl_surface_create_native(display, &spec, device)`. During its draw callback, -`yasl_surface_get_native_frame()` returns the current Metal drawable. The app -submits and presents it, then calls `yasl_surface_present()` to record submission. - -Type-safe native handles are declared in `<yasl/native/wayland.h>`, -`<yasl/native/x11.h>`, and `<yasl/native/cocoa.h>`: -- Wayland: `wl_display *` and `wl_surface *` via `yasl_wayland_display_get_wl_display()` and `yasl_wayland_surface_get_wl_surface()`. -- X11: `Display *` and `uintptr_t` window ID via `yasl_x11_display_get_display()` and `yasl_x11_surface_get_window()`. -- Cocoa: `NSApplication *`, `NSWindow *`, and `NSView *` via `yasl_cocoa_display_get_application()`, `yasl_cocoa_surface_get_window()`, and `yasl_cocoa_surface_get_view()`. -Generic untyped borrowed handles (`void *`) remain accessible via `<yasl/native.h>`. All handles expire on object destruction. - -## Ownership and backend contracts - -- Calls and callbacks use the thread that opened the display (the main thread - on Cocoa). Supplied event loops are borrowed. Destroy popups before parents, - surfaces before displays, and displays before supplied loops. Surface - destruction inside surface callbacks is supported; display or loop destruction - during callbacks/dispatch is not. -- Callback tables, drag listeners, input strings, titles, clipboard text, and - drag pixels are copied. Userdata is borrowed. Cocoa retains a supplied Metal - device. Native handles are borrowed, not transferred to the caller. -- Text, paste, and file-drop event payloads remain valid until the next - **successful** input poll on that surface or surface destruction. Dispatch, - flush, selection replacement, and failed polls do not invalidate them. - 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. 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. -- CPU pixels are tightly packed premultiplied `0xAARRGGBB`. Creation sizes are - logical pixels; framebuffer sizes, pointer coordinates, caret and damage are - device pixels. Every draw target needs complete valid pixel contents; do not - assume a recycled framebuffer contains the previous frame. -- Present only the current draw callback's target, at most once. Targets expire - when the callback returns; preserve the opaque `generation` when copying a - target. Damage is required, clipped to the target, and validated uniformly. Backends may upload the whole frame despite damage hints. -- `yasl_surface_create_native()` requires `YASL_CAP_NATIVE_GRAPHICS` (currently - Cocoa) and a non-NULL graphics device; other backends return `ENOTSUP`. Native - drawable queries are valid only for the current draw target and expire on - successful present, callback return, or surface destruction. -- `YASL_CAP_FRAME_PACING` distinguishes compositor/display-driven draws from - X11's unpaced flush-driven draws. `yasl_timing.source` distinguishes submission - estimates, frame callbacks, and confirmed presentation feedback. Refresh and - next-presentation times are estimates, not universal vsync guarantees. - -These are pre-release API changes. Applications must handle the new reset input -kind and should inspect timing provenance instead of assuming all timestamps -confirm scanout. See `include/yasl/yasl.h` for the complete contracts. - -## Building - -Use a C23 compiler and Meson 1.6 or later. -Build with Meson and Ninja: - -```sh -meson setup build -ninja -C build -ninja -C build test -``` - -Linux builds include each backend whose dependencies are installed. -Wayland needs `wayland-client`, `wayland-cursor`, 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. - -To run the Linux window tests, install Weston and Xwayland. -Then run: - -```sh -meson setup build-test -Dintegration_tests=true -meson test -C build-test --print-errorlogs -``` - -The tests start isolated display servers. -They test explicit requests, automatic selection, and fallback. -They also test both backends in one process, callback-table copying, input -payload ownership, queue growth, concurrent clipboard targets, and consistent -frame/damage validation. Wayland IME ownership tests need no display server. -For memory and undefined-behavior checks, configure a separate build with -`-Db_sanitize=address,undefined`. -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: +# YASL — Yet Another Surface Library + +YASL is a C desktop surface library for applications that own their renderer. +It creates windows and supplies CPU pixel targets, scale-aware geometry, queued +input, clipboard text, popups, surface drags, and optional frame pacing. +It runs on Wayland, X11, and macOS Cocoa. + +A software-rendered editor, terminal, drawing tool, or custom interface can open +a window and paint pixels without creating an OpenGL context or adopting a +widget toolkit. YASL also exposes tablet pressure/tilt and IME composition. +It does not provide fonts, widgets, audio, or a graphics engine. Native handles +and Cocoa/Metal rendering are separate extensions. + +**Status:** pre-release 0.1; source and ABI compatibility are not yet guaranteed. +Physical keys have portable names, committed text arrives as UTF-8, and scroll +offsets use fractional X/Y line units. Read the [application guide](docs/guide.md) +for platform capabilities and limits. + +## Start here + +- [Getting started](docs/getting-started.md): build, install, link, and run a window. +- [Application guide](docs/guide.md): geometry, drawing, input, ownership, and backend limits. +- [Public reference](include/yasl/yasl.h), [loop](include/yasl/loop.h), + [timing](include/yasl/timing.h), and [native extensions](include/yasl/native.h). + Run `doxygen Doxyfile` for a searchable HTML reference in `build-docs/html`. +- [API policy](docs/api-policy.md), [migration notes](docs/migrating.md), and + [contributing](CONTRIBUTING.md). +- [Tests, tablet example, and benchmarks](docs/testing.md). + +## Build a window + +Use a C23 compiler, Meson 1.6 or newer, and Ninja. Linux needs the development +packages for Wayland (`wayland-client`, `wayland-cursor`, `xkbcommon`) or X11 +(`x11`, `xi`, `xkbcommon`, `xext`; optional `xrandr`). Cocoa requires macOS 14 or +newer and the system SDK, with a Metal-capable device for window drawing. ```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 `<yasl/yasl.h>` 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 +./build/yasl-hello +meson test -C build --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. - -## Benchmarks - -YASL includes a dedicated performance microbenchmark target (`yasl-benchmark`) evaluating CPU efficiency, memory footprint, cache line pressure, data structure operations, and window lifecycle operations across core hot paths (surface lookups, multi-output refresh rate scans, input queue expansions, ring buffer throughput, timer arm/disarm cycles, cold/warm window creation, single and bulk window teardowns, titlebar property updates, and multi-resolution dynamic resizing): +Linux builds automatically include backends with available dependencies. Require +one with `-Dwayland=enabled` or `-Dx11=enabled`; omit one with `disabled`. Runtime +selection chooses the native session and allows fallback, or you can request an +explicit backend with `yasl_display_spec.backend`. -```sh -# Run via meson test runner -meson test -C build --benchmark --verbose - -# Or invoke the executable directly -ninja -C build tests/yasl-benchmark -./build/tests/yasl-benchmark -``` - -## Quick Example +Include `<yasl/yasl.h>` for the core. The complete [hello.c](examples/hello.c) +handles creation failures, drawing, dispatch, input draining, and cleanup. +Its drawing callback fills every pixel before presenting: ```c -#include <yasl/yasl.h> - -static bool running = true; - -static void on_draw(struct yasl_surface *s, struct yasl_frame *frame, void *ud) -{ - /* Present frame target */ - struct yasl_damage_list dmg = { .n = -1 }; - yasl_surface_present(s, &frame->target, &dmg); -} - -static void on_close(struct yasl_surface *s, void *ud) -{ - (void)s; (void)ud; - running = false; -} - -int main(void) +static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *ud) { - struct yasl_display_spec dspec = { .app_id = "org.example.app" }; - struct yasl_display *d = yasl_display_open(NULL, &dspec); - - struct yasl_surface_spec sspec = { - .title = "YASL Application", - .size = { .x = 800, .y = 600 }, - }; - struct yasl_surface *s = yasl_surface_create_toplevel(d, &sspec); - struct yasl_surface_cbs cbs = { - .draw = on_draw, - .close = on_close, - }; - yasl_surface_set_callbacks(s, &cbs, NULL); - yasl_surface_schedule_redraw(s); - - while (running) { - yasl_display_dispatch(d, -1); - struct yasl_input_event ev; - while (yasl_surface_input_poll(s, &ev)) { - if (ev.kind == YASL_INPUT_KEY && ev.key.action == YASL_KEY_PRESS) { - if (ev.key.key == 0xff1b) /* Escape */ - running = false; - } - } - yasl_display_flush(d); + (void)ud; + size_t count = (size_t)frame->target.size.x * frame->target.size.y; + for (size_t i = 0; i < count; i++) + frame->target.pixels[i] = 0xff306090; + struct yasl_damage_list damage = {.n = -1}; + if (!yasl_surface_present(surface, &frame->target, &damage)) { + /* Arrange application error handling after returning. */ } - - yasl_surface_destroy(s); - yasl_display_close(d); - return 0; } ``` +Toplevel creation sizes are logical pixels; drawing and input use device pixels. +Targets are borrowed for one draw callback. Keep durable content in application +memory, dispatch events, drain input queues, then flush scheduled drawing. These +rules are explained with examples in the application guide. + ## License -MIT License. +[MIT](LICENSE). diff --git a/docs/api-policy.md b/docs/api-policy.md new file mode 100644 index 0000000..d5c7159 --- /dev/null +++ b/docs/api-policy.md @@ -0,0 +1,37 @@ +# Public API policy + +YASL 0.1 is pre-release. The installed headers are the public API; implementation +headers under `src/` are private even when their symbols appear in a static +archive. The shared library exports only declarations from installed headers. +Native backend headers and accessors are available only for built backends. + +There is currently no stable ABI promise and no versioned shared-library SONAME. +Rebuild consumers against the exact headers/library pair they ship. Source and +binary compatibility can change before 1.0. Do not assume struct layout is stable +across releases, mix headers and binaries from different revisions, or persist +public structs as a file/network format. The package version is available through +`pkg-config --modversion yasl`. + +See [migration notes](migrating.md) for the portable keyboard and fractional +scroll API changes. + +API changes should keep ordinary CPU drawing usable with only `<yasl/yasl.h>` +and the C standard library. Prefer an explicit capability and an ordinary +unsupported result over backend names in portable application logic. Native +rendering and handles belong in the extension headers. Avoid adding engine, +widget, renderer, or application policy to the surface layer. + +Every public addition or behavior change needs: + +- A header contract describing arguments, result, units, lifetime, threading, + callback timing, and unsupported behavior where applicable. +- An update to the guide and its backend limits when observable behavior changes. +- A runnable example when the new workflow cannot be understood from an isolated + call, and meaningful regression coverage for ownership or behavior changes. +- A check that shared exports and installed-package consumers still work. + +Functions documenting errno set it on failure. Other booleans report acceptance +or availability without a guaranteed errno; void setters are best effort. +Callbacks and successful returns do not imply confirmed screen presentation. +See `yasl_timing.source` for provenance. Future changes that strengthen error +reporting must preserve these distinctions in documentation. diff --git a/docs/doxygen_filter.py b/docs/doxygen_filter.py new file mode 100644 index 0000000..ed6e6e8 --- /dev/null +++ b/docs/doxygen_filter.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +"""Resolve repository source links to Doxygen reference/example pages. + +Markdown keeps ordinary relative links for repository and installed-document +readers. Doxygen gets @ref links so its standalone HTML has no source-tree URLs. +""" + +from pathlib import Path +import re +import sys + +text = Path(sys.argv[1]).read_text(encoding="utf-8") + + +def reference(match): + label, target = match.groups() + if target.startswith("../include/yasl/") and target.endswith(".h"): + return f"[{label}](@ref {Path(target).name})" + if target.startswith("../examples/") and target.endswith(".c"): + return f"[{label}](@ref {Path(target).name})" + return match.group(0) + + +sys.stdout.write(re.sub(r"\[([^\]]+)\]\(([^)]+)\)", reference, text)) diff --git a/docs/examples.dox b/docs/examples.dox new file mode 100644 index 0000000..8e9d06a --- /dev/null +++ b/docs/examples.dox @@ -0,0 +1,12 @@ +/** @example hello.c + * A complete beginner window using CPU pixels, checked creation/presentation, + * and ordered shutdown. Run with --smoke-test to present once and exit. + */ + +/** @example simple_window.c + * Interactive pointer and tablet samples over a CPU-rendered gradient. + */ + +/** @example tablet.c + * Retained drawing content with pressure, tilt, eraser input, and scale changes. + */ diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..ff40a9b --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,118 @@ +# Getting started + +YASL gives a C application desktop windows with CPU pixel targets, scale-aware +geometry, queued input, clipboard text, and optional frame pacing. It fits +software-rendered tools such as editors, terminals, drawing applications, and +custom interfaces that already have their own renderer. A window needs neither +an OpenGL context nor a graphics device supplied by the application. + +The core headers expose no window system types. Native handles and Metal drawing +are separate opt-in extensions. YASL currently supports Linux (Wayland and X11) +and macOS (Cocoa); it does not provide widgets, font shaping, audio, an OpenGL +context API, or a Vulkan surface API. It is pre-release software; see the +[API policy](api-policy.md) before distributing a library that depends on its ABI. + +## Build and run + +Use a C23 compiler, Meson 1.6 or newer, and Ninja. GCC and Clang can build the library. On Linux install either backend's development dependencies: + +| Backend | pkg-config dependencies | +| --- | --- | +| Wayland | `wayland-client`, `wayland-cursor`, `xkbcommon` | +| X11 | `x11`, `xi`, `xkbcommon`, `xext`; optional `xrandr` | +| Cocoa | macOS 14+ SDK with AppKit, Metal, and QuartzCore; Metal-capable device | + +```sh +meson setup build +meson compile -C build +./build/yasl-hello +meson test -C build --print-errorlogs +``` + +Each Linux backend defaults to `auto`, meaning build it when its dependencies +are available. Require one with `-Dwayland=enabled` or `-Dx11=enabled`; omit one +with `-Dwayland=disabled` or `-Dx11=disabled`. At least one backend is required. +Cocoa is selected on macOS and requires no extra third-party dependencies. +Its minimum deployment target is macOS 14. Set `MACOSX_DEPLOYMENT_TARGET=14.0` +(or newer) before configuring if your toolchain defaults to an older target. +CPU pixel targets are presented through the system's Metal device; applications +do not need to create or manage that device themselves. + +The complete beginner example is [hello.c](../examples/hello.c). It checks +construction failures, fills every pixel, presents inside `draw`, drains input, +responds to quit/close/lost, and destroys resources in order. The +[interactive window](../examples/simple_window.c) adds pointer input; the +[tablet example](../examples/tablet.c) demonstrates retained application content, +pressure, erasers, resizing, and scale changes. + +## Link an application + +Install the library and public headers into your chosen prefix: + +```sh +meson setup build --prefix=/usr/local +meson compile -C build +meson install -C build +cc -std=c23 examples/hello.c -o hello $(pkg-config --cflags --libs yasl) +./hello +``` + +The prefix must be writable, and your compiler, pkg-config, and runtime loader +must search it. For a custom prefix, set `PKG_CONFIG_PATH` to its pkg-config +directory and configure the loader for its library directory. Static linking +uses `pkg-config --static --libs yasl` to include backend dependencies. + +A Meson consumer uses the installed dependency: + +```meson +project('my-app', 'c', default_options: ['c_std=c23']) +yasl = dependency('yasl', version: '>=0.1.0') +executable('my-app', 'main.c', dependencies: yasl) +``` + +YASL also declares `meson.override_dependency('yasl', ...)`, so the same consumer +can use a vendored Meson subproject through a fallback dependency. Public headers +can be included from C++11 or newer; the library itself builds as C23. + +## The application cycle + +1. Open a display with `yasl_display_open(NULL, &spec)`. NULL creates a loop owned + by the display. Supply your own loop only when you need shared loop ownership. +2. Create a toplevel with a positive **logical-pixel** size and install callbacks. + Zero-initialize every option and callback struct. Callback tables are copied; + userdata must remain alive. Registration can call back synchronously. +3. Schedule the initial redraw. `draw` receives a borrowed target. Fill every + pixel with premultiplied `0xAARRGGBB`, then present that exact target, once. +4. Dispatch, drain input for every live surface queue, update application state, + and flush. Flush runs scheduled drawing and sends native requests. Dispatch + may also invoke callbacks, including drawing during native live resize. +5. Destroy popups before parents, surfaces before displays, and displays before + any supplied loop. NULL destroy/close calls do nothing; freed pointers are + invalid for every operation. + +```c +while (running) { + if (yasl_display_dispatch(display, -1) < 0) { + perror("yasl_display_dispatch"); + break; + } + struct yasl_input_event event; + while (yasl_surface_input_poll(surface, &event)) { + /* Read the union member selected by event.kind. */ + } + yasl_display_flush(display); +} +``` + +Zero timeout polls, positive timeout bounds the wait in milliseconds, and a +negative timeout waits for work. Undrained input makes dispatch return without +waiting. Use the return value only to detect failure, not to count input events. +If callbacks destroy surfaces, update your application registry immediately and +only poll surfaces that are still alive. Arrange display/loop cleanup after the +cycle ends; destroying them inside a callback is unsupported. + +See the [application guide](guide.md) for drawing, input, popups, timers, and +platform limits, or the comments in the [public header](../include/yasl/yasl.h) +for each function's contract. To build the searchable HTML reference, install +Doxygen and run `doxygen Doxyfile` from the repository root. Open +`build-docs/html/index.html`; Doxygen is not needed to build the library. diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..43a7a1e --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,298 @@ +# Application guide + +The contracts in [yasl.h](../include/yasl/yasl.h), [loop.h](../include/yasl/loop.h), +[timing.h](../include/yasl/timing.h), and [native.h](../include/yasl/native.h) are +the reference for individual calls. All examples here use the display's opening +thread, which must be the main thread on macOS. Userdata stays owned by the +application. Copy borrowed data before retaining it beyond its documented life. + +## Backend selection and capabilities + +Zero-initialize `yasl_display_spec` or pass NULL to select automatically. On +Linux, `WAYLAND_DISPLAY`, `WAYLAND_SOCKET`, or `XDG_SESSION_TYPE=wayland` makes +YASL try Wayland first; otherwise it tries X11 first. It falls back to the other +built backend if opening fails. On macOS it uses Cocoa. Explicit +`YASL_BACKEND_WAYLAND`, `YASL_BACKEND_X11`, or `YASL_BACKEND_COCOA` requests never +fall back. Query the result with `yasl_display_backend()`. + +Use `yasl_display_caps()` for optional behavior. A bit means backend/server +support, not that a device is attached or that the current input state allows +an operation. Always check the operation's return value too. + +| Capability | Meaning | Wayland | X11 | Cocoa | +| --- | --- | --- | --- | --- | +| `YASL_CAP_POPUPS` | Child popup surfaces | Yes, input grab required | Yes | Yes | +| `YASL_CAP_DRAG` | Surface-drag source and target events | Data device v3 | Yes | Yes | +| `YASL_CAP_DRAG_CARRY` | Carry a toplevel with a surface drag | Optional toplevel-drag protocol | Yes | Yes | +| `YASL_CAP_PLACE_WINDOW` | Place a window under the pointer | No | Yes | Yes | +| `YASL_CAP_PRIMARY_SELECTION` | Separate primary text selection | Optional primary-selection protocol | Yes | Named pasteboard emulation | +| `YASL_CAP_CSD` | Backend advertises client decoration support | Yes | No | Yes | +| `YASL_CAP_NATIVE_GRAPHICS` | Application-managed native drawables | No | No | Metal | +| `YASL_CAP_FRAME_PACING` | Display/compositor-driven drawing | Yes | No | Yes | +| `YASL_CAP_TABLET` | Tablet event translation | Optional tablet-v2 protocol | XInput 2 | Yes | + +This table describes the implementation, not universal operating-system +promises. Wayland protocols and XInput availability depend on the running +server. A capability does not guarantee every related action: Cocoa currently +returns false for interactive resize and window-menu requests even though +it advertises CSD. Check each result and provide an application fallback. + +## Geometry and scaling + +| Value | Units | +| --- | --- | +| Toplevel `yasl_surface_spec.size` | Logical pixels | +| `yasl_geometry.size`, framebuffer size | Device pixels | +| Pointer position, caret, window-menu position | Device pixels, relative to the surface | +| Damage rectangles | Device pixels, relative to the draw target | +| All popup fields, including `size` | Device pixels; anchor is relative to the parent | +| Drag image size, hotspot, carry/place offsets | Device pixels | +| `scale_120` | 120 = 1x, 180 = 1.5x, 240 = 2x | + +The origin is the top left, x increases right, and y increases down. Use +`yasl_surface_geometry()` for the current size and scale, and update cached +layout on `configure`. The native system may choose a different size from the +request. X11 currently reports unit scale; automatic output DPI scaling is not +implemented there. + +```c +struct yasl_geometry geometry = yasl_surface_geometry(surface); +int padding_px = yasl_scale_to_device(8.0, geometry.scale_120); +int logical_width = yasl_scale_to_logical(geometry.size.x, geometry.scale_120); +``` + +Scale conversion rounds to the nearest integer, with ties away from zero, +saturates out-of-range finite results, and returns zero for a zero scale. +`yasl_scale_to_device()` also returns zero for non-finite logical coordinates. + +## Drawing and pacing + +`yasl_surface_schedule_redraw()` coalesces requests. `yasl_display_flush()` +services them when the backend can draw. During a native resize, dispatch can +also draw synchronously. Avoid assuming callbacks occur only in flush. + +The CPU target is tightly packed premultiplied `0xAARRGGBB`. Row stride is +`target.size.x * sizeof(uint32_t)`. For example, opaque red is `0xffff0000`, +50% transparent red is approximately `0x80800000`, and transparent black is +`0x00000000`. The numeric format describes a 32-bit value, not a portable byte +sequence. Keep your application's durable content separately: a new target may +contain no previous frame contents. + +```c +static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *ud) +{ + (void)ud; + size_t count = (size_t)frame->target.size.x * frame->target.size.y; + for (size_t i = 0; i < count; i++) + frame->target.pixels[i] = 0xff306090; + struct yasl_damage_list damage = {.n = -1}; + if (!yasl_surface_present(surface, &frame->target, &damage)) { + /* Arrange application error handling after returning. */ + } +} +``` + +Present that exact target at most once during draw. Do not change its pointer, +size, or generation, free it, or use it after callback return or surface +destruction. A successful present consumes it. Invalid input returns false +without consuming it. `damage.n = -1` means full target; `0` means no damaged +rectangles; positive `n` uses the first `n` entries in `rects`. Extents must be +nonnegative, and the core clips them to the target. `bounds` is a reserved hint +and can be zero. Damage may reduce uploads, but every target must still contain +complete valid content; backends may upload all pixels. + +To animate, schedule again from draw. With `YASL_CAP_FRAME_PACING`, the backend +uses display/compositor signals to limit draws; tearing can bypass this. X11 +is unpaced: scheduling continuously will use CPU continuously. Use an application +timer to limit redraws there. Suspended/hidden windows need not draw at each +requested interval. + +`yasl_surface_timing()` reports estimates and their provenance. All timestamps +are monotonic nanoseconds. `YASL_TIMING_SUBMISSION` is CPU submission time, +`YASL_TIMING_FRAME_CALLBACK` is a compositor pacing signal, and only +`YASL_TIMING_PRESENTATION` confirms compositor presentation. `UNKNOWN` means no +sample. `refresh_ns` and `next_present_ns` remain estimates. Use +`yasl_surface_frame_time_ns(surface, yasl_loop_now_ns())` as a stable animation +clock; it does not establish actual scanout time. + +## Input, text, and payload lifetime + +Dispatch receives native input. `yasl_surface_input_poll()` only drains it and +never waits. Poll every live surface queue until empty. Wayland routes popup +pointer and keyboard events through the root parent's queue; inspect +`event.surface` to identify the recipient. Do not assume it equals the object +whose queue you polled. + +Read the union member selected by `event.kind`. The `reserved` field is internal +and must not be interpreted. Text, paste, and file-drop payloads are UTF-8 byte +strings, NUL-terminated; `len` excludes the NUL. They remain valid until the +next **successful** poll on the queue or queue destruction. Dispatch, flush, +and unsuccessful polls do not invalidate them. Copy data to keep it longer. + +Use `YASL_INPUT_TEXT` for document text insertion, including committed IME text. +It contains UTF-8 and can contain several characters. Key actions are for +commands and held-key state; releases and repeats have separate tags. A text +commit need not correspond to one key event, and a key need not produce text. + +`key.key` is a portable physical identity from +[keycodes.h](../include/yasl/keycodes.h), included by `<yasl/yasl.h>`. Names follow +US keyboard positions: `YASL_KEY_A` identifies the same position on a French +layout even though it types Q. Modifiers do not change this identity. Keypad +keys and left/right modifiers have distinct names. Unknown native keys report +`YASL_KEY_UNKNOWN`; `native_code` preserves their backend-specific identity +(Wayland evdev code, X11 server keycode, or Cocoa virtual keycode). + +`codepoint` and `shifted` are optional Unicode scalar labels for the active +layout without modifiers and with Shift. Zero means no single printable label, +including function keys, unavailable translations, and mappings that produce +multiple characters. Dead keys may have a spacing label or zero. These fields +are useful for displaying shortcuts or +choosing layout-sensitive commands; they are never document text. For example: + +```c +if (event.kind == YASL_INPUT_KEY && event.key.action == YASL_KEY_PRESS && + event.key.key == YASL_KEY_ESCAPE) { + running = false; +} +/* Insert event.text.text[0..event.text.len) only for YASL_INPUT_TEXT. */ +``` + +Wayland uses the supplied XKB layout and locale compose rules for ordinary text +and dead keys, with text-input-v3 for IME commits. Compose rules use `LC_ALL`, +`LC_CTYPE`, then `LANG`, falling back to `C.UTF-8`. X11 uses the X input method +when available; Cocoa uses AppKit text services. X11 input methods use the +application's `LC_CTYPE` locale. Initialize it before opening a display when +using locale-specific XIM, for example with `setlocale(LC_CTYPE, "")`; YASL does +not change the process locale. IME availability and system configuration still +determine which compositions work. Physical key events +remain available for commands; input methods may consume keys while composing. + +Pointer events use `YASL_INPUT_MOUSE`, with `device` distinguishing mouse, touch, +pen, and eraser. Press/release button 0 is primary/tip, 1 middle, and 2 secondary. +Track those transitions; motion/leave button values are informational. Pen +pressure is normalized to 0..65535, signed tilt is in degrees, and missing axes +are zero. Pressure-only changes can produce motion. Zero pressure alone does +not mean release. This interface does not expose simultaneous touch contacts. + +For `YASL_PTR_SCROLL`, read `mouse.scroll.x` and `.y`: fractional line offsets, +positive right and down, after system scroll preferences. Both axes may be +nonzero in one event. Preserve fractions and choose your application's own +pixels per line; one wheel detent normally gives one line. `button` is unused +for scroll. Wayland high-resolution wheel values take precedence over duplicate +discrete/raw descriptions. Smooth Wayland offsets and precise Cocoa offsets +use ten native units per line. X11 currently reports whole wheel steps, so it +does not provide the same smooth-scroll precision as the other backends. + +Cancel held keys, buttons, active strokes, and composition on `YASL_INPUT_RESET`, +focus loss, or pointer leave as appropriate to your application. RESET has no +union payload. It is emitted after input-queue allocation failure and certain +device interruptions; ignoring it can leave application input stuck. + +## Clipboard, file drops, and IME + +`yasl_display_copy()` copies a NUL-terminated UTF-8 string during the call. +`yasl_display_paste()` requests delivery to the original target as +`YASL_INPUT_PASTE`; destroying the target cancels delivery. There is no transfer +ID or error callback, so unavailable or failed transfers may produce no event. +Wayland selection offers can require a recent input serial. X11 currently does +not implement incremental (`INCR`) selection transfers and may reject large +transfers. X11 converts legacy `STRING` data between Latin-1 and UTF-8; it only +offers that legacy format when the copied text fits Latin-1. Malformed UTF-8 +clipboard transfers are discarded. Unsupported primary selection does nothing +and never aliases the clipboard. Cocoa uses a YASL named pasteboard to emulate primary selection; +this is not a desktop-wide macOS select-to-copy convention. + +External file drag hover uses the surface `drop` callback; actual file URLs +arrive as `YASL_INPUT_DROP_FILES`. `files` is a `text/uri-list` string separated by +CRLF, not a list of native paths. Parse URL encoding, skip blank/comment lines, +and decide which schemes/hosts your application accepts before opening files. + +Use `yasl_surface_ime_preedit()` to draw the uncommitted composition. The borrowed +pointer expires on the next dispatch or surface destruction; copy to keep it. +Set the candidate-window caret with `yasl_surface_set_ime_caret()` in device +pixels. X11 has no inline preedit. Cocoa supplies preedit text but currently no +cursor range. On Wayland, `yasl_surface_ime_preedit_cursor()` returns UTF-8 byte +offsets when a range is available. A false result leaves outputs unchanged. + +## Popups and surface drags + +Create popups from a live parent, normally in response to input. All fields in +`yasl_popup_spec` use device pixels. `size` includes transparent margins; +`content_offset` and `content_size` describe the actual content rectangle used +for positioning. A zero content-size axis extends to the corresponding size +edge. `beside = true` prefers the anchor's right edge; false prefers below. +Placement may flip or slide to stay on screen. Wayland requires a recent input +serial to grab a popup, and older protocols may reject repositioning. Destroy +children before parents. The close callback requests application destruction; +it does not automatically free the popup. + +The surface `drag` callback handles a YASL surface drag; `drop` handles external +data hover. `yasl_display_drag_start()` is intended for window/tab tear-off +workflows, not arbitrary MIME data sources. Keep transferred application state +in your own registry. Start from a recent pointer press, and check the boolean +result even when `YASL_CAP_DRAG` is present. Supply an optional copied image and +completion listener. One active drag is supported per display. A successful +start calls a non-NULL `end` exactly once, including explicit cancel or display +close; a failed start never does. `DROPPED` does not prove that another +application accepted your application object. + +Where `YASL_CAP_DRAG_CARRY` is present, `yasl_surface_drag_carry()` can attach a +toplevel to the active drag. Otherwise an image can represent it. With +`YASL_CAP_PLACE_WINDOW`, `yasl_surface_place_under_pointer()` requests placement +relative to the pointer. These calls may fail due to current input/drag state. +Completion can run synchronously during cancel/close; keep listener userdata +alive until then and do not destroy the display recursively. + +## Timers and file descriptors + +Include `<yasl/loop.h>`. Use `yasl_display_loop(display)` for application timers +so they participate in display dispatch. Intervals are nanoseconds; the +`YASL_MS_TO_NS(ms)` macro converts a nonnegative integer millisecond value. + +```c +static uint64_t tick(void *ud, yasl_timer_id id, uint64_t interval_ns) +{ + (void)id; + yasl_surface_schedule_redraw(ud); + return interval_ns; /* Return zero for a one-shot timer. */ +} +/* Check zero for failure. This timer is canceled with the surface. */ +yasl_timer_id timer = yasl_surface_add_timer(surface, YASL_MS_TO_NS(16), tick, surface); +``` + +A timer callback receives the scheduled interval, not actual elapsed time. A +nonzero return repeats/reschedules; zero retires it. Missed periods coalesce. +Timers can add/delete timers, including themselves. Loop timers end when retired, +deleted, or the loop is destroyed; surface timers also end on surface destruction. +Userdata remains application-owned. Delete surface timers with +`yasl_surface_del_timer()` and ordinary timers with `yasl_loop_del_timer()`. + +File watches use `<poll.h>` masks. `yasl_loop_add_fd()` returns a positive watch +ID or -1. Its callback receives `revents`, including error/hangup flags; its +integer return is ignored. Consume readiness or disable/delete the watch. +The loop never closes application file descriptors: delete the watch before +closing its descriptor. Ready callbacks may add or remove watches. Do not call +`yasl_loop_step()` or `yasl_loop_run()` recursively. + +Cocoa dispatch waits for native events and checks the loop nonblockingly +afterward. An application FD alone does not currently wake an indefinite Cocoa +dispatch; use a bounded timeout when integrating such sources. `loop_kick()` +signals the loop pipe but is not a portable cross-thread event-posting API. + +## Native interoperability + +Portable CPU drawing needs no native headers. Opt into `<yasl/native.h>` and +`<yasl/native/wayland.h>`, `<yasl/native/x11.h>`, or `<yasl/native/cocoa.h>` when +integrating a platform API. Typed headers and functions are installed only for +built backends. Accessors return borrowed handles and zero/NULL for the wrong +backend. Do not pass freed objects, destroy borrowed handles, independently +dispatch native connections, or change surface roles and buffer ownership. + +Application-managed native drawing currently supports Cocoa/Metal. Use +`yasl_surface_create_native()` with a non-NULL Metal device, which YASL retains. +During draw, query `yasl_surface_get_native_frame()` for a borrowed drawable, +encode and present with your renderer, then call `yasl_surface_present()` to +record submission. The drawable expires on successful present, callback return, +or surface destruction. Do not infer GPU completion from the boolean result. +Other backends return NULL with `errno = ENOTSUP` for native creation; having a +native window handle does not imply this rendering path is supported. diff --git a/docs/migrating.md b/docs/migrating.md new file mode 100644 index 0000000..d224cd4 --- /dev/null +++ b/docs/migrating.md @@ -0,0 +1,40 @@ +# Migrating pre-release applications + +YASL 0.1 has no stable source or binary compatibility promise. Rebuild all +consumers against the matching installed headers and library after updating. +The following changes replace backend-specific input fields with a common +contract. See the [application guide](guide.md) for the full input workflow. + +## Keyboard events + +| Previous use | Replacement | +| --- | --- | +| Linux keysym or Cocoa virtual keycode in `key.key` | Portable physical `YASL_KEY_*` identity | +| `key.base` | `key.native_code`, with explicit backend-specific encoding | +| `key.keypad` | Distinct `YASL_KEY_KP_*` identities | +| Advisory `key.text` character | `YASL_INPUT_TEXT` UTF-8 payload for insertion | +| Layout label from a keysym | Optional `key.codepoint` and `key.shifted` Unicode scalars | + +Replace magic numbers and X11 symbols with named keys. For example, a quit +command checks `key.key == YASL_KEY_ESCAPE` on a press. `YASL_KEY_A` means the +US A position on every layout; use layout labels when a command should follow +the printed letter instead. Do not cast key identities to characters. Keypad +Enter and ordinary Enter now have distinct identities without a separate flag. + +Text comes only from `YASL_INPUT_TEXT`. Handle its byte length, copy it when +retaining it after the next successful poll, and allow multiple characters per +commit. Cocoa sends key events through its text input manager; Wayland emits +ordinary XKB text and locale compose results in addition to IME commits. + +## Scroll events + +Replace `scroll_lines`, `scroll_delta`, and scroll button numbers with +`mouse.scroll.x` and `.y` when `mouse.kind == YASL_PTR_SCROLL`. These double +values are fractional line offsets, positive right/down on every backend. +Do not infer scroll direction from `button`. One event may include both axes. +Remove backend-specific sign inversions and whole-line casts; multiply the +offset by your application's preferred pixels per line instead. + +X11 still supplies whole wheel steps. Wayland high-resolution wheels and smooth +offsets, and Cocoa precise scrolling, preserve fractions. Device acceleration +and system preferences still affect the native offsets. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..d01b82c --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,156 @@ +# Testing and examples + +Configure isolated Linux display-server integration tests with Weston and +Xwayland installed: + +```sh +meson setup build-test -Dintegration_tests=true +meson test -C build-test --print-errorlogs +``` + +The harness starts and cleans up its own servers. It checks explicit requests, +automatic selection, fallback, both backends in one process, frame lifetimes, +callback copying, clipboard ownership, and timers. It also runs the beginner +and tablet examples on both backends. On macOS the option enables native window, +input ownership, keyboard/text/scroll, cursor, tablet, and example tests; these +require a desktop session. Linux results do not verify Cocoa behavior. + +For memory/undefined-behavior checks use a separate build: + +```sh +meson setup build-sanitize -Db_sanitize=address,undefined -Dintegration_tests=true +meson test -C build-sanitize --print-errorlogs +``` + +Default tests need no desktop connection. C++ header coverage is built when a +C++ compiler is available. On Linux and macOS, the shared-export test ensures +only installed API declarations are exported. Test disabled-backend configurations separately with +`-Dwayland=disabled` or `-Dx11=disabled`; the combined integration harness needs +both backends. + +Keyboard tests check physical identities, distinct keypad/modifier keys, layout +labels, Shift/Caps Lock, shortcut text suppression, AltGr, dead-key composition, +repeat, and composition reset. The X11 integration test changes and restores +the isolated server's keymap to verify that labels change while physical keys +retain their identity. The X11 text fallback is also checked without an input +method, including Latin-1, Cyrillic, and non-BMP characters encoded as UTF-8. +Scroll tests cover both axes, fractional Wayland offsets, +duplicate protocol representations, and X11 core/XInput wheel directions. +Cocoa integration tests cover UTF-16 labels, modifier-only events, native text +commit routing, and diagonal precise scrolling. Native IME interaction and +hardware gestures still need testing on the target desktop. +Clipboard tests cover Latin-1 interoperability, empty transfers, and rejection +of malformed UTF-8 on Linux. + +## Cocoa validation + +On macOS 14 or newer, use a logged-in desktop session with a Metal-capable +device. Configure `-Dintegration_tests=true`, compile, and run the full suite. +Cross-compiling with an Apple SDK checks compilation and linking; run +`meson test -C build-macos public-exports` to check the dylib's exports on the +build machine. A cross file should provide an `nm` that can read Mach-O, such +as `llvm-nm`. These checks do not execute the native window and input tests. + +To move an already compiled, unsanitized Cocoa suite to another Mac without +rebuilding it: + +```sh +python3 tests/helpers/package_cocoa_tests.py build-macos cocoa-tests.tar.gz +``` + +On the matching Mac, extract the archive and run: + +```sh +tar -xzf cocoa-tests.tar.gz +python3 yasl-cocoa-tests/run.py +``` + +The bundle includes the dylib, every executable test registered by Meson, and +the license. The build-machine export check is separate. The runner checks file +hashes, enforces each test's timeout, saves output under `logs/`, and writes +`results.json`. A nonzero exit means validation failed. `--list` lists the +bundled tests without running them. Use Python 3.8 or newer and a bundle matching +its architecture; Apple Silicon uses `aarch64`, Intel uses `x86_64`. + +## 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 `<yasl/yasl.h>` 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. + +The example uses portable physical keys: C and Space clear, Escape exits. +Letter names describe US positions, so the clear key follows the C position +when the user selects another layout. + +`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. + +## Benchmarks + +`yasl-benchmark` measures queue, timer, and surface-operation costs. Results +depend on the build, backend, and display server; they do not measure confirmed +screen presentation latency. + +```sh +# Run via meson test runner +meson test -C build --benchmark --verbose + +# Or invoke the executable directly +ninja -C build tests/yasl-benchmark +./build/tests/yasl-benchmark +``` + diff --git a/examples/hello.c b/examples/hello.c new file mode 100644 index 0000000..67ac88b --- /dev/null +++ b/examples/hello.c @@ -0,0 +1,102 @@ +/* A complete CPU-rendered window. Build instructions: docs/getting-started.md. */ +#include <yasl/yasl.h> + +#include <stdio.h> +#include <string.h> + +struct app { + bool running; + bool failed; + bool smoke_test; +}; + +static void quit(void *ud) +{ + ((struct app *)ud)->running = false; +} + +static void lost(void *ud) +{ + struct app *app = ud; + app->failed = true; + app->running = false; +} + +static void close_window(struct yasl_surface *surface, void *ud) +{ + (void)surface; + quit(ud); +} + +static void configure(struct yasl_surface *surface, struct yasl_geometry geometry, void *ud) +{ + (void)geometry; + (void)ud; + yasl_surface_schedule_redraw(surface); +} + +static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *ud) +{ + struct app *app = ud; + size_t count = (size_t)frame->target.size.x * frame->target.size.y; + for (size_t i = 0; i < count; i++) + frame->target.pixels[i] = 0xff306090; /* Opaque premultiplied ARGB. */ + + struct yasl_damage_list damage = {.n = -1}; + if (!yasl_surface_present(surface, &frame->target, &damage)) { + fprintf(stderr, "Could not present the draw target\n"); + app->failed = true; + app->running = false; + } + if (app->smoke_test) app->running = false; +} + +int main(int argc, char **argv) +{ + struct app app = {.running = true}; + if (argc == 2 && strcmp(argv[1], "--smoke-test") == 0) + app.smoke_test = true; + else if (argc != 1) { + fprintf(stderr, "Usage: %s [--smoke-test]\n", argv[0]); + return 1; + } + + struct yasl_display_cbs display_callbacks = {.quit = quit, .lost = lost}; + struct yasl_display_spec display_spec = { + .app_id = "org.example.hello", + .cbs = &display_callbacks, + .ud = &app, + }; + struct yasl_display *display = yasl_display_open(NULL, &display_spec); + if (!display) { + perror("yasl_display_open"); + return 1; + } + struct yasl_surface_spec spec = {.title = "Hello YASL", .size = {640, 480}}; + struct yasl_surface *surface = yasl_surface_create_toplevel(display, &spec); + if (!surface) { + perror("yasl_surface_create_toplevel"); + yasl_display_close(display); + return 1; + } + struct yasl_surface_cbs callbacks = { + .draw = draw, .configure = configure, .close = close_window, + }; + yasl_surface_set_callbacks(surface, &callbacks, &app); + yasl_surface_schedule_redraw(surface); + + while (app.running) { + if (yasl_display_dispatch(display, -1) < 0) { + perror("yasl_display_dispatch"); + app.failed = true; + break; + } + /* Drain even unused input so queued events do not cause a busy loop. */ + struct yasl_input_event event; + while (yasl_surface_input_poll(surface, &event)) {} + if (app.running) yasl_display_flush(display); + } + yasl_surface_destroy(surface); + yasl_display_close(display); + return app.failed ? 1 : 0; +} diff --git a/examples/simple_window.c b/examples/simple_window.c index 40a7c25..85db04a 100644 --- a/examples/simple_window.c +++ b/examples/simple_window.c @@ -152,9 +152,9 @@ int main(void) while (yasl_surface_input_poll(s, &ev)) { if (ev.kind == YASL_INPUT_KEY) { if (ev.key.action == YASL_KEY_PRESS) { - if (ev.key.key == 0xff1b) { /* Escape */ + if (ev.key.key == YASL_KEY_ESCAPE) { /* Escape */ running = false; - } else if (ev.key.key == ' ' || ev.key.key == 0xff0d) { /* Space or Return */ + } else if (ev.key.key == YASL_KEY_SPACE || ev.key.key == YASL_KEY_ENTER) { /* Space or Return */ color_theme++; yasl_surface_schedule_redraw(s); } diff --git a/examples/tablet.c b/examples/tablet.c index 4d7a8bd..0aae370 100644 --- a/examples/tablet.c +++ b/examples/tablet.c @@ -148,8 +148,8 @@ static void input(struct app *app, const struct yasl_input_event *event) (event->kind == YASL_INPUT_FOCUS && !event->focus.focused)) { cancel_stroke(app); } else if (event->kind == YASL_INPUT_KEY && event->key.action == YASL_KEY_PRESS) { - if (event->key.key == 0xff1b) app->running = false; - if (event->key.key == 'c' || event->key.key == 'C' || event->key.key == ' ') + if (event->key.key == YASL_KEY_ESCAPE) app->running = false; + if (event->key.key == YASL_KEY_C || event->key.key == YASL_KEY_SPACE) clear_canvas(app); } else if (event->kind == YASL_INPUT_MOUSE) { const struct yasl_mouse_event *pointer = &event->mouse; diff --git a/include/yasl/keycodes.h b/include/yasl/keycodes.h new file mode 100644 index 0000000..7586945 --- /dev/null +++ b/include/yasl/keycodes.h @@ -0,0 +1,149 @@ +/** + * @file + * Portable physical keyboard identities, included by yasl/yasl.h. + * Letter/punctuation names describe positions on a US keyboard, regardless of + * active layout or modifiers. Use YASL_INPUT_TEXT for text and codepoint/shifted + * in yasl_key_event for layout labels. These values are neither Unicode nor + * native scancodes; do not derive a character from a key enumerator. + */ +#ifndef YASL_KEYCODES_H +#define YASL_KEYCODES_H + +#include <stdint.h> + +/** Physical keys. Unrecognized native keys report YASL_KEY_UNKNOWN. */ +enum yasl_key : uint32_t { + YASL_KEY_UNKNOWN = 0x000, /**< No portable identity; native_code may still identify the key. */ + YASL_KEY_SPACE = 0x020, /**< Space. */ + YASL_KEY_APOSTROPHE = 0x027, /**< Apostrophe. */ + YASL_KEY_COMMA = 0x02c, /**< Comma. */ + YASL_KEY_MINUS = 0x02d, /**< Minus. */ + YASL_KEY_PERIOD = 0x02e, /**< Period. */ + YASL_KEY_SLASH = 0x02f, /**< Slash. */ + YASL_KEY_0 = 0x030, /**< Physical 0 key. */ + YASL_KEY_1 = 0x031, /**< Physical 1 key. */ + YASL_KEY_2 = 0x032, /**< Physical 2 key. */ + YASL_KEY_3 = 0x033, /**< Physical 3 key. */ + YASL_KEY_4 = 0x034, /**< Physical 4 key. */ + YASL_KEY_5 = 0x035, /**< Physical 5 key. */ + YASL_KEY_6 = 0x036, /**< Physical 6 key. */ + YASL_KEY_7 = 0x037, /**< Physical 7 key. */ + YASL_KEY_8 = 0x038, /**< Physical 8 key. */ + YASL_KEY_9 = 0x039, /**< Physical 9 key. */ + YASL_KEY_SEMICOLON = 0x03b, /**< Semicolon. */ + YASL_KEY_EQUAL = 0x03d, /**< Equal. */ + YASL_KEY_A = 0x041, /**< Physical US A position; independent of layout and modifiers. */ + YASL_KEY_B = 0x042, /**< Physical US B position; independent of layout and modifiers. */ + YASL_KEY_C = 0x043, /**< Physical US C position; independent of layout and modifiers. */ + YASL_KEY_D = 0x044, /**< Physical US D position; independent of layout and modifiers. */ + YASL_KEY_E = 0x045, /**< Physical US E position; independent of layout and modifiers. */ + YASL_KEY_F = 0x046, /**< Physical US F position; independent of layout and modifiers. */ + YASL_KEY_G = 0x047, /**< Physical US G position; independent of layout and modifiers. */ + YASL_KEY_H = 0x048, /**< Physical US H position; independent of layout and modifiers. */ + YASL_KEY_I = 0x049, /**< Physical US I position; independent of layout and modifiers. */ + YASL_KEY_J = 0x04a, /**< Physical US J position; independent of layout and modifiers. */ + YASL_KEY_K = 0x04b, /**< Physical US K position; independent of layout and modifiers. */ + YASL_KEY_L = 0x04c, /**< Physical US L position; independent of layout and modifiers. */ + YASL_KEY_M = 0x04d, /**< Physical US M position; independent of layout and modifiers. */ + YASL_KEY_N = 0x04e, /**< Physical US N position; independent of layout and modifiers. */ + YASL_KEY_O = 0x04f, /**< Physical US O position; independent of layout and modifiers. */ + YASL_KEY_P = 0x050, /**< Physical US P position; independent of layout and modifiers. */ + YASL_KEY_Q = 0x051, /**< Physical US Q position; independent of layout and modifiers. */ + YASL_KEY_R = 0x052, /**< Physical US R position; independent of layout and modifiers. */ + YASL_KEY_S = 0x053, /**< Physical US S position; independent of layout and modifiers. */ + YASL_KEY_T = 0x054, /**< Physical US T position; independent of layout and modifiers. */ + YASL_KEY_U = 0x055, /**< Physical US U position; independent of layout and modifiers. */ + YASL_KEY_V = 0x056, /**< Physical US V position; independent of layout and modifiers. */ + YASL_KEY_W = 0x057, /**< Physical US W position; independent of layout and modifiers. */ + YASL_KEY_X = 0x058, /**< Physical US X position; independent of layout and modifiers. */ + YASL_KEY_Y = 0x059, /**< Physical US Y position; independent of layout and modifiers. */ + YASL_KEY_Z = 0x05a, /**< Physical US Z position; independent of layout and modifiers. */ + YASL_KEY_LEFT_BRACKET = 0x05b, /**< Left Bracket. */ + YASL_KEY_BACKSLASH = 0x05c, /**< Backslash. */ + YASL_KEY_RIGHT_BRACKET = 0x05d, /**< Right Bracket. */ + YASL_KEY_GRAVE = 0x060, /**< Grave. */ + YASL_KEY_ESCAPE = 0x100, /**< Escape. */ + YASL_KEY_ENTER = 0x101, /**< Enter. */ + YASL_KEY_TAB = 0x102, /**< Tab. */ + YASL_KEY_BACKSPACE = 0x103, /**< Backspace. */ + YASL_KEY_INSERT = 0x104, /**< Insert. */ + YASL_KEY_DELETE = 0x105, /**< Delete. */ + YASL_KEY_RIGHT = 0x106, /**< Right. */ + YASL_KEY_LEFT = 0x107, /**< Left. */ + YASL_KEY_DOWN = 0x108, /**< Down. */ + YASL_KEY_UP = 0x109, /**< Up. */ + YASL_KEY_PAGE_UP = 0x10a, /**< Page Up. */ + YASL_KEY_PAGE_DOWN = 0x10b, /**< Page Down. */ + YASL_KEY_HOME = 0x10c, /**< Home. */ + YASL_KEY_END = 0x10d, /**< End. */ + YASL_KEY_CAPS_LOCK = 0x10e, /**< Caps Lock. */ + YASL_KEY_SCROLL_LOCK = 0x10f, /**< Scroll Lock. */ + YASL_KEY_NUM_LOCK = 0x110, /**< Num Lock. */ + YASL_KEY_PRINT_SCREEN = 0x111, /**< Print Screen. */ + YASL_KEY_PAUSE = 0x112, /**< Pause. */ + YASL_KEY_ISO_BACKSLASH = 0x113, /**< Iso Backslash. */ + YASL_KEY_YEN = 0x114, /**< Yen. */ + YASL_KEY_RO = 0x115, /**< Ro. */ + YASL_KEY_KANA = 0x116, /**< Kana. */ + YASL_KEY_EISU = 0x117, /**< Eisu. */ + YASL_KEY_CONVERT = 0x118, /**< Convert. */ + YASL_KEY_NONCONVERT = 0x119, /**< Nonconvert. */ + YASL_KEY_F1 = 0x120, /**< Function key F1. */ + YASL_KEY_F2 = 0x121, /**< Function key F2. */ + YASL_KEY_F3 = 0x122, /**< Function key F3. */ + YASL_KEY_F4 = 0x123, /**< Function key F4. */ + YASL_KEY_F5 = 0x124, /**< Function key F5. */ + YASL_KEY_F6 = 0x125, /**< Function key F6. */ + YASL_KEY_F7 = 0x126, /**< Function key F7. */ + YASL_KEY_F8 = 0x127, /**< Function key F8. */ + YASL_KEY_F9 = 0x128, /**< Function key F9. */ + YASL_KEY_F10 = 0x129, /**< Function key F10. */ + YASL_KEY_F11 = 0x12a, /**< Function key F11. */ + YASL_KEY_F12 = 0x12b, /**< Function key F12. */ + YASL_KEY_F13 = 0x12c, /**< Function key F13. */ + YASL_KEY_F14 = 0x12d, /**< Function key F14. */ + YASL_KEY_F15 = 0x12e, /**< Function key F15. */ + YASL_KEY_F16 = 0x12f, /**< Function key F16. */ + YASL_KEY_F17 = 0x130, /**< Function key F17. */ + YASL_KEY_F18 = 0x131, /**< Function key F18. */ + YASL_KEY_F19 = 0x132, /**< Function key F19. */ + YASL_KEY_F20 = 0x133, /**< Function key F20. */ + YASL_KEY_F21 = 0x134, /**< Function key F21. */ + YASL_KEY_F22 = 0x135, /**< Function key F22. */ + YASL_KEY_F23 = 0x136, /**< Function key F23. */ + YASL_KEY_F24 = 0x137, /**< Function key F24. */ + YASL_KEY_F25 = 0x138, /**< Function key F25. */ + YASL_KEY_KP_0 = 0x140, /**< Numeric keypad 0. */ + YASL_KEY_KP_1 = 0x141, /**< Numeric keypad 1. */ + YASL_KEY_KP_2 = 0x142, /**< Numeric keypad 2. */ + YASL_KEY_KP_3 = 0x143, /**< Numeric keypad 3. */ + YASL_KEY_KP_4 = 0x144, /**< Numeric keypad 4. */ + YASL_KEY_KP_5 = 0x145, /**< Numeric keypad 5. */ + YASL_KEY_KP_6 = 0x146, /**< Numeric keypad 6. */ + YASL_KEY_KP_7 = 0x147, /**< Numeric keypad 7. */ + YASL_KEY_KP_8 = 0x148, /**< Numeric keypad 8. */ + YASL_KEY_KP_9 = 0x149, /**< Numeric keypad 9. */ + YASL_KEY_KP_DECIMAL = 0x14a, /**< Numeric keypad decimal. */ + YASL_KEY_KP_DIVIDE = 0x14b, /**< Numeric keypad divide. */ + YASL_KEY_KP_MULTIPLY = 0x14c, /**< Numeric keypad multiply. */ + YASL_KEY_KP_SUBTRACT = 0x14d, /**< Numeric keypad subtract. */ + YASL_KEY_KP_ADD = 0x14e, /**< Numeric keypad add. */ + YASL_KEY_KP_ENTER = 0x14f, /**< Numeric keypad enter. */ + YASL_KEY_KP_EQUAL = 0x150, /**< Numeric keypad equal. */ + YASL_KEY_KP_COMMA = 0x151, /**< Numeric keypad comma. */ + YASL_KEY_KP_CLEAR = 0x152, /**< Numeric keypad clear. */ + YASL_KEY_LEFT_SHIFT = 0x160, /**< Left Shift. */ + YASL_KEY_LEFT_CONTROL = 0x161, /**< Left Control. */ + YASL_KEY_LEFT_ALT = 0x162, /**< Left Alt. */ + YASL_KEY_LEFT_SUPER = 0x163, /**< Left Super. */ + YASL_KEY_RIGHT_SHIFT = 0x164, /**< Right Shift. */ + YASL_KEY_RIGHT_CONTROL = 0x165, /**< Right Control. */ + YASL_KEY_RIGHT_ALT = 0x166, /**< Right Alt. */ + YASL_KEY_RIGHT_SUPER = 0x167, /**< Right Super. */ + YASL_KEY_MENU = 0x168, /**< Menu. */ + YASL_KEY_VOLUME_UP = 0x169, /**< Volume Up. */ + YASL_KEY_VOLUME_DOWN = 0x16a, /**< Volume Down. */ + YASL_KEY_MUTE = 0x16b, /**< Mute. */ +}; + +#endif /* YASL_KEYCODES_H */ diff --git a/include/yasl/loop.h b/include/yasl/loop.h index a65fa12..9faa8f7 100644 --- a/include/yasl/loop.h +++ b/include/yasl/loop.h @@ -1,3 +1,14 @@ +/** + * @file + * Optional event loop, file watches, and timers. + * + * Use the loop's owning thread for all calls and callbacks, except + * yasl_loop_now_ns(). A display borrows a supplied loop. For window applications, + * drive yasl_display_dispatch(), drain input, then yasl_display_flush(); the + * standalone loop_run() function does not replace this cycle. Timer intervals are + * nanoseconds; timeout_ms arguments are milliseconds. Do not recursively step/run + * or destroy a loop from a callback. + */ #ifndef YASL_LOOP_H #define YASL_LOOP_H @@ -10,33 +21,139 @@ extern "C" { /* Optional event loop. Use the display's loop when adding application timers. * A step waits at most timeout_ms: zero polls, a negative value waits indefinitely. * Calls and callbacks use the loop's owning thread. */ +/** + * Create an owned standalone file-descriptor and timer loop. + * @return A loop to destroy with yasl_loop_destroy(), or NULL on allocation failure. + * Use on one owning thread. Passing it to yasl_display_open() only lends it to + * the display; the caller retains ownership. + */ YASL_API struct yasl_loop *yasl_loop_create(void); +/** + * Release a loop, its watches, and its timers. + * @param l Loop, or NULL for no action. + * Close displays borrowing this loop first. Must not run during a loop callback + * or an active step/run. Watched file descriptors are not closed. + */ YASL_API void yasl_loop_destroy(struct yasl_loop *l); +/** + * Step a standalone loop until yasl_loop_quit() is called. + * @param l Loop. + * @return Zero after quit, or -1 on failure. + * For a window application, use a dispatch, input-poll, flush cycle instead; + * loop_run alone does not perform that full cycle on every backend. + */ YASL_API int yasl_loop_run(struct yasl_loop *l); +/** + * Wait for file-descriptor readiness or a timer deadline and run callbacks. + * @param l Loop. + * @param timeout_ms Maximum wait: zero polls, negative waits indefinitely. + * @return Number of callbacks handled, or -1 on failure. + * Timer deadlines shorten the wait. Callbacks can add/delete sources, including + * themselves. Do not recursively step/run this loop. + */ YASL_API int yasl_loop_step(struct yasl_loop *l, int timeout_ms); +/** + * Ask the currently running yasl_loop_run() to return after this step. + * @param l Loop, or NULL for no action. + * Call on the owning thread, usually from a callback. + */ YASL_API void yasl_loop_quit(struct yasl_loop *l); +/** + * Signal the loop's wake pipe without dispatching callbacks. + * @param l Loop, or NULL for no action. + * Multiple signals may coalesce. This does not schedule a redraw or enqueue an + * event, and it does not provide a cross-thread application messaging contract. + */ YASL_API void yasl_loop_kick(struct yasl_loop *l); +/** + * Read the monotonic clock used by YASL timers and timing results. + * @return Nanoseconds from CLOCK_MONOTONIC, unrelated to wall-clock time. + * May be called from any thread. + */ YASL_API uint64_t yasl_loop_now_ns(void); +/** + * Get the loop used for a display's file watches and application timers. + * @param d Display, or NULL. + * @return Borrowed loop, or NULL. Do not destroy a display-owned loop yourself. + */ YASL_API struct yasl_loop *yasl_display_loop(struct yasl_display *d); +/** + * Register a borrowed file descriptor for poll-style readiness. + * @param l Loop. + * @param fd Open file descriptor; it remains owned by the caller. + * @param events Bitmask from <poll.h>, for example POLLIN or POLLOUT. + * @param fn Callback receiving poll revents (including errors/hangup); return value is ignored. + * @param ud Borrowed userdata until watch removal or loop destruction. + * @return Positive watch ID, or -1 on failure. + * Delete the watch before closing fd. The callback must consume readiness or + * change/remove its watch to avoid repeated immediate wakeups. + */ YASL_API int yasl_loop_add_fd(struct yasl_loop *l, int fd, short events, int (*fn)(int fd, short revents, void *ud), void *ud); +/** + * Remove a file watch without closing its descriptor. + * @param l Loop. + * @param id Watch ID returned by yasl_loop_add_fd(). + * @return Zero if removed, or -1 for an invalid/missing watch. + */ YASL_API int yasl_loop_del_fd(struct yasl_loop *l, int id); +/** + * Replace a watch's poll event mask. + * @param l Loop. + * @param id Watch ID. + * @param events New <poll.h> mask; zero disables requested readiness (errors may still arrive). + * @return Zero if updated, or -1 for an invalid/missing watch. + */ YASL_API int yasl_loop_set_fd_events(struct yasl_loop *l, int id, short events); /* Timers use nanoseconds. Return the next interval to repeat/reschedule, or zero * to remove the timer. A zero ID indicates failure. Loop timers live until they * stop, are deleted, or the loop is destroyed. Surface timers are also canceled * when their surface is destroyed. */ +/** Timer identity scoped to its loop. Zero is invalid; do not reuse a retired ID. */ typedef uint32_t yasl_timer_id; +/** Timer callback. interval_ns is the last scheduled delay; return the next delay or zero to stop. */ typedef uint64_t (*yasl_timer_cb)(void *ud, yasl_timer_id id, uint64_t interval_ns); +/** Convert a nonnegative integer millisecond value to nanoseconds; avoid overflow. */ #define YASL_MS_TO_NS(ms) ((uint64_t)(ms) * 1000000ull) +/** + * Schedule a timer on a loop. + * @param l Loop. + * @param interval_ns Nonzero delay in monotonic nanoseconds before first firing. + * @param cb Required callback; returns a new nonzero interval to repeat, or zero to stop. + * @param ud Borrowed userdata until the timer stops, is deleted, or the loop is destroyed. + * @return Nonzero timer ID, or zero for invalid arguments or allocation failure. + * Repeating timers coalesce missed deadlines; do not use them to count elapsed + * wall time. The callback receives the last scheduled interval, not elapsed time. + */ YASL_API yasl_timer_id yasl_loop_add_timer(struct yasl_loop *l, uint64_t interval_ns, yasl_timer_cb cb, void *ud); +/** + * Cancel a loop timer, including from its own callback. + * @param l Loop. + * @param id Timer ID. + * @return true if an armed timer was removed, false if invalid or already retired. + */ YASL_API bool yasl_loop_del_timer(struct yasl_loop *l, yasl_timer_id id); +/** + * Schedule a timer canceled automatically on surface destruction. + * @param s Surface whose display loop will run the timer. + * @param interval_ns Nonzero initial delay in nanoseconds. + * @param cb Required timer callback, with the same rules as yasl_loop_add_timer(). + * @param ud Borrowed userdata until the timer ends or the surface is destroyed. + * @return Nonzero timer ID, or zero on failure. + * The surface does not own userdata. Cancel with yasl_surface_del_timer(). + */ YASL_API yasl_timer_id yasl_surface_add_timer(struct yasl_surface *s, uint64_t interval_ns, yasl_timer_cb cb, void *ud); +/** + * Cancel a timer registered through yasl_surface_add_timer(). + * @param s Owning surface. + * @param id Timer ID. + * @return true if still armed and removed; false if unknown or already retired. + */ YASL_API bool yasl_surface_del_timer(struct yasl_surface *s, yasl_timer_id id); #ifdef __cplusplus diff --git a/include/yasl/native.h b/include/yasl/native.h index f7e3020..d65f8d3 100644 --- a/include/yasl/native.h +++ b/include/yasl/native.h @@ -1,3 +1,12 @@ +/** + * @file + * Optional native handles and application-managed rendering. + * + * These extensions follow the core thread and lifetime rules. Handles are borrowed; + * never destroy them or dispatch their native connection independently. Typed + * backend accessors live in the yasl/native headers and are installed only for built + * backends. Application-managed drawing currently supports Cocoa/Metal only. + */ #ifndef YASL_NATIVE_H #define YASL_NATIVE_H @@ -15,25 +24,61 @@ extern "C" { * X11 Display * Window (cast through uintptr_t) * Cocoa NSApplication * NSWindow * (view: window.contentView) */ +/** + * Get a borrowed, backend-specific display handle. + * @param d Display, or NULL. + * @return Native handle, or NULL. Inspect yasl_display_backend() before casting. + * Prefer a typed accessor from yasl/native/wayland.h, x11.h, or cocoa.h. + * The handle expires on display close; do not close or dispatch it independently. + */ YASL_API void *yasl_display_get_native_handle(struct yasl_display *d); +/** + * Get a borrowed, backend-specific surface handle. + * @param s Surface, or NULL. + * @return Native handle, or NULL. X11 encodes a Window through uintptr_t. + * Prefer typed accessors. The handle expires on surface destruction. Do not + * change native ownership, event masks, buffer attachment, or surface roles. + */ YASL_API void *yasl_surface_get_native_handle(struct yasl_surface *s); /* Create a surface for application-managed native rendering. graphics_device * must be non-NULL; currently an id<MTLDevice> on Cocoa, retained by the surface. * Other backends return NULL with errno=ENOTSUP. CPU rendering uses the ordinary * yasl_surface_create_toplevel() and requires no native device. */ +/** + * Create a toplevel for application-managed native rendering. + * @param d Display with YASL_CAP_NATIVE_GRAPHICS. + * @param spec Copied toplevel options, with logical-pixel size. + * @param graphics_device Required native graphics device; currently id<MTLDevice> on Cocoa. + * @return Owned surface, or NULL with errno set: EINVAL for invalid arguments, + * ENOTSUP for an unsupported backend, or a backend error. + * Cocoa retains the device. Query the drawable during draw, submit/present it, + * then call yasl_surface_present() to record submission. + */ YASL_API struct yasl_surface *yasl_surface_create_native(struct yasl_display *d, const struct yasl_surface_spec *spec, void *graphics_device); +/** Borrowed native drawable for the current draw target, currently Cocoa/Metal. */ struct yasl_native_frame { - void *drawable; /* id<CAMetalDrawable> on Cocoa */ - bool transaction; /* CAMetalLayer.presentsWithTransaction */ + /** Borrowed id<CAMetalDrawable> on Cocoa. */ + void *drawable; + /** Cocoa CAMetalLayer presentsWithTransaction setting for this frame. */ + bool transaction; }; /* Query the current draw target's native drawable. Returns false for unsupported * backends, stale targets, or outside the draw callback. The result expires on * successful present, callback return, or surface destruction. Native renderers * submit/present the drawable, then call yasl_surface_present() to record it. */ +/** + * Get the current draw target's native drawable. + * @param s Surface currently being drawn. + * @param target Exact framebuffer identity supplied to this draw callback. + * @param out Required output native frame. + * @return true if available, false for NULL arguments, unsupported backends, + * stale targets, or calls outside draw. The drawable is borrowed and expires on + * successful present, callback return, or surface destruction. Currently Cocoa only. + */ YASL_API bool yasl_surface_get_native_frame(struct yasl_surface *s, const struct yasl_framebuffer *target, struct yasl_native_frame *out); 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 diff --git a/include/yasl/timing.h b/include/yasl/timing.h index d443bf6..7e4af9e 100644 --- a/include/yasl/timing.h +++ b/include/yasl/timing.h @@ -1,3 +1,8 @@ +/** + * @file + * Timing provenance, refresh estimates, and buffer-resize statistics. + * All timestamps are monotonic nanoseconds, not wall-clock dates. + */ #ifndef YASL_TIMING_H #define YASL_TIMING_H @@ -7,27 +12,40 @@ extern "C" { #endif +/** Cumulative backend buffer-resize measurements; unavailable counters are zero. */ struct yasl_resize_stats { + /** Number of measured buffer resizes. */ uint64_t count; + /** Mean measured resize duration in microseconds. */ double avg_us; + /** Maximum measured resize duration in microseconds. */ double max_us; + /** Backend minor page-fault counter, if collected. */ long minflt; }; /* Describes last_present_ns, not merely availability of an extension. */ +/** Provenance of last_present_ns; only PRESENTATION confirms compositor presentation. */ enum yasl_timing_source { - YASL_TIMING_UNKNOWN = 0, - YASL_TIMING_SUBMISSION, /* CPU submission time; not scanout confirmation */ - YASL_TIMING_FRAME_CALLBACK, /* compositor pacing callback, not scanout */ - YASL_TIMING_PRESENTATION, /* compositor-confirmed presentation */ + YASL_TIMING_UNKNOWN = 0, /**< No timing sample yet. */ + YASL_TIMING_SUBMISSION, /**< CPU submission time, not scanout confirmation. */ + YASL_TIMING_FRAME_CALLBACK, /**< Compositor pacing callback, not scanout confirmation. */ + YASL_TIMING_PRESENTATION, /**< Compositor-confirmed presentation. */ }; +/** Snapshot of estimates and timing provenance. Zero timestamps mean no sample yet. */ struct yasl_timing { + /** Estimated refresh interval in nanoseconds; zero if unavailable. */ double refresh_ns; + /** Last timestamp, whose meaning is specified by source. */ uint64_t last_present_ns; + /** Estimated next presentation time, or zero without a prior sample. */ uint64_t next_present_ns; + /** Backend skipped-frame counter; not comparable across backends. */ uint64_t frames_skipped; + /** Provenance of last_present_ns. */ enum yasl_timing_source source; + /** Cumulative backend resize statistics. */ struct yasl_resize_stats resize; }; diff --git a/include/yasl/yasl.h b/include/yasl/yasl.h index df94800..f40264e 100644 --- a/include/yasl/yasl.h +++ b/include/yasl/yasl.h @@ -1,3 +1,26 @@ +/** + * @file + * Portable desktop surfaces, CPU drawing, input, and display dispatch. + * + * All calls and callbacks use the display's opening thread (the main thread on + * Cocoa), unless explicitly documented otherwise. Userdata is borrowed; callback + * tables and creation specs are copied. Do not recursively dispatch/flush or + * destroy a display/loop while dispatch or a callback is active. Destroy child + * popups before parents, surfaces before displays, displays before borrowed loops. + * Surface destruction from its own callback is supported; stop using it immediately. + * + * Zero-initialize option and callback structs before setting fields. Pointers to + * destroyed objects are invalid, even for getters and destroy functions. NULL + * handling is documented per function; it does not make freed pointers safe. + * Only functions explicitly documenting errno guarantee a diagnostic there. + * Other boolean results report success/availability; void setters are best effort. + * + * Toplevel creation sizes use logical pixels. Geometry, framebuffers, pointer + * positions, damage, IME carets, popup specs, and drag offsets use device pixels. + * Coordinates have their origin at the upper left; x grows right and y grows down. + * Scale is an integer ratio with YASL_SCALE_UNIT (120) representing 1x. + * See the application guide for the dispatch/poll/flush cycle and backend limits. + */ #ifndef YASL_H #define YASL_H @@ -9,11 +32,13 @@ #include <math.h> #include "yasl/timing.h" +#include "yasl/keycodes.h" #ifdef __cplusplus extern "C" { #endif +/** Public shared-library symbol visibility annotation. */ #if defined(_WIN32) || defined(__CYGWIN__) #if defined(YASL_BUILD_SHARED) #define YASL_API __declspec(dllexport) @@ -33,23 +58,46 @@ struct yasl_surface; struct yasl_loop; /* Geometry */ +/** A two-dimensional integer size, position, or offset; units depend on the caller. */ struct yasl_vector2i { + /** Horizontal coordinate or width. */ int x; + /** Vertical coordinate or height. */ int y; }; +/** Two-dimensional fractional offset; units depend on the containing structure. */ +struct yasl_vector2d { + /** Horizontal component. */ + double x; + /** Vertical component. */ + double y; +}; + +/** Integer rectangle; origin is upper left and extents must be nonnegative. */ struct yasl_rect2i { + /** Left coordinate. */ int x; + /** Top coordinate. */ int y; + /** Nonnegative horizontal extent. */ int width; + /** Nonnegative vertical extent. */ int height; }; +/** Scale numerator representing 1x. */ #define YASL_SCALE_UNIT 120 +/** Backend minimum logical dimension used when constraining toplevel sizes. */ #define YASL_MIN_LOGICAL_PX 64 /* Nearest integer, ties away from zero. Zero scale returns zero; finite * out-of-range results saturate. Non-finite logical coordinates return zero. */ +/** Convert a logical coordinate to device pixels, rounding ties away from zero. + * @param logical Logical coordinate; non-finite values return zero. + * @param scale_120 Scale numerator; zero returns zero. + * @return Rounded device coordinate, saturated to the range of int. + */ static inline int yasl_scale_to_device(double logical, uint32_t scale_120) { if (!scale_120 || !(logical >= -DBL_MAX && logical <= DBL_MAX)) return 0; @@ -59,6 +107,11 @@ static inline int yasl_scale_to_device(double logical, uint32_t scale_120) return (int)(px + copysign(0.5, px)); } +/** Convert a device coordinate to logical pixels, rounding ties away from zero. + * @param device Device coordinate. + * @param scale_120 Scale numerator; zero returns zero. + * @return Rounded logical coordinate, saturated to the range of int. + */ static inline int yasl_scale_to_logical(int device, uint32_t scale_120) { if (!scale_120) return 0; @@ -73,219 +126,293 @@ static inline int yasl_scale_to_logical(int device, uint32_t scale_120) } /* Capabilities */ +/** Optional backend/server features, returned as a bitmask by yasl_display_caps(). */ enum yasl_display_cap : uint32_t { - YASL_CAP_POPUPS = 1 << 0, - YASL_CAP_DRAG = 1 << 1, - YASL_CAP_DRAG_CARRY = 1 << 2, - YASL_CAP_PLACE_WINDOW = 1 << 3, - YASL_CAP_PRIMARY_SELECTION = 1 << 4, - YASL_CAP_CSD = 1 << 5, - YASL_CAP_NATIVE_GRAPHICS = 1 << 6, - YASL_CAP_FRAME_PACING = 1 << 7, /* compositor/display-driven draws */ + YASL_CAP_POPUPS = 1 << 0, /**< Popup creation and placement. */ + YASL_CAP_DRAG = 1 << 1, /**< Surface-drag source and target support. */ + YASL_CAP_DRAG_CARRY = 1 << 2, /**< Carry a toplevel during a drag. */ + YASL_CAP_PLACE_WINDOW = 1 << 3, /**< Place a window relative to the pointer. */ + YASL_CAP_PRIMARY_SELECTION = 1 << 4, /**< Separate primary selection. */ + YASL_CAP_CSD = 1 << 5, /**< Backend advertises client decoration support; check each action result. */ + YASL_CAP_NATIVE_GRAPHICS = 1 << 6, /**< Application-managed native rendering. */ + YASL_CAP_FRAME_PACING = 1 << 7, /**< Compositor/display-driven draws. */ /* Backend/protocol supports tablet axes, independent of attached hardware. */ - YASL_CAP_TABLET = 1 << 8, + YASL_CAP_TABLET = 1 << 8, /**< Tablet protocol support, independent of attached hardware. */ }; +/** Independent selections. An unsupported selection never aliases the clipboard. */ enum yasl_selection : uint8_t { - YASL_CLIPBOARD, - YASL_PRIMARY, + YASL_CLIPBOARD, /**< Explicit copy/paste selection. */ + YASL_PRIMARY, /**< Independent primary selection, if supported. */ }; +/** Reported surface state flags; absent flags may also mean unsupported state. */ enum yasl_surface_state : uint32_t { - YASL_STATE_FULLSCREEN = 1 << 0, - YASL_STATE_MAXIMIZED = 1 << 1, - YASL_STATE_ACTIVATED = 1 << 2, - YASL_STATE_SUSPENDED = 1 << 3, - YASL_STATE_CSD = 1 << 4, + YASL_STATE_FULLSCREEN = 1 << 0, /**< Fullscreen. */ + YASL_STATE_MAXIMIZED = 1 << 1, /**< Maximized. */ + YASL_STATE_ACTIVATED = 1 << 2, /**< Active window. */ + YASL_STATE_SUSPENDED = 1 << 3, /**< Compositor reports suspension. */ + YASL_STATE_CSD = 1 << 4, /**< Backend reports client-side decorations. */ }; +/** System cursor shapes. HIDDEN preserves pointer input; NONE is its compatibility alias. */ enum yasl_cursor { - YASL_CURSOR_ARROW, - YASL_CURSOR_TEXT, - YASL_CURSOR_LINK, - YASL_CURSOR_CROSSHAIR, - YASL_CURSOR_MOVE, - YASL_CURSOR_RESIZE_NWSE, - YASL_CURSOR_RESIZE_NESW, - YASL_CURSOR_RESIZE_EW, - YASL_CURSOR_RESIZE_NS, - YASL_CURSOR_HIDDEN, /* Hide the system cursor; pointer input is unchanged. */ - YASL_CURSOR_NONE = YASL_CURSOR_HIDDEN, /* Compatibility alias. */ -}; - + YASL_CURSOR_ARROW, /**< Default arrow. */ + YASL_CURSOR_TEXT, /**< Text insertion. */ + YASL_CURSOR_LINK, /**< Link/pointer hand. */ + YASL_CURSOR_CROSSHAIR, /**< Crosshair. */ + YASL_CURSOR_MOVE, /**< Move in any direction. */ + YASL_CURSOR_RESIZE_NWSE, /**< Northwest/southeast resize. */ + YASL_CURSOR_RESIZE_NESW, /**< Northeast/southwest resize. */ + YASL_CURSOR_RESIZE_EW, /**< Horizontal resize. */ + YASL_CURSOR_RESIZE_NS, /**< Vertical resize. */ + YASL_CURSOR_HIDDEN, /**< Hidden system cursor; pointer input continues. */ + YASL_CURSOR_NONE = YASL_CURSOR_HIDDEN, /**< Compatibility alias for HIDDEN. */ +}; + +/** Valid interactive resize edges; combinations are restricted to the named values. */ enum yasl_resize_edge : uint32_t { - YASL_EDGE_NONE = 0, - YASL_EDGE_TOP = 1, - YASL_EDGE_BOTTOM = 2, - YASL_EDGE_LEFT = 4, - YASL_EDGE_TOP_LEFT = 5, - YASL_EDGE_BOTTOM_LEFT = 6, - YASL_EDGE_RIGHT = 8, - YASL_EDGE_TOP_RIGHT = 9, - YASL_EDGE_BOTTOM_RIGHT = 10, + YASL_EDGE_NONE = 0, /**< No resize edge; rejected by interactive resize. */ + YASL_EDGE_TOP = 1, /**< Top edge. */ + YASL_EDGE_BOTTOM = 2, /**< Bottom edge. */ + YASL_EDGE_LEFT = 4, /**< Left edge. */ + YASL_EDGE_TOP_LEFT = 5, /**< Top-left corner. */ + YASL_EDGE_BOTTOM_LEFT = 6, /**< Bottom-left corner. */ + YASL_EDGE_RIGHT = 8, /**< Right edge. */ + YASL_EDGE_TOP_RIGHT = 9, /**< Top-right corner. */ + YASL_EDGE_BOTTOM_RIGHT = 10, /**< Bottom-right corner. */ }; /* Damage & Framebuffer * CPU pixels are tightly packed premultiplied ARGB8888 (0xAARRGGBB). * Size, pointer positions, IME caret and damage use device pixels; surface - * creation sizes use logical pixels. Damage is a hint: backends may upload + * toplevel creation sizes use logical pixels. Damage is a hint: backends may upload * the whole frame. Every pixel must contain valid content on each draw. */ +/** Maximum number of damage rectangles in one presentation. */ #define YASL_DAMAGE_MAX 64 +/** Damage hints for one presentation; every target still needs complete valid pixels. */ struct yasl_damage_list { - int n; /* -1 means full repaint */ + /** -1: full target; 0: no damaged rectangles; otherwise number of rects. */ + int n; + /** Reserved hint; callers may leave zero. Core presentation uses rects. */ struct yasl_rect2i bounds; + /** First n rectangles, in device pixels; ignored for n == -1. */ struct yasl_rect2i rects[YASL_DAMAGE_MAX]; }; +/** Borrowed draw target, valid only for the current draw callback. Never free pixels. */ struct yasl_framebuffer { - uint64_t generation; /* Opaque draw identity; preserve when copying target. */ + /** Opaque draw identity. Preserve it and all target fields when copying. */ + uint64_t generation; + /** Writable premultiplied ARGB8888, row stride size.x * sizeof(uint32_t); may be NULL for native rendering. */ uint32_t *pixels; + /** Target extent in device pixels. */ struct yasl_vector2i size; }; +/** One draw invocation. Do not retain its pointer after the callback returns. */ struct yasl_frame { + /** Surface being drawn. */ struct yasl_surface *surface; + /** Target to initialize and present before returning. */ struct yasl_framebuffer target; }; /* Drag and Drop */ +/** Target notifications for YASL surface drags, separate from external file drops. */ enum yasl_drag_event { - YASL_DRAG_OVER, - YASL_DRAG_LEAVE, - YASL_DRAG_DROP, + YASL_DRAG_OVER, /**< Surface drag entered or moved over the target. */ + YASL_DRAG_LEAVE, /**< Surface drag left the target. */ + YASL_DRAG_DROP, /**< Surface drag dropped on the target. */ }; +/** External text/file drag hover notifications; completed data arrives through input. */ enum yasl_drop_event { - YASL_DROP_OVER, - YASL_DROP_LEAVE, + YASL_DROP_OVER, /**< External data drag entered or moved over the target. */ + YASL_DROP_LEAVE, /**< External data drag left the target. */ }; +/** Source-side drag completion; DROPPED does not prove application-level acceptance. */ enum yasl_drag_end { - YASL_DRAG_DROPPED, - YASL_DRAG_CANCELLED, + YASL_DRAG_DROPPED, /**< Drag ended in a drop; not an application acceptance receipt. */ + YASL_DRAG_CANCELLED, /**< Drag canceled, including display close. */ }; +/** Copied drag icon in tightly packed premultiplied 0xAARRGGBB device pixels. */ struct yasl_drag_image { + /** Copied pixel array; required when an image is supplied. */ const uint32_t *pixels; + /** Positive width and height in device pixels. */ struct yasl_vector2i size; + /** Pointer position within the image, in device pixels. */ struct yasl_vector2i hotspot; }; +/** Copied drag completion listener; userdata remains owned by the application. */ struct yasl_drag_listener { + /** Called exactly once after a successful start, possibly synchronously on cancel/close. */ void (*end)(void *ud, enum yasl_drag_end how); }; +/** Configured device-pixel content size and the corresponding display scale. */ struct yasl_geometry { + /** Current content extent in device pixels. */ struct yasl_vector2i size; + /** Positive scale numerator; 120 means 1x and 180 means 1.5x. */ uint32_t scale_120; }; /* Input Model */ +/** Keyboard press, release, or autorepeat; releases must not insert text. */ enum yasl_key_action { - YASL_KEY_PRESS, - YASL_KEY_RELEASE, - YASL_KEY_REPEAT, + YASL_KEY_PRESS, /**< Key pressed. */ + YASL_KEY_RELEASE, /**< Key released. */ + YASL_KEY_REPEAT, /**< Key autorepeat. */ }; +/** Modifier bitmask. SUPER is Command on macOS. */ enum yasl_mod : uint32_t { - YASL_MOD_SHIFT = 1 << 0, - YASL_MOD_ALT = 1 << 1, - YASL_MOD_CTRL = 1 << 2, - YASL_MOD_SUPER = 1 << 3, - YASL_MOD_CAPS = 1 << 4, + YASL_MOD_SHIFT = 1 << 0, /**< Shift modifier. */ + YASL_MOD_ALT = 1 << 1, /**< Alt/Option modifier. */ + YASL_MOD_CTRL = 1 << 2, /**< Control modifier. */ + YASL_MOD_SUPER = 1 << 3, /**< Super/Command modifier. */ + YASL_MOD_CAPS = 1 << 4, /**< Caps Lock modifier. */ }; +/** Pointer transition or motion type; fields are meaningful according to this tag. */ enum yasl_pointer_kind { - YASL_PTR_PRESS, - YASL_PTR_RELEASE, - YASL_PTR_MOTION, - YASL_PTR_LEAVE, - YASL_PTR_SCROLL, + YASL_PTR_PRESS, /**< Button/tip pressed. */ + YASL_PTR_RELEASE, /**< Button/tip released. */ + YASL_PTR_MOTION, /**< Position or tablet axes changed. */ + YASL_PTR_LEAVE, /**< Pointer/tool left the surface. */ + YASL_PTR_SCROLL, /**< Scroll sample. */ }; +/** Pointer source class; capability support does not imply an attached device. */ enum yasl_pointer_device { - YASL_PTR_DEV_MOUSE, - YASL_PTR_DEV_TOUCH, - YASL_PTR_DEV_PEN, - YASL_PTR_DEV_ERASER, + YASL_PTR_DEV_MOUSE, /**< Mouse or trackpad pointer. */ + YASL_PTR_DEV_TOUCH, /**< Touch translated into pointer input. */ + YASL_PTR_DEV_PEN, /**< Tablet stylus. */ + YASL_PTR_DEV_ERASER, /**< Tablet eraser tool. */ }; +/** Normalized tablet axes; zero for unavailable axes and non-tablet devices. */ struct yasl_pointer_pen { - 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. */ -}; - + /** 0..65535 normalized to device range. Zero alone does not end contact. */ + uint16_t pressure; + /** Degrees in -90..90; positive right. */ + int8_t tilt_x; + /** Degrees in -90..90; positive down. */ + int8_t tilt_y; +}; + +/** Physical keyboard transition with optional layout labels. + * key is independent of modifiers/layout and stable between press and release. + * codepoint and shifted are optional single Unicode scalars for the current + * layout at levels zero/one, not text input. Zero means unavailable, a control + * key, or a layout mapping that produces multiple characters. Native scancodes + * are backend-specific. Insert committed YASL_INPUT_TEXT into documents. + */ struct yasl_key_event { - uint32_t key; - uint32_t keypad; + /** Portable physical key; YASL_KEY_UNKNOWN when unmapped. */ + enum yasl_key key; + /** Press, release, or autorepeat. */ enum yasl_key_action action; + /** yasl_mod bitmask at this event. */ uint32_t mods; + /** Optional unshifted layout Unicode scalar; zero if unavailable. */ uint32_t codepoint; + /** Optional shifted layout Unicode scalar; zero if unavailable. */ uint32_t shifted; - uint32_t base; - uint32_t text; + /** Native code: Wayland evdev, X11 server keycode, Cocoa virtual keycode. */ + uint32_t native_code; }; +/** Pointer sample. Pen and eraser events share this structure with mouse input. +Track contact with primary press/release, not pressure alone. Leave, focus loss, +and YASL_INPUT_RESET must cancel held application input state. This is not a +multi-contact touch API. Scroll offsets use fractional line units: positive x +means right and positive y means down, after system scroll preferences. */ struct yasl_mouse_event { + /** Surface-relative device-pixel position. */ struct yasl_vector2i pos; - int16_t button; /* Press/release: 0 = primary/tip, 1 = middle, 2 = secondary. - * Motion/leave: informational; track presses and releases. */ - int16_t scroll_lines; + /** Press/release: 0 primary/tip, 1 middle, 2 secondary. Unused for scroll. */ + int16_t button; + /** Sample type. */ enum yasl_pointer_kind kind; + /** Mouse, touch, pen, or eraser. */ enum yasl_pointer_device device; + /** yasl_mod bitmask at this event. */ 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. */ + /** Fractional line offsets, valid for SCROLL only; positive right/down. */ + struct yasl_vector2d scroll; + + /** Current tablet axes, including on pressure-only motion; missing axes are zero. */ struct yasl_pointer_pen pen; }; +/** Input union tag. RESET has no payload and requires clearing held state. */ enum yasl_input_kind { - YASL_INPUT_KEY, - YASL_INPUT_MOUSE, - YASL_INPUT_FOCUS, - YASL_INPUT_PASTE, - YASL_INPUT_DROP_FILES, - YASL_INPUT_TEXT, + YASL_INPUT_KEY, /**< key member. */ + YASL_INPUT_MOUSE, /**< mouse member. */ + YASL_INPUT_FOCUS, /**< focus member. */ + YASL_INPUT_PASTE, /**< paste member. */ + YASL_INPUT_DROP_FILES, /**< drop_files member. */ + YASL_INPUT_TEXT, /**< text member, containing committed UTF-8. */ /* The input stream was interrupted (e.g. allocation failure or device * removal). Clear held keys/buttons and composition state. */ - YASL_INPUT_RESET, + YASL_INPUT_RESET, /**< No payload. Clear held keys/buttons and composition after an interruption. */ }; +/** Keyboard focus transition; cancel held state when focus is lost. */ struct yasl_focus_event { + /** true on focus gain, false on loss. */ bool focused; }; +/** Committed UTF-8 text; insert this instead of deriving characters from key events. */ struct yasl_text_event { + /** Borrowed NUL-terminated UTF-8. */ const char *text; + /** Length in bytes excluding the terminating NUL. */ size_t len; }; +/** UTF-8 text received from an explicit selection request. */ struct yasl_paste_event { + /** Borrowed NUL-terminated UTF-8. */ const char *text; + /** Length in bytes excluding the terminating NUL. */ size_t len; }; +/** File URLs in text/uri-list form, separated by CRLF; not filesystem paths. */ struct yasl_drop_files_event { + /** Borrowed NUL-terminated text/uri-list; parse URLs and percent escapes. */ const char *files; + /** Length in bytes excluding the terminating NUL. */ size_t len; }; +/** One tagged input event; read only the union member selected by kind. +Payload strings follow yasl_surface_input_poll() lifetime rules. RESET carries +no union payload; clear keys, buttons, strokes, and composition state. */ struct yasl_input_event { + /** Recipient; can differ from the polled surface for routed popup input. */ struct yasl_surface *surface; + /** Selects the valid union member. */ enum yasl_input_kind kind; + /** Reserved for YASL; applications must not interpret it. */ uint32_t reserved; union { - struct yasl_key_event key; - struct yasl_mouse_event mouse; - struct yasl_focus_event focus; - struct yasl_text_event text; - struct yasl_paste_event paste; - struct yasl_drop_files_event drop_files; + struct yasl_key_event key; /**< Keyboard payload. */ + struct yasl_mouse_event mouse; /**< Pointer payload. */ + struct yasl_focus_event focus; /**< Focus payload. */ + struct yasl_text_event text; /**< Committed text payload. */ + struct yasl_paste_event paste; /**< Selection text payload. */ + struct yasl_drop_files_event drop_files; /**< File URL list payload. */ }; }; @@ -300,128 +427,417 @@ struct yasl_input_event { */ /* Callbacks */ +/** Optional display notifications. NULL callback members are ignored. */ struct yasl_display_cbs { + /** Application quit request; arrange orderly shutdown after dispatch returns. */ void (*quit)(void *ud); + /** Application reopen/activation request, currently Cocoa. */ void (*reopen)(void *ud); + /** Display connection lost; arrange cleanup after dispatch returns. */ void (*lost)(void *ud); }; +/** Optional surface notifications, copied by yasl_surface_set_callbacks(). +Callbacks may destroy their surface. They must then return without further use +of the surface or draw target. NULL members are ignored. */ struct yasl_surface_cbs { + /** Initialize the entire target and optionally present. Requested through schedule_redraw/flush. */ void (*draw)(struct yasl_surface *s, struct yasl_frame *frame, void *ud); + /** Configured size/scale changed; reallocate application content and request a redraw. */ void (*configure)(struct yasl_surface *s, struct yasl_geometry geometry, void *ud); + /** Window/popup close request; application is responsible for destruction. */ void (*close)(struct yasl_surface *s, void *ud); + /** Reported yasl_surface_state bitmask changed. */ void (*state)(struct yasl_surface *s, uint32_t state, void *ud); + /** YASL surface-drag target hover, leave, or drop; pos is in device pixels. */ void (*drag)(struct yasl_surface *s, enum yasl_drag_event ev, struct yasl_vector2i pos, void *ud); + /** External data-drag hover or leave; pos is in device pixels. */ void (*drop)(struct yasl_surface *s, enum yasl_drop_event ev, struct yasl_vector2i pos, void *ud); }; /* Display Lifecycle */ +/** Runtime backend choice. AUTO selects a native backend and allows fallback. */ enum yasl_backend { - YASL_BACKEND_AUTO = 0, - YASL_BACKEND_WAYLAND, - YASL_BACKEND_X11, - YASL_BACKEND_COCOA, + YASL_BACKEND_AUTO = 0, /**< Choose native backend with fallback. */ + YASL_BACKEND_WAYLAND, /**< Require Wayland. */ + YASL_BACKEND_X11, /**< Require X11. */ + YASL_BACKEND_COCOA, /**< Require Cocoa. */ }; +/** Display options. Zero-initialize for automatic backend selection. */ struct yasl_display_spec { + /** Copied application identifier, conventionally a reverse-domain UTF-8 string; NULL uses backend defaults. */ const char *app_id; + /** Copied optional display callbacks; NULL disables them. */ const struct yasl_display_cbs *cbs; + /** Borrowed display callback userdata. */ void *ud; - /* Zero selects the native backend. An explicit choice never falls back. */ + + /** Zero/AUTO chooses native backend; explicit choices never fall back. */ enum yasl_backend backend; }; /* Return NULL and set errno if the requested backend cannot open. */ +/** + * Open a desktop connection and its event machinery. + * @param loop Borrowed loop, or NULL to create a display-owned loop. + * @param spec Copied options, or NULL for automatic backend selection and defaults. + * @return An owned display, or NULL with errno set. EINVAL means an invalid backend; + * ENOSYS means the requested backend was not built; ENODEV is the fallback when + * opening fails without a more specific platform error. Explicit choices never + * fall back. Close with yasl_display_close() after destroying its surfaces. + */ YASL_API struct yasl_display *yasl_display_open(struct yasl_loop *loop, const struct yasl_display_spec *spec); +/** + * Read the selected backend. + * @param d Display, or NULL. + * @return The actual backend, or YASL_BACKEND_AUTO for NULL. + */ YASL_API enum yasl_backend yasl_display_backend(const struct yasl_display *d); +/** + * Close a display and release its owned loop, if any. + * @param d Display to close, or NULL for no action. + * Destroy all surfaces first. Cancels an active drag and may invoke its end + * listener. Must not be called during dispatch or from a callback. + */ YASL_API void yasl_display_close(struct yasl_display *d); +/** + * Query currently available optional features. + * @param d Display, or NULL. + * @return A bitmask of yasl_display_cap values, or zero for NULL. + * Capabilities describe backend/server support, not attached input hardware or + * permission to perform an operation at any arbitrary moment. + */ YASL_API uint32_t yasl_display_caps(const struct yasl_display *d); /* Process events, waiting at most timeout_ms: zero polls, negative waits. * Pending input or redraw work returns immediately. Returns -1 on failure. */ +/** + * Receive events and run ready loop sources. + * @param d Display to dispatch. + * @param timeout_ms Maximum wait in milliseconds: zero polls, negative waits indefinitely. + * @return A nonnegative backend-specific work count on success, or -1 with errno + * set on failure (EINVAL for NULL, EIO if no specific backend error is available). + * Do not interpret the count as the number of queued input events. Pending input + * or runnable redraw work prevents waiting. Drain input and call + * yasl_display_flush() after updating application state. Do not dispatch recursively. + */ YASL_API int yasl_display_dispatch(struct yasl_display *d, int timeout_ms); +/** + * Draw scheduled surfaces and send pending display requests. + * @param d Display, or NULL for no action. + * May synchronously invoke draw and other callbacks. A paced surface may wait + * for its next display/compositor signal. This is not a GPU completion wait. + */ YASL_API void yasl_display_flush(struct yasl_display *d); +/** + * Read the latest modifier state known to the backend. + * @param d Display, or NULL. + * @return A bitmask of yasl_mod values, or zero for NULL. + * For an individual event use its own mods field instead. + */ YASL_API int yasl_display_modifiers(const struct yasl_display *d); /* Unsupported/invalid selections are no-ops, never clipboard aliases. */ +/** + * Offer a copy of a NUL-terminated UTF-8 string as a selection. + * @param d Display, or NULL for no action. + * @param sel YASL_CLIPBOARD or YASL_PRIMARY. + * @param text Text copied during this call; NULL does nothing. + * Unsupported selections do nothing. The void return does not confirm that the + * system accepted the offer; Wayland may require a recent input serial. + */ YASL_API void yasl_display_copy(struct yasl_display *d, enum yasl_selection sel, const char *text); +/** + * Request text delivery to a particular surface. + * @param d Display that owns target. + * @param sel YASL_CLIPBOARD or YASL_PRIMARY. + * @param target Destination surface; NULL or a surface on another display does nothing. + * Results arrive as YASL_INPUT_PASTE, possibly during a later dispatch. No result + * is promised for unavailable data or a failed transfer. Destroying target cancels + * delivery. Unsupported selections do nothing. + */ YASL_API void yasl_display_paste(struct yasl_display *d, enum yasl_selection sel, struct yasl_surface *target); /* A successful drag invokes the copied listener's non-NULL end once, including * cancel and display close. Failed starts do not invoke it. */ +/** + * Start a surface drag from a recent pointer press. + * @param d Display that owns origin. + * @param origin Origin surface. + * @param image Optional copied premultiplied ARGB8888 drag image, or NULL. + * @param l Optional copied completion listener, or NULL. + * @param ud Borrowed listener userdata until completion. + * @return true if started; false if unsupported, invalid, or not currently permitted. + * A successful start invokes a non-NULL end callback exactly once, including + * cancellation or display close. Failed starts do not invoke it. This API carries + * surfaces, not arbitrary MIME payloads; use application state to identify the item. + */ YASL_API bool yasl_display_drag_start(struct yasl_display *d, struct yasl_surface *origin, const struct yasl_drag_image *image, const struct yasl_drag_listener *l, void *ud); +/** + * Cancel the active surface drag, if any. + * @param d Display, or NULL for no action. + * May invoke the end listener synchronously. + */ YASL_API void yasl_display_drag_cancel(struct yasl_display *d); /* Surface Lifecycle */ +/** Toplevel options. Zero-initialize, then supply a positive logical-pixel size. */ struct yasl_surface_spec { + /** Copied UTF-8 title; NULL uses backend defaults. */ const char *title; + /** Requested logical-pixel width and height; both must be positive. */ struct yasl_vector2i size; + /** Request initial fullscreen; actual state is reported asynchronously. */ bool fullscreen; + /** Permit unpaced presentation where supported; a hint, not a guarantee. */ bool tearing; }; +/** Popup options, entirely in device pixels, including size. +The content rectangle excludes transparent margins/shadows used for placement. +An axis of content_size equal to zero extends to that axis of size. The offset +and resolved content size must fit in size. Anchor extents must be nonnegative. +Dimensions must be positive, at most 32767, and fit an INT32_MAX-byte buffer; +backends may impose further limits after scaling or resolving placement. */ struct yasl_popup_spec { + /** Full popup framebuffer extent in device pixels, including transparent margins. */ struct yasl_vector2i size; + /** Rectangle in parent framebuffer coordinates, in device pixels. */ struct yasl_rect2i anchor; + /** true prefers right of anchor; false prefers below. Placement may flip/slide. */ bool beside; + /** Top-left content offset within the popup, in device pixels. */ struct yasl_vector2i content_offset; + /** Content extent; zero per axis extends to the corresponding size edge. */ struct yasl_vector2i content_size; }; +/** + * Create a resizable desktop window with CPU drawing targets. + * @param d Owning display. + * @param spec Required copied options; size is in logical pixels. + * @return An owned surface, or NULL with errno set. EINVAL means invalid options, + * including a nonpositive dimension, a dimension above 32767, or a buffer above + * INT32_MAX bytes. ENODEV is the fallback backend failure. Actual configured + * size may differ from the request. Install callbacks and schedule a redraw. + */ YASL_API struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d, const struct yasl_surface_spec *spec); +/** + * Create an owned popup attached to a parent surface. + * @param parent Borrowed parent; destroy the popup before the parent. + * @param spec Required copied options, entirely in device pixels. + * @return A popup, or NULL with errno set: EINVAL for invalid options, ENOTSUP + * for missing popup support, or a backend error (ENODEV if none was supplied). + * Wayland requires a recent input serial for its popup grab. The backend may + * flip or slide placement to fit the screen. See yasl_popup_spec. + */ YASL_API struct yasl_surface *yasl_surface_create_popup(struct yasl_surface *parent, const struct yasl_popup_spec *spec); +/** + * Update a popup's geometry and placement. + * @param popup An existing popup. + * @param spec Required copied replacement options, in device pixels. + * @return true on success; false with errno set: EINVAL for invalid options, + * ENOTSUP for missing popup support, or a backend error (ENODEV if unspecified). + * Older Wayland popup protocol versions can reject repositioning. + */ YASL_API bool yasl_surface_popup_reposition(struct yasl_surface *popup, const struct yasl_popup_spec *spec); +/** + * Destroy a surface and cancel its surface timers and pending input. + * @param s Surface, or NULL for no action. + * Destroy child popups first. May be called from a surface callback; return from + * that callback without further use of the surface or its draw target. Every + * pointer or native handle obtained from this surface becomes invalid. + */ YASL_API void yasl_surface_destroy(struct yasl_surface *s); +/** + * Get the display that owns a surface. + * @param s Surface, or NULL. + * @return A borrowed display, or NULL. + */ YASL_API struct yasl_display *yasl_surface_display(const struct yasl_surface *s); +/** + * Replace the surface's callback table and userdata. + * @param s Surface, or NULL for no action. + * @param cbs Table copied by value; NULL removes all callbacks. NULL members are ignored. + * @param ud Borrowed userdata passed to the installed callbacks. + * Callbacks may run synchronously during this call; initialize userdata first. + * Use yasl_surface_geometry() to read current geometry; do not rely on receiving + * an initial configure callback when registering. + */ YASL_API void yasl_surface_set_callbacks(struct yasl_surface *s, const struct yasl_surface_cbs *cbs, void *ud); +/** + * Replace the window title with copied UTF-8 text. + * @param s Surface. + * @param title NUL-terminated UTF-8 title. Pass an empty string to clear it. + * Backends may truncate the title. + */ YASL_API void yasl_surface_set_title(struct yasl_surface *s, const char *title); +/** + * Request a future draw callback, coalescing repeated requests. + * @param s Surface, or NULL for no action. + * Call yasl_display_flush() to service the request. Schedule again from draw to + * animate. Without YASL_CAP_FRAME_PACING, throttle animation with a timer. + */ YASL_API void yasl_surface_schedule_redraw(struct yasl_surface *s); /* Present exactly the target supplied to the current draw callback, at most * once. Targets expire when that callback returns or the surface is destroyed. * damage is required: n must be -1 or 0..YASL_DAMAGE_MAX. Rectangles must have * nonnegative extents; they are clipped to the target. Invalid input returns * false without consuming the frame. See yasl/native.h for native rendering. */ +/** + * Submit the current draw target at most once. + * @param s Surface currently being drawn. + * @param fb Exact target from the current draw callback, including its generation. + * @param damage Required damage hint: n is -1 for all pixels or 0..YASL_DAMAGE_MAX. + * @return true if accepted; false for invalid, stale, already presented, or failed targets. + * Rectangles must have nonnegative extents and are clipped to the target. Invalid + * input does not consume the frame. All pixels must be initialized even with + * partial damage. The backend may upload all pixels. Success records submission, + * not confirmed scanout. The target expires when draw returns or s is destroyed. + */ YASL_API bool yasl_surface_present(struct yasl_surface *s, const struct yasl_framebuffer *fb, const struct yasl_damage_list *damage); /* Event payload strings are library-owned, NUL-terminated, and valid until * the next SUCCESSFUL poll on this surface or surface destruction. Dispatch, * flush and unsuccessful polls do not invalidate them. Copy to keep longer. */ +/** + * Remove one event from a surface's input queue without waiting. + * @param s Surface whose queue to drain. + * @param ev Required output event; unchanged when no event is available. + * @return true for an event, false for an empty queue or NULL arguments. + * Dispatch receives native input; polling only drains the queue. Read the union + * member selected by kind. Payload strings are borrowed, NUL-terminated, and + * valid until the next successful poll on this queue or its destruction; dispatch, + * flush, and unsuccessful polls do not invalidate them. On Wayland, popup pointer + * and keyboard input can be routed through the root parent's queue; inspect + * ev->surface to identify the receiving surface. + */ YASL_API bool yasl_surface_input_poll(struct yasl_surface *s, struct yasl_input_event *ev); /* Current device-pixel size and scale, matching the configure callback. */ +/** + * Read current device-pixel size and scale together. + * @param s Surface, or NULL. + * @return Geometry matching configure callbacks; NULL gives zero size and unit scale. + */ YASL_API struct yasl_geometry yasl_surface_geometry(const struct yasl_surface *s); +/** + * Read current window state. + * @param s Surface, or NULL. + * @return A bitmask of yasl_surface_state values, or zero for NULL. + * Flags are reported state, not requests; unsupported states are absent. + */ YASL_API uint32_t yasl_surface_state(const struct yasl_surface *s); /* Timing uses monotonic nanoseconds. Check source before treating timestamps * as presentation confirmation. refresh/next_present are estimates. Without * YASL_CAP_FRAME_PACING, redraws run on flush without display synchronization. * Tearing may bypass pacing even when the capability is present. */ +/** + * Read frame timing estimates and their provenance. + * @param s Surface, or NULL. + * @return Current timing, or a zero-initialized result for NULL. + * Timestamps use monotonic nanoseconds. Inspect source before treating a timestamp + * as confirmation of presentation. Refresh and next-present values are estimates. + */ YASL_API struct yasl_timing yasl_surface_timing(const struct yasl_surface *s); +/** + * Get a nondecreasing animation timestamp aligned to estimated refresh. + * @param s Surface, or NULL. + * @param now Current monotonic nanoseconds, usually from yasl_loop_now_ns(). + * @return Animation timestamp, or zero for NULL. Before timing is known, returns now. + * Use this to advance animations; it is not presentation feedback. + */ 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. */ +/** + * Select the surface's system mouse and tablet cursor. + * @param s Surface. + * @param cursor Cursor shape; YASL_CURSOR_HIDDEN hides the cursor without disabling input. + * The choice persists across motion and re-entry until another shape is selected. + */ YASL_API void yasl_surface_set_cursor(struct yasl_surface *s, enum yasl_cursor cursor); +/** + * Set a backend window background hint. + * @param s Surface. + * @param bg Packed 0xAARRGGBB color; backends may ignore alpha or the entire hint. + * Does not initialize framebuffer pixels or replace drawing. + */ YASL_API void yasl_surface_set_background_color(struct yasl_surface *s, uint32_t bg); /* IME Support: preedit is borrowed until the next dispatch or destruction. */ +/** + * Read the current uncommitted UTF-8 composition text. + * @param s Surface, or NULL. + * @return Borrowed NUL-terminated text, or NULL if absent/unsupported. + * Copy to retain across the next dispatch or surface destruction. Composition + * changes can schedule a redraw. Insert committed YASL_INPUT_TEXT into documents, + * not preedit text. + */ YASL_API const char *yasl_surface_ime_preedit(const struct yasl_surface *s); +/** + * Read the cursor/selection range in the preedit string. + * @param s Surface. + * @param begin Required output UTF-8 byte offset for the range start. + * @param end Required output UTF-8 byte offset for the range end. + * @return true if available; false without changing outputs otherwise. + * Currently available on Wayland; Cocoa preedit text has no range result. + */ YASL_API bool yasl_surface_ime_preedit_cursor(const struct yasl_surface *s, int *begin, int *end); +/** + * Place the composition candidate window near the application caret. + * @param s Surface. + * @param caret Caret rectangle relative to the surface, in device pixels. + * Update after caret motion or scale changes. Unsupported backends ignore it. + */ YASL_API void yasl_surface_set_ime_caret(struct yasl_surface *s, struct yasl_rect2i caret); /* Client-Side Decorations (CSD) Actions */ +/** + * Ask the window system to begin an interactive move. + * @param s Toplevel surface, normally during handling of a pointer press. + * @return true if the request was issued; false if unsupported or not permitted. + * A recent input serial may be required. Success does not confirm a final position. + */ YASL_API bool yasl_surface_start_interactive_move(struct yasl_surface *s); +/** + * Ask the window system to begin an interactive resize. + * @param s Toplevel surface, normally during handling of a pointer press. + * @param edge One nonzero yasl_resize_edge enumerator. + * @return true if issued; false for an invalid edge, missing support, or rejected request. + */ YASL_API bool yasl_surface_start_interactive_resize(struct yasl_surface *s, enum yasl_resize_edge edge); +/** + * Ask the window system to display its window management menu. + * @param s Toplevel surface. + * @param pos Surface-relative position in device pixels. + * @return true if issued; false if unsupported or not currently permitted. + */ YASL_API bool yasl_surface_show_window_menu(struct yasl_surface *s, struct yasl_vector2i pos); /* Drag Support */ +/** + * Attach a toplevel surface to the current surface drag. + * @param s Surface to carry; check YASL_CAP_DRAG_CARRY first. + * @param offset Device-pixel offset of the pointer within the carried surface. + * @return true if accepted; false if unsupported or no compatible drag is active. + */ YASL_API bool yasl_surface_drag_carry(struct yasl_surface *s, struct yasl_vector2i offset); +/** + * Place a toplevel surface relative to the current pointer. + * @param s Surface; check YASL_CAP_PLACE_WINDOW first. + * @param at Device-pixel position within the surface to place under the pointer. + * @return true if issued; false if unsupported or unavailable. + */ YASL_API bool yasl_surface_place_under_pointer(struct yasl_surface *s, struct yasl_vector2i at); #ifdef __cplusplus diff --git a/meson.build b/meson.build index 1c4ea10..07f4390 100644 --- a/meson.build +++ b/meson.build @@ -48,7 +48,15 @@ if system == 'linux' deps += [wl_client, wl_cursor, xkbcommon] endif elif system == 'darwin' - add_languages('objc') + add_languages('objc', native: false) + if not cc.compiles(''' + #if !defined(__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__) || __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 140000 + #error YASL requires macOS 14 or newer + #endif + int main(void) { return 0; } + ''', name: 'macOS deployment target is at least 14') + error('Cocoa requires macOS 14 or newer. Set MACOSX_DEPLOYMENT_TARGET=14.0 or a newer target before configuring.') + endif deps += [ dependency('appleframeworks', modules: ['AppKit', 'Metal', 'QuartzCore']), ] @@ -84,6 +92,7 @@ yasl_lib = both_libraries( install_headers( 'include/yasl/yasl.h', 'include/yasl/timing.h', + 'include/yasl/keycodes.h', 'include/yasl/loop.h', 'include/yasl/native.h', subdir: 'yasl', @@ -115,6 +124,13 @@ yasl_dep = declare_dependency( ) meson.override_dependency('yasl', yasl_dep) +hello_example = executable( + 'yasl-hello', + 'examples/hello.c', + include_directories: inc, + link_with: yasl_lib.get_shared_lib(), +) + executable( 'yasl-example', 'examples/simple_window.c', @@ -130,3 +146,11 @@ tablet_example = executable( ) subdir('tests') + +doc_dir = get_option('datadir') / 'doc' / 'yasl' +install_data('README.md', 'CONTRIBUTING.md', 'Doxyfile', 'LICENSE', install_dir: doc_dir) +# Preserve source-relative links and keep the reference buildable offline. +install_subdir('docs', install_dir: doc_dir) +install_subdir('examples', install_dir: doc_dir) +install_subdir('include', install_dir: doc_dir) +install_data('LICENSE', install_dir: get_option('datadir') / 'licenses' / 'yasl') diff --git a/src/cocoa/window.m b/src/cocoa/window.m index 645ae07..028ba64 100644 --- a/src/cocoa/window.m +++ b/src/cocoa/window.m @@ -7,6 +7,7 @@ #include "common/timing.h" #include "common/loop.h" #include "cocoa/keycodes.h" +#include "common/keyboard.h" #include <assert.h> #include <math.h> @@ -67,10 +68,6 @@ struct cocoa_surface { char *preedit; struct yasl_rect2i ime_caret; - char *key_text; - size_t key_text_capacity; - size_t key_text_len; - bool in_key_down; struct yasl_vector2i size; uint32_t scale_120; @@ -269,23 +266,35 @@ static unsigned cocoa_mods(NSEventModifierFlags m) return mods; } +/* Decode a single Unicode scalar, never a lone UTF-16 surrogate. Layout labels + * are optional: multi-scalar mappings and native function-key characters are 0. */ +static uint32_t cocoa_key_label(NSString *characters) +{ + if (!characters.length) return 0; + unichar first = [characters characterAtIndex:0]; + if (characters.length == 1) + return yasl_key_label(first); + if (characters.length == 2 && first >= 0xd800 && first <= 0xdbff) { + unichar second = [characters characterAtIndex:1]; + if (second >= 0xdc00 && second <= 0xdfff) + return yasl_key_label(0x10000 + ((first - 0xd800) << 10) + second - 0xdc00); + } + return 0; +} + static struct yasl_key_event cocoa_key_event(NSEvent *ev, enum yasl_key_action action) { - unsigned short vk = ev.keyCode; struct yasl_key_event k = { - .key = vk, - .keypad = (vk >= kVK_ANSI_Keypad0 && vk <= kVK_ANSI_Keypad9) || - vk == kVK_ANSI_KeypadDecimal || vk == kVK_ANSI_KeypadMultiply || - vk == kVK_ANSI_KeypadPlus || vk == kVK_ANSI_KeypadClear || - vk == kVK_ANSI_KeypadDivide || vk == kVK_ANSI_KeypadEnter || - vk == kVK_ANSI_KeypadMinus || vk == kVK_ANSI_KeypadEquals, + .key = yasl_key_from_cocoa(ev.keyCode), .action = action, .mods = cocoa_mods(ev.modifierFlags), - .base = vk, + .native_code = ev.keyCode, }; - NSString *chars = ev.characters; - if (chars && chars.length > 0) - k.text = [chars characterAtIndex:0]; + /* characters properties are invalid on flagsChanged events. */ + if (ev.type == NSEventTypeKeyDown || ev.type == NSEventTypeKeyUp) { + k.codepoint = cocoa_key_label([ev charactersByApplyingModifiers:0]); + k.shifted = cocoa_key_label([ev charactersByApplyingModifiers:NSEventModifierFlagShift]); + } return k; } @@ -741,9 +750,7 @@ static struct yasl_vector2i dragging_pos(YaslView *view, id<NSDraggingInfo> send struct cocoa_surface *w = self.surface; if (!w) return; on_key_event(w, event, event.isARepeat ? YASL_KEY_REPEAT : YASL_KEY_PRESS); - NSString *chars = event.characters; - if (chars && chars.length > 0) - on_text_input(w, chars.UTF8String, strlen(chars.UTF8String)); + [self interpretKeyEvents:@[event]]; } - (void)keyUp:(NSEvent *)event @@ -818,28 +825,25 @@ static struct yasl_vector2i dragging_pos(YaslView *view, id<NSDraggingInfo> send { struct cocoa_surface *w = self.surface; if (!w) return; - double dx = event.scrollingDeltaX, dy = event.scrollingDeltaY; + double dx = -event.scrollingDeltaX, dy = -event.scrollingDeltaY; if (event.hasPreciseScrollingDeltas) { dx /= SCROLL_POINTS_PER_LINE; dy /= SCROLL_POINTS_PER_LINE; } + if (!isfinite(dx) || !isfinite(dy) || (dx == 0 && dy == 0)) return; w->mods = cocoa_mods(event.modifierFlags); w->pointer = event_pos(w, event); - if (dy != 0.0) { - struct yasl_input_event input_ev = { - .kind = YASL_INPUT_MOUSE, - .surface = &w->base, - .mouse = { - .pos = w->pointer, - .button = dy > 0.0 ? 4 : 5, - .kind = YASL_PTR_SCROLL, - .mods = w->mods, - .scroll_delta = (float)dy, - .scroll_lines = (int)dy, - }, - }; - input_queue_push(&w->input, &input_ev); - } + struct yasl_input_event input_ev = { + .kind = YASL_INPUT_MOUSE, + .surface = &w->base, + .mouse = { + .pos = w->pointer, + .kind = YASL_PTR_SCROLL, + .mods = w->mods, + .scroll = {dx, dy}, + }, + }; + input_queue_push(&w->input, &input_ev); } static NSString *plain_string(id string) @@ -1409,7 +1413,6 @@ static void surface_free(struct cocoa_surface *w) [w->view release]; [w->controller release]; [w->window release]; - free(w->key_text); free(w->preedit); free(w->pixels); free(w); diff --git a/src/common/backend.c b/src/common/backend.c index ccb9c27..23275d6 100644 --- a/src/common/backend.c +++ b/src/common/backend.c @@ -81,10 +81,18 @@ uint32_t yasl_display_caps(const struct yasl_display *d) int yasl_display_dispatch(struct yasl_display *d, int timeout_ms) { - if (!d) return -1; - if (d->ops->display_dispatch_timeout) - return d->ops->display_dispatch_timeout(d, timeout_ms); - return -1; + if (!d) { + errno = EINVAL; + return -1; + } + if (!d->ops->display_dispatch_timeout) { + errno = ENOTSUP; + return -1; + } + errno = 0; + int result = d->ops->display_dispatch_timeout(d, timeout_ms); + if (result < 0 && !errno) errno = EIO; + return result; } void yasl_display_flush(struct yasl_display *d) @@ -127,7 +135,12 @@ bool yasl_display_drag_start(struct yasl_display *d, struct yasl_surface *origin return 0; if (!origin || origin->display != d) return false; - return d->ops->display_drag_start(d, origin, image, l, ud); + if (image && (!image->pixels || image->size.x <= 0 || image->size.y <= 0 || + image->size.x > 32767 || image->size.y > 32767 || + (int64_t)image->size.x * image->size.y * 4 > INT32_MAX)) + return false; + const struct yasl_drag_listener empty = {0}; + return d->ops->display_drag_start(d, origin, image, l ? l : &empty, ud); } void yasl_display_drag_cancel(struct yasl_display *d) @@ -151,7 +164,10 @@ struct yasl_surface *yasl_create_toplevel(struct yasl_display *d, errno = ENOTSUP; return NULL; } - return d->ops->surface_create_toplevel(d, spec, graphics_device); + errno = 0; + struct yasl_surface *s = d->ops->surface_create_toplevel(d, spec, graphics_device); + if (!s && !errno) errno = ENODEV; + return s; } struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d, @@ -160,18 +176,50 @@ struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d, return yasl_create_toplevel(d, spec, NULL); } +static bool popup_spec_valid(const struct yasl_popup_spec *spec) +{ + return spec && spec->size.x > 0 && spec->size.y > 0 && + spec->size.x <= 32767 && spec->size.y <= 32767 && + (int64_t)spec->size.x * spec->size.y * 4 <= INT32_MAX && + spec->anchor.width >= 0 && spec->anchor.height >= 0 && + spec->content_offset.x >= 0 && spec->content_offset.y >= 0 && + spec->content_size.x >= 0 && spec->content_size.y >= 0 && + (int64_t)spec->content_offset.x + spec->content_size.x <= spec->size.x && + (int64_t)spec->content_offset.y + spec->content_size.y <= spec->size.y; +} + struct yasl_surface *yasl_surface_create_popup(struct yasl_surface *parent, const struct yasl_popup_spec *spec) { - if (!parent || !parent->display->ops->surface_create_popup) - return 0; - return parent->display->ops->surface_create_popup(parent, spec); + if (!parent || !popup_spec_valid(spec)) { + errno = EINVAL; + return NULL; + } + if (!(yasl_display_caps(parent->display) & YASL_CAP_POPUPS) || + !parent->display->ops->surface_create_popup) { + errno = ENOTSUP; + return NULL; + } + errno = 0; + struct yasl_surface *s = parent->display->ops->surface_create_popup(parent, spec); + if (!s && !errno) errno = ENODEV; + return s; } bool yasl_surface_popup_reposition(struct yasl_surface *popup, const struct yasl_popup_spec *spec) { - if (!popup || !popup->display->ops->surface_popup_reposition) - return 0; - return popup->display->ops->surface_popup_reposition(popup, spec); + if (!popup || !popup_spec_valid(spec)) { + errno = EINVAL; + return false; + } + if (!(yasl_display_caps(popup->display) & YASL_CAP_POPUPS) || + !popup->display->ops->surface_popup_reposition) { + errno = ENOTSUP; + return false; + } + errno = 0; + bool result = popup->display->ops->surface_popup_reposition(popup, spec); + if (!result && !errno) errno = ENODEV; + return result; } void yasl_surface_destroy(struct yasl_surface *s) diff --git a/src/common/keyboard.c b/src/common/keyboard.c new file mode 100644 index 0000000..80c6702 --- /dev/null +++ b/src/common/keyboard.c @@ -0,0 +1,399 @@ +#include "keyboard.h" +#include "cocoa/keycodes.h" +#include <string.h> + +/* Numeric Linux evdev codes; no platform headers are needed by this table. */ +enum yasl_key yasl_key_from_evdev(uint32_t code) +{ + switch (code) { + case 1: return YASL_KEY_ESCAPE; /* KEY_ESC */ + case 2: return YASL_KEY_1; /* KEY_1 */ + case 3: return YASL_KEY_2; /* KEY_2 */ + case 4: return YASL_KEY_3; /* KEY_3 */ + case 5: return YASL_KEY_4; /* KEY_4 */ + case 6: return YASL_KEY_5; /* KEY_5 */ + case 7: return YASL_KEY_6; /* KEY_6 */ + case 8: return YASL_KEY_7; /* KEY_7 */ + case 9: return YASL_KEY_8; /* KEY_8 */ + case 10: return YASL_KEY_9; /* KEY_9 */ + case 11: return YASL_KEY_0; /* KEY_0 */ + case 12: return YASL_KEY_MINUS; /* KEY_MINUS */ + case 13: return YASL_KEY_EQUAL; /* KEY_EQUAL */ + case 14: return YASL_KEY_BACKSPACE; /* KEY_BACKSPACE */ + case 15: return YASL_KEY_TAB; /* KEY_TAB */ + case 16: return YASL_KEY_Q; /* KEY_Q */ + case 17: return YASL_KEY_W; /* KEY_W */ + case 18: return YASL_KEY_E; /* KEY_E */ + case 19: return YASL_KEY_R; /* KEY_R */ + case 20: return YASL_KEY_T; /* KEY_T */ + case 21: return YASL_KEY_Y; /* KEY_Y */ + case 22: return YASL_KEY_U; /* KEY_U */ + case 23: return YASL_KEY_I; /* KEY_I */ + case 24: return YASL_KEY_O; /* KEY_O */ + case 25: return YASL_KEY_P; /* KEY_P */ + case 26: return YASL_KEY_LEFT_BRACKET; /* KEY_LEFTBRACE */ + case 27: return YASL_KEY_RIGHT_BRACKET; /* KEY_RIGHTBRACE */ + case 28: return YASL_KEY_ENTER; /* KEY_ENTER */ + case 29: return YASL_KEY_LEFT_CONTROL; /* KEY_LEFTCTRL */ + case 30: return YASL_KEY_A; /* KEY_A */ + case 31: return YASL_KEY_S; /* KEY_S */ + case 32: return YASL_KEY_D; /* KEY_D */ + case 33: return YASL_KEY_F; /* KEY_F */ + case 34: return YASL_KEY_G; /* KEY_G */ + case 35: return YASL_KEY_H; /* KEY_H */ + case 36: return YASL_KEY_J; /* KEY_J */ + case 37: return YASL_KEY_K; /* KEY_K */ + case 38: return YASL_KEY_L; /* KEY_L */ + case 39: return YASL_KEY_SEMICOLON; /* KEY_SEMICOLON */ + case 40: return YASL_KEY_APOSTROPHE; /* KEY_APOSTROPHE */ + case 41: return YASL_KEY_GRAVE; /* KEY_GRAVE */ + case 42: return YASL_KEY_LEFT_SHIFT; /* KEY_LEFTSHIFT */ + case 43: return YASL_KEY_BACKSLASH; /* KEY_BACKSLASH */ + case 44: return YASL_KEY_Z; /* KEY_Z */ + case 45: return YASL_KEY_X; /* KEY_X */ + case 46: return YASL_KEY_C; /* KEY_C */ + case 47: return YASL_KEY_V; /* KEY_V */ + case 48: return YASL_KEY_B; /* KEY_B */ + case 49: return YASL_KEY_N; /* KEY_N */ + case 50: return YASL_KEY_M; /* KEY_M */ + case 51: return YASL_KEY_COMMA; /* KEY_COMMA */ + case 52: return YASL_KEY_PERIOD; /* KEY_DOT */ + case 53: return YASL_KEY_SLASH; /* KEY_SLASH */ + case 54: return YASL_KEY_RIGHT_SHIFT; /* KEY_RIGHTSHIFT */ + case 55: return YASL_KEY_KP_MULTIPLY; /* KEY_KPASTERISK */ + case 56: return YASL_KEY_LEFT_ALT; /* KEY_LEFTALT */ + case 57: return YASL_KEY_SPACE; /* KEY_SPACE */ + case 58: return YASL_KEY_CAPS_LOCK; /* KEY_CAPSLOCK */ + case 59: return YASL_KEY_F1; /* KEY_F1 */ + case 60: return YASL_KEY_F2; /* KEY_F2 */ + case 61: return YASL_KEY_F3; /* KEY_F3 */ + case 62: return YASL_KEY_F4; /* KEY_F4 */ + case 63: return YASL_KEY_F5; /* KEY_F5 */ + case 64: return YASL_KEY_F6; /* KEY_F6 */ + case 65: return YASL_KEY_F7; /* KEY_F7 */ + case 66: return YASL_KEY_F8; /* KEY_F8 */ + case 67: return YASL_KEY_F9; /* KEY_F9 */ + case 68: return YASL_KEY_F10; /* KEY_F10 */ + case 69: return YASL_KEY_NUM_LOCK; /* KEY_NUMLOCK */ + case 70: return YASL_KEY_SCROLL_LOCK; /* KEY_SCROLLLOCK */ + case 71: return YASL_KEY_KP_7; /* KEY_KP7 */ + case 72: return YASL_KEY_KP_8; /* KEY_KP8 */ + case 73: return YASL_KEY_KP_9; /* KEY_KP9 */ + case 74: return YASL_KEY_KP_SUBTRACT; /* KEY_KPMINUS */ + case 75: return YASL_KEY_KP_4; /* KEY_KP4 */ + case 76: return YASL_KEY_KP_5; /* KEY_KP5 */ + case 77: return YASL_KEY_KP_6; /* KEY_KP6 */ + case 78: return YASL_KEY_KP_ADD; /* KEY_KPPLUS */ + case 79: return YASL_KEY_KP_1; /* KEY_KP1 */ + case 80: return YASL_KEY_KP_2; /* KEY_KP2 */ + case 81: return YASL_KEY_KP_3; /* KEY_KP3 */ + case 82: return YASL_KEY_KP_0; /* KEY_KP0 */ + case 83: return YASL_KEY_KP_DECIMAL; /* KEY_KPDOT */ + case 86: return YASL_KEY_ISO_BACKSLASH; /* KEY_102ND */ + case 87: return YASL_KEY_F11; /* KEY_F11 */ + case 88: return YASL_KEY_F12; /* KEY_F12 */ + case 89: return YASL_KEY_RO; /* KEY_RO */ + case 92: return YASL_KEY_CONVERT; /* KEY_HENKAN */ + case 93: return YASL_KEY_KANA; /* KEY_KATAKANAHIRAGANA */ + case 94: return YASL_KEY_NONCONVERT; /* KEY_MUHENKAN */ + case 96: return YASL_KEY_KP_ENTER; /* KEY_KPENTER */ + case 97: return YASL_KEY_RIGHT_CONTROL; /* KEY_RIGHTCTRL */ + case 98: return YASL_KEY_KP_DIVIDE; /* KEY_KPSLASH */ + case 99: return YASL_KEY_PRINT_SCREEN; /* KEY_SYSRQ */ + case 100: return YASL_KEY_RIGHT_ALT; /* KEY_RIGHTALT */ + case 102: return YASL_KEY_HOME; /* KEY_HOME */ + case 103: return YASL_KEY_UP; /* KEY_UP */ + case 104: return YASL_KEY_PAGE_UP; /* KEY_PAGEUP */ + case 105: return YASL_KEY_LEFT; /* KEY_LEFT */ + case 106: return YASL_KEY_RIGHT; /* KEY_RIGHT */ + case 107: return YASL_KEY_END; /* KEY_END */ + case 108: return YASL_KEY_DOWN; /* KEY_DOWN */ + case 109: return YASL_KEY_PAGE_DOWN; /* KEY_PAGEDOWN */ + case 110: return YASL_KEY_INSERT; /* KEY_INSERT */ + case 111: return YASL_KEY_DELETE; /* KEY_DELETE */ + case 113: return YASL_KEY_MUTE; /* KEY_MUTE */ + case 114: return YASL_KEY_VOLUME_DOWN; /* KEY_VOLUMEDOWN */ + case 115: return YASL_KEY_VOLUME_UP; /* KEY_VOLUMEUP */ + case 117: return YASL_KEY_KP_EQUAL; /* KEY_KPEQUAL */ + case 119: return YASL_KEY_PAUSE; /* KEY_PAUSE */ + case 121: return YASL_KEY_KP_COMMA; /* KEY_KPCOMMA */ + case 124: return YASL_KEY_YEN; /* KEY_YEN */ + case 125: return YASL_KEY_LEFT_SUPER; /* KEY_LEFTMETA */ + case 126: return YASL_KEY_RIGHT_SUPER; /* KEY_RIGHTMETA */ + case 127: return YASL_KEY_MENU; /* KEY_COMPOSE */ + case 183: return YASL_KEY_F13; /* KEY_F13 */ + case 184: return YASL_KEY_F14; /* KEY_F14 */ + case 185: return YASL_KEY_F15; /* KEY_F15 */ + case 186: return YASL_KEY_F16; /* KEY_F16 */ + case 187: return YASL_KEY_F17; /* KEY_F17 */ + case 188: return YASL_KEY_F18; /* KEY_F18 */ + case 189: return YASL_KEY_F19; /* KEY_F19 */ + case 190: return YASL_KEY_F20; /* KEY_F20 */ + case 191: return YASL_KEY_F21; /* KEY_F21 */ + case 192: return YASL_KEY_F22; /* KEY_F22 */ + case 193: return YASL_KEY_F23; /* KEY_F23 */ + case 194: return YASL_KEY_F24; /* KEY_F24 */ + default: return YASL_KEY_UNKNOWN; + } +} + +enum yasl_key yasl_key_from_cocoa(uint32_t code) +{ + switch (code) { + case kVK_ANSI_A: return YASL_KEY_A; + case kVK_ANSI_B: return YASL_KEY_B; + case kVK_ANSI_C: return YASL_KEY_C; + case kVK_ANSI_D: return YASL_KEY_D; + case kVK_ANSI_E: return YASL_KEY_E; + case kVK_ANSI_F: return YASL_KEY_F; + case kVK_ANSI_G: return YASL_KEY_G; + case kVK_ANSI_H: return YASL_KEY_H; + case kVK_ANSI_I: return YASL_KEY_I; + case kVK_ANSI_J: return YASL_KEY_J; + case kVK_ANSI_K: return YASL_KEY_K; + case kVK_ANSI_L: return YASL_KEY_L; + case kVK_ANSI_M: return YASL_KEY_M; + case kVK_ANSI_N: return YASL_KEY_N; + case kVK_ANSI_O: return YASL_KEY_O; + case kVK_ANSI_P: return YASL_KEY_P; + case kVK_ANSI_Q: return YASL_KEY_Q; + case kVK_ANSI_R: return YASL_KEY_R; + case kVK_ANSI_S: return YASL_KEY_S; + case kVK_ANSI_T: return YASL_KEY_T; + case kVK_ANSI_U: return YASL_KEY_U; + case kVK_ANSI_V: return YASL_KEY_V; + case kVK_ANSI_W: return YASL_KEY_W; + case kVK_ANSI_X: return YASL_KEY_X; + case kVK_ANSI_Y: return YASL_KEY_Y; + case kVK_ANSI_Z: return YASL_KEY_Z; + case kVK_ANSI_0: return YASL_KEY_0; + case kVK_ANSI_1: return YASL_KEY_1; + case kVK_ANSI_2: return YASL_KEY_2; + case kVK_ANSI_3: return YASL_KEY_3; + case kVK_ANSI_4: return YASL_KEY_4; + case kVK_ANSI_5: return YASL_KEY_5; + case kVK_ANSI_6: return YASL_KEY_6; + case kVK_ANSI_7: return YASL_KEY_7; + case kVK_ANSI_8: return YASL_KEY_8; + case kVK_ANSI_9: return YASL_KEY_9; + case kVK_Return: return YASL_KEY_ENTER; + case kVK_Tab: return YASL_KEY_TAB; + case kVK_Space: return YASL_KEY_SPACE; + case kVK_Escape: return YASL_KEY_ESCAPE; + case kVK_Home: return YASL_KEY_HOME; + case kVK_End: return YASL_KEY_END; + case kVK_Delete: return YASL_KEY_BACKSPACE; + case kVK_ForwardDelete: return YASL_KEY_DELETE; + case kVK_PageUp: return YASL_KEY_PAGE_UP; + case kVK_PageDown: return YASL_KEY_PAGE_DOWN; + case kVK_Help: return YASL_KEY_INSERT; + case kVK_LeftArrow: return YASL_KEY_LEFT; + case kVK_RightArrow: return YASL_KEY_RIGHT; + case kVK_DownArrow: return YASL_KEY_DOWN; + case kVK_UpArrow: return YASL_KEY_UP; + case kVK_Command: return YASL_KEY_LEFT_SUPER; + case kVK_Shift: return YASL_KEY_LEFT_SHIFT; + case kVK_CapsLock: return YASL_KEY_CAPS_LOCK; + case kVK_Option: return YASL_KEY_LEFT_ALT; + case kVK_Control: return YASL_KEY_LEFT_CONTROL; + case kVK_RightCommand: return YASL_KEY_RIGHT_SUPER; + case kVK_RightShift: return YASL_KEY_RIGHT_SHIFT; + case kVK_RightOption: return YASL_KEY_RIGHT_ALT; + case kVK_RightControl: return YASL_KEY_RIGHT_CONTROL; + case kVK_ContextualMenu: return YASL_KEY_MENU; + case kVK_VolumeUp: return YASL_KEY_VOLUME_UP; + case kVK_VolumeDown: return YASL_KEY_VOLUME_DOWN; + case kVK_Mute: return YASL_KEY_MUTE; + case kVK_ISO_Section: return YASL_KEY_ISO_BACKSLASH; + case kVK_JIS_Yen: return YASL_KEY_YEN; + case kVK_JIS_Underscore: return YASL_KEY_RO; + case kVK_JIS_Eisu: return YASL_KEY_EISU; + case kVK_JIS_Kana: return YASL_KEY_KANA; + case kVK_JIS_KeypadComma: return YASL_KEY_KP_COMMA; + case kVK_ANSI_Equal: return YASL_KEY_EQUAL; + case kVK_ANSI_Minus: return YASL_KEY_MINUS; + case kVK_ANSI_LeftBracket: return YASL_KEY_LEFT_BRACKET; + case kVK_ANSI_RightBracket: return YASL_KEY_RIGHT_BRACKET; + case kVK_ANSI_Quote: return YASL_KEY_APOSTROPHE; + case kVK_ANSI_Semicolon: return YASL_KEY_SEMICOLON; + case kVK_ANSI_Backslash: return YASL_KEY_BACKSLASH; + case kVK_ANSI_Comma: return YASL_KEY_COMMA; + case kVK_ANSI_Slash: return YASL_KEY_SLASH; + case kVK_ANSI_Period: return YASL_KEY_PERIOD; + case kVK_ANSI_Grave: return YASL_KEY_GRAVE; + case kVK_F1: return YASL_KEY_F1; + case kVK_F2: return YASL_KEY_F2; + case kVK_F3: return YASL_KEY_F3; + case kVK_F4: return YASL_KEY_F4; + case kVK_F5: return YASL_KEY_F5; + case kVK_F6: return YASL_KEY_F6; + case kVK_F7: return YASL_KEY_F7; + case kVK_F8: return YASL_KEY_F8; + case kVK_F9: return YASL_KEY_F9; + case kVK_F10: return YASL_KEY_F10; + case kVK_F11: return YASL_KEY_F11; + case kVK_F12: return YASL_KEY_F12; + case kVK_F13: return YASL_KEY_F13; + case kVK_F14: return YASL_KEY_F14; + case kVK_F15: return YASL_KEY_F15; + case kVK_F16: return YASL_KEY_F16; + case kVK_F17: return YASL_KEY_F17; + case kVK_F18: return YASL_KEY_F18; + case kVK_F19: return YASL_KEY_F19; + case kVK_F20: return YASL_KEY_F20; + case kVK_ANSI_Keypad0: return YASL_KEY_KP_0; + case kVK_ANSI_Keypad1: return YASL_KEY_KP_1; + case kVK_ANSI_Keypad2: return YASL_KEY_KP_2; + case kVK_ANSI_Keypad3: return YASL_KEY_KP_3; + case kVK_ANSI_Keypad4: return YASL_KEY_KP_4; + case kVK_ANSI_Keypad5: return YASL_KEY_KP_5; + case kVK_ANSI_Keypad6: return YASL_KEY_KP_6; + case kVK_ANSI_Keypad7: return YASL_KEY_KP_7; + case kVK_ANSI_Keypad8: return YASL_KEY_KP_8; + case kVK_ANSI_Keypad9: return YASL_KEY_KP_9; + case kVK_ANSI_KeypadDecimal: return YASL_KEY_KP_DECIMAL; + case kVK_ANSI_KeypadMultiply: return YASL_KEY_KP_MULTIPLY; + case kVK_ANSI_KeypadPlus: return YASL_KEY_KP_ADD; + case kVK_ANSI_KeypadClear: return YASL_KEY_KP_CLEAR; + case kVK_ANSI_KeypadDivide: return YASL_KEY_KP_DIVIDE; + case kVK_ANSI_KeypadEnter: return YASL_KEY_KP_ENTER; + case kVK_ANSI_KeypadMinus: return YASL_KEY_KP_SUBTRACT; + case kVK_ANSI_KeypadEquals: return YASL_KEY_KP_EQUAL; + default: return YASL_KEY_UNKNOWN; + } +} + +/* XKB standard physical key names, independent of server numeric keycodes. */ +enum yasl_key yasl_key_from_xkb_name(const char name[4]) +{ + static const struct { char name[4]; enum yasl_key key; } keys[] = { + {{'T', 'L', 'D', 'E'}, YASL_KEY_GRAVE}, + {{'A', 'E', '0', '1'}, YASL_KEY_1}, + {{'A', 'E', '0', '2'}, YASL_KEY_2}, + {{'A', 'E', '0', '3'}, YASL_KEY_3}, + {{'A', 'E', '0', '4'}, YASL_KEY_4}, + {{'A', 'E', '0', '5'}, YASL_KEY_5}, + {{'A', 'E', '0', '6'}, YASL_KEY_6}, + {{'A', 'E', '0', '7'}, YASL_KEY_7}, + {{'A', 'E', '0', '8'}, YASL_KEY_8}, + {{'A', 'E', '0', '9'}, YASL_KEY_9}, + {{'A', 'E', '1', '0'}, YASL_KEY_0}, + {{'A', 'E', '1', '1'}, YASL_KEY_MINUS}, + {{'A', 'E', '1', '2'}, YASL_KEY_EQUAL}, + {{'B', 'K', 'S', 'P'}, YASL_KEY_BACKSPACE}, + {{'T', 'A', 'B', 0}, YASL_KEY_TAB}, + {{'A', 'D', '0', '1'}, YASL_KEY_Q}, + {{'A', 'D', '0', '2'}, YASL_KEY_W}, + {{'A', 'D', '0', '3'}, YASL_KEY_E}, + {{'A', 'D', '0', '4'}, YASL_KEY_R}, + {{'A', 'D', '0', '5'}, YASL_KEY_T}, + {{'A', 'D', '0', '6'}, YASL_KEY_Y}, + {{'A', 'D', '0', '7'}, YASL_KEY_U}, + {{'A', 'D', '0', '8'}, YASL_KEY_I}, + {{'A', 'D', '0', '9'}, YASL_KEY_O}, + {{'A', 'D', '1', '0'}, YASL_KEY_P}, + {{'A', 'D', '1', '1'}, YASL_KEY_LEFT_BRACKET}, + {{'A', 'D', '1', '2'}, YASL_KEY_RIGHT_BRACKET}, + {{'B', 'K', 'S', 'L'}, YASL_KEY_BACKSLASH}, + {{'R', 'T', 'R', 'N'}, YASL_KEY_ENTER}, + {{'C', 'A', 'P', 'S'}, YASL_KEY_CAPS_LOCK}, + {{'A', 'C', '0', '1'}, YASL_KEY_A}, + {{'A', 'C', '0', '2'}, YASL_KEY_S}, + {{'A', 'C', '0', '3'}, YASL_KEY_D}, + {{'A', 'C', '0', '4'}, YASL_KEY_F}, + {{'A', 'C', '0', '5'}, YASL_KEY_G}, + {{'A', 'C', '0', '6'}, YASL_KEY_H}, + {{'A', 'C', '0', '7'}, YASL_KEY_J}, + {{'A', 'C', '0', '8'}, YASL_KEY_K}, + {{'A', 'C', '0', '9'}, YASL_KEY_L}, + {{'A', 'C', '1', '0'}, YASL_KEY_SEMICOLON}, + {{'A', 'C', '1', '1'}, YASL_KEY_APOSTROPHE}, + {{'L', 'F', 'S', 'H'}, YASL_KEY_LEFT_SHIFT}, + {{'L', 'S', 'G', 'T'}, YASL_KEY_ISO_BACKSLASH}, + {{'A', 'B', '0', '1'}, YASL_KEY_Z}, + {{'A', 'B', '0', '2'}, YASL_KEY_X}, + {{'A', 'B', '0', '3'}, YASL_KEY_C}, + {{'A', 'B', '0', '4'}, YASL_KEY_V}, + {{'A', 'B', '0', '5'}, YASL_KEY_B}, + {{'A', 'B', '0', '6'}, YASL_KEY_N}, + {{'A', 'B', '0', '7'}, YASL_KEY_M}, + {{'A', 'B', '0', '8'}, YASL_KEY_COMMA}, + {{'A', 'B', '0', '9'}, YASL_KEY_PERIOD}, + {{'A', 'B', '1', '0'}, YASL_KEY_SLASH}, + {{'R', 'T', 'S', 'H'}, YASL_KEY_RIGHT_SHIFT}, + {{'L', 'C', 'T', 'L'}, YASL_KEY_LEFT_CONTROL}, + {{'L', 'W', 'I', 'N'}, YASL_KEY_LEFT_SUPER}, + {{'L', 'A', 'L', 'T'}, YASL_KEY_LEFT_ALT}, + {{'S', 'P', 'C', 'E'}, YASL_KEY_SPACE}, + {{'R', 'A', 'L', 'T'}, YASL_KEY_RIGHT_ALT}, + {{'R', 'W', 'I', 'N'}, YASL_KEY_RIGHT_SUPER}, + {{'C', 'O', 'M', 'P'}, YASL_KEY_MENU}, + {{'R', 'C', 'T', 'L'}, YASL_KEY_RIGHT_CONTROL}, + {{'E', 'S', 'C', 0}, YASL_KEY_ESCAPE}, + {{'F', 'K', '0', '1'}, YASL_KEY_F1}, + {{'F', 'K', '0', '2'}, YASL_KEY_F2}, + {{'F', 'K', '0', '3'}, YASL_KEY_F3}, + {{'F', 'K', '0', '4'}, YASL_KEY_F4}, + {{'F', 'K', '0', '5'}, YASL_KEY_F5}, + {{'F', 'K', '0', '6'}, YASL_KEY_F6}, + {{'F', 'K', '0', '7'}, YASL_KEY_F7}, + {{'F', 'K', '0', '8'}, YASL_KEY_F8}, + {{'F', 'K', '0', '9'}, YASL_KEY_F9}, + {{'F', 'K', '1', '0'}, YASL_KEY_F10}, + {{'F', 'K', '1', '1'}, YASL_KEY_F11}, + {{'F', 'K', '1', '2'}, YASL_KEY_F12}, + {{'P', 'R', 'S', 'C'}, YASL_KEY_PRINT_SCREEN}, + {{'S', 'C', 'L', 'K'}, YASL_KEY_SCROLL_LOCK}, + {{'P', 'A', 'U', 'S'}, YASL_KEY_PAUSE}, + {{'I', 'N', 'S', 0}, YASL_KEY_INSERT}, + {{'H', 'O', 'M', 'E'}, YASL_KEY_HOME}, + {{'P', 'G', 'U', 'P'}, YASL_KEY_PAGE_UP}, + {{'D', 'E', 'L', 'E'}, YASL_KEY_DELETE}, + {{'E', 'N', 'D', 0}, YASL_KEY_END}, + {{'P', 'G', 'D', 'N'}, YASL_KEY_PAGE_DOWN}, + {{'U', 'P', 0, 0}, YASL_KEY_UP}, + {{'L', 'E', 'F', 'T'}, YASL_KEY_LEFT}, + {{'D', 'O', 'W', 'N'}, YASL_KEY_DOWN}, + {{'R', 'G', 'H', 'T'}, YASL_KEY_RIGHT}, + {{'N', 'M', 'L', 'K'}, YASL_KEY_NUM_LOCK}, + {{'K', 'P', 'D', 'V'}, YASL_KEY_KP_DIVIDE}, + {{'K', 'P', 'M', 'U'}, YASL_KEY_KP_MULTIPLY}, + {{'K', 'P', 'S', 'U'}, YASL_KEY_KP_SUBTRACT}, + {{'K', 'P', '7', 0}, YASL_KEY_KP_7}, + {{'K', 'P', '8', 0}, YASL_KEY_KP_8}, + {{'K', 'P', '9', 0}, YASL_KEY_KP_9}, + {{'K', 'P', 'A', 'D'}, YASL_KEY_KP_ADD}, + {{'K', 'P', '4', 0}, YASL_KEY_KP_4}, + {{'K', 'P', '5', 0}, YASL_KEY_KP_5}, + {{'K', 'P', '6', 0}, YASL_KEY_KP_6}, + {{'K', 'P', '1', 0}, YASL_KEY_KP_1}, + {{'K', 'P', '2', 0}, YASL_KEY_KP_2}, + {{'K', 'P', '3', 0}, YASL_KEY_KP_3}, + {{'K', 'P', 'E', 'N'}, YASL_KEY_KP_ENTER}, + {{'K', 'P', '0', 0}, YASL_KEY_KP_0}, + {{'K', 'P', 'D', 'L'}, YASL_KEY_KP_DECIMAL}, + {{'K', 'P', 'E', 'Q'}, YASL_KEY_KP_EQUAL}, + {{'F', 'K', '1', '3'}, YASL_KEY_F13}, + {{'F', 'K', '1', '4'}, YASL_KEY_F14}, + {{'F', 'K', '1', '5'}, YASL_KEY_F15}, + {{'F', 'K', '1', '6'}, YASL_KEY_F16}, + {{'F', 'K', '1', '7'}, YASL_KEY_F17}, + {{'F', 'K', '1', '8'}, YASL_KEY_F18}, + {{'F', 'K', '1', '9'}, YASL_KEY_F19}, + {{'F', 'K', '2', '0'}, YASL_KEY_F20}, + {{'F', 'K', '2', '1'}, YASL_KEY_F21}, + {{'F', 'K', '2', '2'}, YASL_KEY_F22}, + {{'F', 'K', '2', '3'}, YASL_KEY_F23}, + {{'F', 'K', '2', '4'}, YASL_KEY_F24}, + {{'H', 'K', 'T', 'G'}, YASL_KEY_KANA}, + {{'A', 'B', '1', '1'}, YASL_KEY_RO}, + {{'H', 'E', 'N', 'K'}, YASL_KEY_CONVERT}, + {{'M', 'U', 'H', 'E'}, YASL_KEY_NONCONVERT}, + {{'A', 'E', '1', '3'}, YASL_KEY_YEN}, + {{'M', 'U', 'T', 'E'}, YASL_KEY_MUTE}, + {{'I', '1', '2', '9'}, YASL_KEY_KP_COMMA}, + }; + for (size_t i = 0; i < sizeof(keys) / sizeof(keys[0]); i++) + if (memcmp(keys[i].name, name, 4) == 0) return keys[i].key; + return YASL_KEY_UNKNOWN; +} diff --git a/src/common/keyboard.h b/src/common/keyboard.h new file mode 100644 index 0000000..50ddbb3 --- /dev/null +++ b/src/common/keyboard.h @@ -0,0 +1,18 @@ +#ifndef YASL_COMMON_KEYBOARD_H +#define YASL_COMMON_KEYBOARD_H + +#include "yasl/yasl.h" + +enum yasl_key yasl_key_from_evdev(uint32_t code); +enum yasl_key yasl_key_from_xkb_name(const char name[4]); +enum yasl_key yasl_key_from_cocoa(uint32_t code); + +/* Layout labels omit controls, invalid Unicode, and Cocoa function-key PUA. */ +static inline uint32_t yasl_key_label(uint32_t cp) +{ + return cp >= 0x20 && cp != 0x7f && cp <= 0x10ffff && + !(cp >= 0x80 && cp <= 0x9f) && !(cp >= 0xd800 && cp <= 0xdfff) && + !(cp >= 0xf700 && cp <= 0xf7ff) ? cp : 0; +} + +#endif diff --git a/src/common/meson.build b/src/common/meson.build index ddd0194..1247ff5 100644 --- a/src/common/meson.build +++ b/src/common/meson.build @@ -1 +1 @@ -sources += files('backend.c', 'input.c', 'loop.c', 'native.c', 'timing.c', 'utf8.c') +sources += files('backend.c', 'input.c', 'keyboard.c', 'loop.c', 'native.c', 'timing.c', 'utf8.c') diff --git a/src/common/utf8.c b/src/common/utf8.c index 1d4cf13..78a5d8e 100644 --- a/src/common/utf8.c +++ b/src/common/utf8.c @@ -1,3 +1,4 @@ +#include "utf8.h" #include <stdlib.h> #include <string.h> #include <stdbool.h> @@ -12,11 +13,12 @@ bool yasl_utf8_validate(const char *str, size_t len) { + if (!str) return len == 0; const unsigned char *p = (const unsigned char *)str; const unsigned char *end = p + len; while (p < end) { - while (p + 8 <= end) { + while ((size_t)(end - p) >= 8) { uint64_t v; memcpy(&v, p, 8); if (v & 0x8080808080808080ull) @@ -28,18 +30,18 @@ bool yasl_utf8_validate(const char *str, size_t len) if (likely(*p < 0x80)) { p++; } else if ((*p & 0xe0) == 0xc0) { - if (unlikely(p + 1 >= end || (p[1] & 0xc0) != 0x80 || (*p & 0x1e) == 0)) + if (unlikely(end - p < 2 || (p[1] & 0xc0) != 0x80 || (*p & 0x1e) == 0)) return false; p += 2; } else if ((*p & 0xf0) == 0xe0) { - if (unlikely(p + 2 >= end || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80)) + if (unlikely(end - p < 3 || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80)) return false; uint32_t cp = ((p[0] & 0x0f) << 12) | ((p[1] & 0x3f) << 6) | (p[2] & 0x3f); if (unlikely(cp < 0x800 || (cp >= 0xd800 && cp <= 0xdfff))) return false; p += 3; } else if ((*p & 0xf8) == 0xf0) { - if (unlikely(p + 3 >= end || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80 || (p[3] & 0xc0) != 0x80)) + if (unlikely(end - p < 4 || (p[1] & 0xc0) != 0x80 || (p[2] & 0xc0) != 0x80 || (p[3] & 0xc0) != 0x80)) return false; uint32_t cp = ((p[0] & 0x07) << 18) | ((p[1] & 0x3f) << 12) | ((p[2] & 0x3f) << 6) | (p[3] & 0x3f); if (unlikely(cp < 0x10000 || cp > 0x10ffff)) @@ -52,6 +54,46 @@ bool yasl_utf8_validate(const char *str, size_t len) return true; } +char *yasl_utf8_from_latin1(const char *str, size_t len, size_t *out_len) +{ + if (len > (SIZE_MAX - 1) / 2) return NULL; + char *out = malloc(len * 2 + 1); + if (!out) return NULL; + size_t n = 0; + for (size_t i = 0; i < len; i++) { + unsigned char ch = (unsigned char)str[i]; + if (ch < 0x80) out[n++] = (char)ch; + else { + out[n++] = (char)(0xc0 | (ch >> 6)); + out[n++] = (char)(0x80 | (ch & 0x3f)); + } + } + out[n] = '\0'; + *out_len = n; + return out; +} + +char *yasl_utf8_to_latin1(const char *str, size_t *out_len) +{ + char *out = malloc(strlen(str) + 1); + if (!out) return NULL; + const unsigned char *p = (const unsigned char *)str; + size_t n = 0; + while (*p) { + if (*p < 0x80) out[n++] = (char)*p++; + else if ((*p == 0xc2 || *p == 0xc3) && (p[1] & 0xc0) == 0x80) { + out[n++] = (char)(((*p & 3) << 6) | (p[1] & 0x3f)); + p += 2; + } else { + free(out); + return NULL; + } + } + out[n] = '\0'; + *out_len = n; + return out; +} + char *yasl_utf8_sanitize_dup(const char *str) { if (unlikely(!str)) return NULL; diff --git a/src/common/utf8.h b/src/common/utf8.h new file mode 100644 index 0000000..f31c99d --- /dev/null +++ b/src/common/utf8.h @@ -0,0 +1,14 @@ +#ifndef YASL_COMMON_UTF8_H +#define YASL_COMMON_UTF8_H + +#include <stdbool.h> +#include <stddef.h> + +bool yasl_utf8_validate(const char *str, size_t len); +char *yasl_utf8_sanitize_dup(const char *str); +/* Owned conversions for X11 STRING interoperability. to_latin1 rejects text + * outside Latin-1; byte lengths exclude the allocated NUL terminator. */ +char *yasl_utf8_from_latin1(const char *str, size_t len, size_t *out_len); +char *yasl_utf8_to_latin1(const char *str, size_t *out_len); + +#endif diff --git a/src/wayland/clipboard.c b/src/wayland/clipboard.c index e3eec0f..a6922c4 100644 --- a/src/wayland/clipboard.c +++ b/src/wayland/clipboard.c @@ -131,9 +131,11 @@ static int transfer_io(int fd, short events, void *ud) if (n > 0) { t->len += (size_t)n; } else if (n == 0) { - t->owner->receive(t->text ? t->text : "", t->len, t->uri_list, - t->drop_surface, t->owner->ud); - transfer_end(t, true); + bool valid = yasl_utf8_validate(t->text, t->len); + if (valid) + t->owner->receive(t->text ? t->text : "", t->len, t->uri_list, + t->drop_surface, t->owner->ud); + transfer_end(t, valid); } else if (errno != EAGAIN && errno != EINTR) transfer_destroy(t); } return 0; diff --git a/src/wayland/ime.c b/src/wayland/ime.c index 74db53f..bd9375b 100644 --- a/src/wayland/ime.c +++ b/src/wayland/ime.c @@ -98,6 +98,7 @@ static void text_input_preedit_string(void *data, (void)text_input; struct wayland_surface *w = ((struct seat *)data)->ime_focus; if (!w) return; + keyboard_text_reset((struct seat *)data); free(w->ime_preedit); w->ime_preedit = text ? strndup(text, IME_TEXT_MAX) : NULL; int len = w->ime_preedit ? (int)strlen(w->ime_preedit) : 0; @@ -113,6 +114,7 @@ static void text_input_commit_string(void *data, (void)text_input; struct wayland_surface *w = ((struct seat *)data)->ime_focus; if (!w) return; + keyboard_text_reset((struct seat *)data); free(w->ime_commit); w->ime_commit = (text && text[0]) ? strndup(text, IME_TEXT_MAX) : NULL; } diff --git a/src/wayland/internal.h b/src/wayland/internal.h index ad6531b..b687a61 100644 --- a/src/wayland/internal.h +++ b/src/wayland/internal.h @@ -5,6 +5,7 @@ #include "api.h" #include "common/timing.h" +#include "common/utf8.h" #include "clipboard.h" #include <wayland-client.h> @@ -38,6 +39,7 @@ #include <unistd.h> #include <xkbcommon/xkbcommon.h> #include <xkbcommon/xkbcommon-keysyms.h> +#include <xkbcommon/xkbcommon-compose.h> #define NBUF 3 @@ -140,6 +142,8 @@ struct seat { struct clipboard *clipboard; struct xkb_keymap *xkb_keymap; struct xkb_state *xkb_state; + struct xkb_compose_state *compose; + bool compose_attempted; uint64_t repeat_started_ns; struct wayland_surface *pointer_focus; struct wayland_surface *keyboard_focus; @@ -152,8 +156,10 @@ struct seat { struct touch_point *touch_primary; uint64_t pointer_buttons; uint64_t tool_buttons; - double axis_v, axis_h, frame_v; - double touch_scroll_y, touch_scroll_rest; + double axis[2], axis_value120[2]; + int64_t axis_discrete[2]; + bool axis_has_value120[2], axis_has_discrete[2]; + double touch_scroll_y; /* Embedded structs */ xkb_mod_mask_t input_mod_masks[8]; @@ -174,18 +180,12 @@ struct seat { uint32_t press_serial; uint32_t pointer_serial; int cursor_shape; - int frame_v120; - int axis_discrete_v, axis_discrete_h; - int axis_value120_v, axis_value120_h; struct yasl_pointer_pen pen; int tool_wheel; /* 1-byte booleans grouped tightly */ bool input_mods_ready; bool repeat_held; - bool axis_has_v120_v; - bool axis_has_v120_h; - bool axis_smooth; bool motion_pending; bool ptr_left_motion; bool tool_motion; @@ -325,8 +325,6 @@ struct wayland_surface { bool want_draw; }; -char *yasl_utf8_sanitize_dup(const char *str); -bool yasl_utf8_validate(const char *str, size_t len); int device_px(int logical, uint32_t scale_120); bool buffer_size(int width, int height, size_t *bytes); @@ -415,6 +413,7 @@ void seat_pointer_reset(struct seat *s); extern const struct zwp_text_input_v3_listener text_input_listener; void ime_reset(struct wayland_surface *w); +void keyboard_text_reset(struct seat *s); void ime_send_caret(struct wayland_surface *w); int surface_init_shell(struct wayland_surface *w, const char *title); diff --git a/src/wayland/keyboard.c b/src/wayland/keyboard.c index 11c7f3f..f1170c6 100644 --- a/src/wayland/keyboard.c +++ b/src/wayland/keyboard.c @@ -1,8 +1,14 @@ #include "internal.h" +#include "common/keyboard.h" #define XKB_EVDEV_OFFSET 8 #define KEYMAP_MAX_BYTES (8u * 1024 * 1024) +void keyboard_text_reset(struct seat *s) +{ + if (s->compose) xkb_compose_state_reset(s->compose); +} + void keyboard_repeat_stop(struct seat *s) { if (!s->repeat_held) return; @@ -28,11 +34,10 @@ void keyboard_repeat_sync(struct seat *s) timerfd_settime(s->repeat_fd, 0, &timer, NULL); } -static const char *const input_mod_names[8] = { +static const char *const input_mod_names[5] = { XKB_MOD_NAME_SHIFT, XKB_MOD_NAME_ALT, XKB_MOD_NAME_CTRL, XKB_MOD_NAME_LOGO, - "Hyper", "Meta", - XKB_MOD_NAME_CAPS, XKB_MOD_NAME_NUM + XKB_MOD_NAME_CAPS }; static bool mod_active(const struct seat *s, const char *name) @@ -48,7 +53,7 @@ static void resolve_input_mod_masks(struct seat *s) if (!probe) return; for (unsigned real = 0; real < 8; real++) { xkb_state_update_mask(probe, 1u << real, 0, 0, 0, 0, 0); - for (unsigned i = 0; i < 8; i++) { + for (unsigned i = 0; i < 5; i++) { if (xkb_state_mod_name_is_active(probe, input_mod_names[i], XKB_STATE_MODS_EFFECTIVE) > 0) s->input_mod_masks[i] |= 1u << real; @@ -64,6 +69,7 @@ static void keyboard_keymap(void *data, struct wl_keyboard *keyboard, (void)keyboard; struct seat *s = data; keyboard_repeat_stop(s); + keyboard_text_reset(s); s->input_mods_ready = false; if (format != WL_KEYBOARD_KEYMAP_FORMAT_XKB_V1) { close(fd); @@ -116,6 +122,7 @@ static void keyboard_reset_keys(struct seat *s, struct wayland_surface *w) { (void)w; keyboard_repeat_stop(s); + keyboard_text_reset(s); } bool conn_keyboard_on(const struct wayland_display *c, const struct wayland_surface *w, @@ -194,7 +201,7 @@ static unsigned input_modifiers(struct seat *s) unsigned mods = 0; xkb_mod_mask_t reported = 0; - for (unsigned i = 0; i < 8; i++) { + for (unsigned i = 0; i < 5; i++) { xkb_mod_mask_t mask = s->input_mod_masks[i]; if (mask && (mask & ~reported) && mod_active(s, input_mod_names[i])) { mods |= 1u << i; @@ -215,23 +222,75 @@ static struct yasl_key_event xkb_key_event(struct seat *s, uint32_t key, enum yasl_key_action action) { uint32_t code = key + XKB_EVDEV_OFFSET; - xkb_keysym_t sym = xkb_state_key_get_one_sym(s->xkb_state, code); xkb_layout_index_t layout = xkb_state_key_get_layout(s->xkb_state, code); struct yasl_key_event k = { - .key = sym, - .keypad = key >= KEY_KP0 && key <= KEY_KPCOMMA, + .key = yasl_key_from_evdev(key), .action = action, .mods = input_modifiers(s), - .codepoint = key_codepoint_at_level(s, key, layout, 0), - .shifted = key_codepoint_at_level(s, key, layout, 1), - .base = key, - .text = xkb_state_key_get_utf32(s->xkb_state, code), + .codepoint = yasl_key_label(key_codepoint_at_level(s, key, layout, 0)), + .shifted = yasl_key_label(key_codepoint_at_level(s, key, layout, 1)), + .native_code = key, }; - if (!k.codepoint) k.codepoint = xkb_keysym_to_utf32(sym); return k; } +static void keyboard_text(struct seat *s, struct wayland_surface *w, uint32_t key) +{ + uint32_t code = key + XKB_EVDEV_OFFSET; + unsigned mods = input_modifiers(s); + if ((mods & (YASL_MOD_CTRL | YASL_MOD_SUPER)) || + ((mods & YASL_MOD_ALT) && + !xkb_state_mod_index_is_consumed(s->xkb_state, code, s->mod_alt))) { + keyboard_text_reset(s); + return; + } + if (!s->compose_attempted) { + s->compose_attempted = true; + const char *locale = getenv("LC_ALL"); + if (!locale || !*locale) locale = getenv("LC_CTYPE"); + if (!locale || !*locale) locale = getenv("LANG"); + if (!locale || !*locale) locale = "C.UTF-8"; + struct xkb_compose_table *table = xkb_compose_table_new_from_locale( + s->conn->xkb_ctx, locale, XKB_COMPOSE_COMPILE_NO_FLAGS); + if (table) { + s->compose = xkb_compose_state_new(table, XKB_COMPOSE_STATE_NO_FLAGS); + xkb_compose_table_unref(table); + } + } + bool composed = false; + if (s->compose) { + xkb_compose_state_feed(s->compose, xkb_state_key_get_one_sym(s->xkb_state, code)); + switch (xkb_compose_state_get_status(s->compose)) { + case XKB_COMPOSE_COMPOSING: return; + case XKB_COMPOSE_CANCELLED: keyboard_text_reset(s); return; + case XKB_COMPOSE_COMPOSED: composed = true; break; + default: break; + } + } + int len = composed ? xkb_compose_state_get_utf8(s->compose, NULL, 0) : + xkb_state_key_get_utf8(s->xkb_state, code, NULL, 0); + if (len > 0) { + char local[128]; + char *text = (size_t)len < sizeof(local) ? local : malloc((size_t)len + 1); + if (text) { + if (composed) xkb_compose_state_get_utf8(s->compose, text, (size_t)len + 1); + else xkb_state_key_get_utf8(s->xkb_state, code, text, (size_t)len + 1); + /* Editing commands belong to key events, not text insertion. */ + if ((unsigned char)text[0] >= 0x20 && text[0] != 0x7f) { + struct yasl_input_event ev = {.kind = YASL_INPUT_TEXT, + .surface = &w->base, .text = {text, (size_t)len}}; + input_queue_push(&w->input, &ev); + } + if (text != local) free(text); + } else { + struct yasl_input_event ev = {.kind = YASL_INPUT_RESET, .surface = &w->base}; + input_queue_push(&w->input, &ev); + } + } + if (composed) keyboard_text_reset(s); +} + static bool keyboard_dispatch_key(struct seat *s, struct wayland_surface *w, uint32_t key, enum yasl_key_action action) { @@ -243,7 +302,11 @@ static bool keyboard_dispatch_key(struct seat *s, struct wayland_surface *w, uin .surface = &w->base, .key = k, }; - input_queue_push(&w->input, &ev); + if (!input_queue_push(&w->input, &ev)) { + keyboard_text_reset(s); + return false; + } + if (action != YASL_KEY_RELEASE) keyboard_text(s, w, key); return action != YASL_KEY_RELEASE; } @@ -351,7 +414,8 @@ int seat_modifiers(const struct seat *s) return (mod_index_active(s, s->mod_shift) * YASL_MOD_SHIFT) | (mod_index_active(s, s->mod_alt) * YASL_MOD_ALT) | (mod_index_active(s, s->mod_ctrl) * YASL_MOD_CTRL) | - (mod_index_active(s, s->mod_super) * YASL_MOD_SUPER); + (mod_index_active(s, s->mod_super) * YASL_MOD_SUPER) | + (mod_active(s, XKB_MOD_NAME_CAPS) * YASL_MOD_CAPS); } int wayland_display_modifiers(const struct wayland_display *c) diff --git a/src/wayland/pointer.c b/src/wayland/pointer.c index 065669f..90b7ecc 100644 --- a/src/wayland/pointer.c +++ b/src/wayland/pointer.c @@ -109,12 +109,12 @@ static void report_mouse(struct seat *s, struct wayland_surface *w, struct yasl_ }); } -static void report_wheel(struct seat *s, struct wayland_surface *w, struct yasl_vector2i pos, - int button, int lines, float delta) +static void report_wheel(struct seat *s, struct wayland_surface *w, + struct yasl_vector2i pos, double x, double y) { + if ((x == 0 && y == 0) || !isfinite(x) || !isfinite(y)) return; push_mouse(s, w, (struct yasl_mouse_event){ - .pos = pos, .button = button, .kind = YASL_PTR_SCROLL, - .scroll_lines = lines, .scroll_delta = delta, + .pos = pos, .kind = YASL_PTR_SCROLL, .scroll = {x, y}, }); } @@ -295,12 +295,11 @@ void seat_pointer_reset(struct seat *s) s->pointer_buttons = 0; s->pointer_serial = 0; s->motion_pending = false; - s->axis_v = s->axis_h = s->frame_v = 0; - s->frame_v120 = 0; - s->axis_discrete_v = s->axis_discrete_h = 0; - s->axis_value120_v = s->axis_value120_h = 0; - s->axis_has_v120_v = s->axis_has_v120_h = false; - s->axis_smooth = false; + memset(s->axis, 0, sizeof(s->axis)); + memset(s->axis_value120, 0, sizeof(s->axis_value120)); + memset(s->axis_discrete, 0, sizeof(s->axis_discrete)); + memset(s->axis_has_value120, 0, sizeof(s->axis_has_value120)); + memset(s->axis_has_discrete, 0, sizeof(s->axis_has_discrete)); s->cursor_shape = -1; } @@ -405,8 +404,7 @@ static void pointer_axis(void *data, struct wl_pointer *pointer, if (unlikely(!s->pointer_focus)) return; double v = wl_fixed_to_double(value); if (likely(axis < 2)) { - (&s->axis_v)[axis] += v; - s->frame_v += v * (!axis); + s->axis[axis] += v; } pointer_event_done(s); } @@ -414,81 +412,49 @@ static void pointer_axis(void *data, struct wl_pointer *pointer, static void pointer_axis_source(void *data, struct wl_pointer *pointer, uint32_t axis_source) { (void)pointer; - struct seat *s = data; - s->axis_smooth = (axis_source == WL_POINTER_AXIS_SOURCE_FINGER || - axis_source == WL_POINTER_AXIS_SOURCE_CONTINUOUS); + (void)data; (void)axis_source; } static void pointer_axis_stop(void *data, struct wl_pointer *pointer, uint32_t time, uint32_t axis) { - (void)pointer; (void)time; - struct seat *s = data; - if (likely(axis < 2)) { - (&s->axis_value120_v)[axis] = 0; - (&s->axis_has_v120_v)[axis] = false; - } + /* A stop ends a gesture, not the offsets already received in this frame. */ + (void)data; (void)pointer; (void)time; (void)axis; } static void pointer_axis_discrete(void *data, struct wl_pointer *pointer, uint32_t axis, int32_t discrete) { (void)pointer; struct seat *s = data; - if (likely(axis < 2)) - (&s->axis_discrete_v)[axis] += discrete; + if (axis < 2) { + s->axis_discrete[axis] += discrete; + s->axis_has_discrete[axis] = true; + } } static void pointer_axis_value120(void *data, struct wl_pointer *pointer, uint32_t axis, int32_t value120) { (void)pointer; struct seat *s = data; - if (likely(axis < 2)) { - (&s->axis_value120_v)[axis] += value120; - (&s->axis_has_v120_v)[axis] = true; - s->frame_v120 += value120 * (!axis); + if (axis < 2) { + s->axis_value120[axis] += value120; + s->axis_has_value120[axis] = true; } } -static void pointer_frame_vertical(struct seat *s, struct wayland_surface *w) -{ - if (s->axis_has_v120_v) { - int discrete = s->axis_value120_v / 120; - s->axis_value120_v -= discrete * 120; - float delta = -(float)s->frame_v120 / 120.0f; - int btn = discrete ? (discrete < 0 ? 4 : 5) : (delta > 0 ? 4 : 5); - if (discrete || delta != 0.0f) - report_wheel(s, w, s->pointer_pos, btn, -discrete, delta); - s->axis_v = 0; - } else if (s->axis_discrete_v) { - report_wheel(s, w, s->pointer_pos, s->axis_discrete_v > 0 ? 5 : 4, -s->axis_discrete_v, 0.0f); - s->axis_v = 0; - } else if (s->frame_v != 0.0) { - int lines = -(int)(s->axis_v / SCROLL_PX_PER_LINE); - s->axis_v += (double)lines * SCROLL_PX_PER_LINE; - float delta = (float)(-s->frame_v / SCROLL_PX_PER_LINE); - report_wheel(s, w, s->pointer_pos, delta > 0 ? 4 : 5, lines, delta); - } - s->frame_v = 0; - s->frame_v120 = 0; -} - -static void pointer_frame_horizontal(struct seat *s, struct wayland_surface *w) -{ - if (s->axis_has_v120_h) { - int discrete = s->axis_value120_h / 120; - s->axis_value120_h -= discrete * 120; - if (discrete) - report_wheel(s, w, s->pointer_pos, discrete > 0 ? 7 : 6, discrete, 0.0f); - s->axis_h = 0; - } else if (s->axis_discrete_h) { - report_wheel(s, w, s->pointer_pos, s->axis_discrete_h > 0 ? 7 : 6, s->axis_discrete_h, 0.0f); - s->axis_h = 0; - } else if (s->axis_h) { - int steps = (int)(s->axis_h / SCROLL_PX_PER_LINE); - if (steps != 0) { - s->axis_h -= (double)steps * SCROLL_PX_PER_LINE; - report_wheel(s, w, s->pointer_pos, steps > 0 ? 7 : 6, steps, 0.0f); - } +static void pointer_frame_scroll(struct seat *s, struct wayland_surface *w) +{ + double lines[2]; + for (int axis = 0; axis < 2; axis++) { + /* A wheel may provide all three representations. Pick one, never sum + * them. value120 preserves high-resolution detents on both axes. */ + lines[axis] = s->axis_has_value120[axis] ? s->axis_value120[axis] / 120.0 : + s->axis_has_discrete[axis] ? (double)s->axis_discrete[axis] : + s->axis[axis] / SCROLL_PX_PER_LINE; + s->axis[axis] = s->axis_value120[axis] = 0; + s->axis_discrete[axis] = 0; + s->axis_has_value120[axis] = s->axis_has_discrete[axis] = false; } + report_wheel(s, w, s->pointer_pos, lines[1], lines[0]); } static void pointer_frame(void *data, struct wl_pointer *pointer) @@ -521,18 +487,7 @@ static void pointer_frame(void *data, struct wl_pointer *pointer) flush_pending_motion(s, w); press_queue_flush(s, &s->ptr_presses, NULL, &s->pointer_buttons, (struct yasl_mouse_event){0}); - if (s->axis_smooth) { - if (!s->axis_has_v120_v) s->axis_value120_v = 0; - if (!s->axis_has_v120_h) s->axis_value120_h = 0; - s->axis_smooth = false; - } - pointer_frame_vertical(s, w); - pointer_frame_horizontal(s, w); - - s->axis_discrete_v = 0; - s->axis_discrete_h = 0; - s->axis_has_v120_v = false; - s->axis_has_v120_h = false; + pointer_frame_scroll(s, w); } static void pointer_axis_relative_direction(void *data, struct wl_pointer *pointer, uint32_t axis, uint32_t direction) @@ -651,20 +606,15 @@ static void touch_frame(void *data, struct wl_touch *touch) s->touch_pressed = false; s->touch_scrolling = true; s->touch_scroll_y = centroid_n ? centroid_sum / centroid_n : 0; - s->touch_scroll_rest = 0; } else if (s->touch_scrolling && primary && active_n >= 2) { double y = centroid_n ? centroid_sum / centroid_n : 0; double dy = y - s->touch_scroll_y; s->touch_scroll_y = y; if (dy != 0.0) { double lines = dy / SCROLL_PX_PER_LINE; - s->touch_scroll_rest += lines; - int whole = (int)s->touch_scroll_rest; - s->touch_scroll_rest -= whole; push_mouse(s, primary->surface, (struct yasl_mouse_event){ - .pos = touch_pos(primary), .button = lines > 0 ? 4 : 5, - .kind = YASL_PTR_SCROLL, .scroll_lines = whole, - .scroll_delta = (float)lines, .device = YASL_PTR_DEV_TOUCH, + .pos = touch_pos(primary), .kind = YASL_PTR_SCROLL, + .scroll = {0, -lines}, .device = YASL_PTR_DEV_TOUCH, }); } } else if (primary && primary->moved && s->touch_pressed) { @@ -870,7 +820,7 @@ static void tool_frame(void *d, struct zwp_tablet_tool_v2 *t, uint32_t time) struct yasl_mouse_event ev = like; ev.pos = s->tool_pos; ev.kind = YASL_PTR_SCROLL; - ev.scroll_lines = -s->tool_wheel; + ev.scroll.y = s->tool_wheel; push_mouse(s, w, ev); s->tool_wheel = 0; } @@ -1105,6 +1055,7 @@ static void seat_drop_pointer(struct seat *s) static void seat_drop_keyboard(struct seat *s) { keyboard_repeat_stop(s); + keyboard_text_reset(s); if (s->keyboard) { if (wl_keyboard_get_version(s->keyboard) >= WL_KEYBOARD_RELEASE_SINCE_VERSION) wl_keyboard_release(s->keyboard); @@ -1281,6 +1232,7 @@ void seat_destroy(struct seat *s) if (s->cursor_viewport) wp_viewport_destroy(s->cursor_viewport); if (s->cursor_surface) wl_surface_destroy(s->cursor_surface); if (s->xkb_state) xkb_state_unref(s->xkb_state); + if (s->compose) xkb_compose_state_unref(s->compose); if (s->xkb_keymap) xkb_keymap_unref(s->xkb_keymap); if (s->proxy) { if (wl_seat_get_version(s->proxy) >= WL_SEAT_RELEASE_SINCE_VERSION) diff --git a/src/x11/window.c b/src/x11/window.c index 1a0db7d..f7d036f 100644 --- a/src/x11/window.c +++ b/src/x11/window.c @@ -2,6 +2,8 @@ #define _DEFAULT_SOURCE #include "common/backend.h" #include "common/input.h" +#include "common/keyboard.h" +#include "common/utf8.h" #include "common/timing.h" #include <X11/Xatom.h> @@ -103,6 +105,8 @@ struct x11_display { bool xi2; bool has_shm; bool has_xkb; + int xkb_event; + enum yasl_key keys[256]; Cursor cursors[16]; Atom abs_pressure, abs_tilt_x, abs_tilt_y, tool_type, eraser; struct x11_pointer *pointers; @@ -379,7 +383,8 @@ static void xi_pointer_event(struct x11_surface *s, const XIDeviceEvent *ev) else if (ev->detail >= 4 && ev->detail <= 7) { if (ev->evtype == XI_ButtonRelease) return; mouse.kind = YASL_PTR_SCROLL; - mouse.scroll_lines = (ev->detail == 4 || ev->detail == 6) ? -1 : 1; + if (ev->detail <= 5) mouse.scroll.y = ev->detail == 4 ? -1 : 1; + else mouse.scroll.x = ev->detail == 6 ? -1 : 1; } else { mouse.kind = ev->evtype == XI_ButtonPress ? YASL_PTR_PRESS : YASL_PTR_RELEASE; mouse.button = pointer_button(ev->detail); @@ -915,20 +920,24 @@ static void selection_request(struct x11_display *d, XSelectionRequestEvent *req Atom property = request->property ? request->property : request->target; int slot = request->selection == XA_PRIMARY ? YASL_PRIMARY : YASL_CLIPBOARD; const char *text = d->selection[slot]; + size_t latin1_len = 0; + char *latin1 = text ? yasl_utf8_to_latin1(text, &latin1_len) : NULL; if (text && request->target == d->targets) { Atom targets[] = {d->targets, d->utf8, XA_STRING}; XChangeProperty(d->native, request->requestor, property, XA_ATOM, 32, - PropModeReplace, (unsigned char *)targets, 3); + PropModeReplace, (unsigned char *)targets, latin1 ? 3 : 2); reply.xselection.property = property; } else if (text && (request->target == d->utf8 || request->target == XA_STRING)) { - size_t len = strlen(text); + const char *payload = request->target == XA_STRING ? latin1 : text; + size_t len = request->target == XA_STRING ? latin1_len : strlen(text); long max = XMaxRequestSize(d->native) * 4 - 128; - if (len <= (size_t)max) { + if (payload && len <= (size_t)max) { XChangeProperty(d->native, request->requestor, property, request->target, - 8, PropModeReplace, (const unsigned char *)text, (int)len); + 8, PropModeReplace, (const unsigned char *)payload, (int)len); reply.xselection.property = property; } } + free(latin1); XSendEvent(d->native, request->requestor, False, 0, &reply); } @@ -1038,6 +1047,7 @@ static void selection_notify(struct x11_display *d, XSelectionEvent *event) char *buf = NULL; size_t total = 0; unsigned long offset = 0; + bool complete = false; /* Read up to TEXT_LIMIT bytes in 64KB chunks to avoid huge single-request limits */ while (total < TEXT_LIMIT) { @@ -1053,7 +1063,7 @@ static void selection_notify(struct x11_display *d, XSelectionEvent *event) if (data) { XFree(data); data = NULL; } break; } - if ((actual != d->utf8 && actual != XA_STRING) || format != 8 || count == 0) { + if ((actual != d->utf8 && actual != XA_STRING) || format != 8) { if (data) { XFree(data); data = NULL; } break; } @@ -1063,22 +1073,41 @@ static void selection_notify(struct x11_display *d, XSelectionEvent *event) break; } buf = nb; - memcpy(buf + total, data, count); + if (count) memcpy(buf + total, data, count); total += count; buf[total] = '\0'; offset += count / 4; XFree(data); data = NULL; - if (left == 0) break; + if (left == 0) { complete = true; break; } } - if (buf && total > 0) { - push(s, (struct yasl_input_event){.kind = YASL_INPUT_PASTE}, buf, total); + if (complete && actual == XA_STRING) { + size_t utf8_len; + char *utf8 = yasl_utf8_from_latin1(buf, total, &utf8_len); free(buf); - } else free(buf); + buf = utf8; + if (buf) total = utf8_len; + } + if (complete && buf && yasl_utf8_validate(buf, total)) + push(s, (struct yasl_input_event){.kind = YASL_INPUT_PASTE}, buf, total); + free(buf); XDestroyWindow(d->native, r->window); free(r); } +static void refresh_keyboard(struct x11_display *d) +{ + memset(d->keys, 0, sizeof(d->keys)); + if (!d->has_xkb) return; + XkbDescPtr keyboard = XkbGetKeyboard(d->native, XkbAllComponentsMask, XkbUseCoreKbd); + if (!keyboard) return; + if (keyboard->names && keyboard->names->keys) { + for (unsigned code = keyboard->min_key_code; code <= keyboard->max_key_code; code++) + d->keys[code] = yasl_key_from_xkb_name(keyboard->names->keys[code].name); + } + XkbFreeKeyboard(keyboard, XkbAllComponentsMask, True); +} + static void key_event(struct x11_surface *s, XKeyEvent *key, bool repeat) { struct x11_display *d = display_of(&s->base); @@ -1086,10 +1115,11 @@ static void key_event(struct x11_surface *s, XKeyEvent *key, bool repeat) unsigned clean_state = key->state & ~(Mod2Mask | LockMask); KeySym sym = NoSymbol, base = NoSymbol, shifted = NoSymbol; + int group = XkbGroupForCoreState(key->state); if (d->has_xkb) { - sym = XkbKeycodeToKeysym(d->native, key->keycode, 0, (clean_state & ShiftMask) ? 1 : 0); - base = XkbKeycodeToKeysym(d->native, key->keycode, 0, 0); - shifted = XkbKeycodeToKeysym(d->native, key->keycode, 0, 1); + sym = XkbKeycodeToKeysym(d->native, key->keycode, group, (clean_state & ShiftMask) ? 1 : 0); + base = XkbKeycodeToKeysym(d->native, key->keycode, group, 0); + shifted = XkbKeycodeToKeysym(d->native, key->keycode, group, 1); } if (sym == NoSymbol) { XKeyEvent clean_key = *key; @@ -1111,21 +1141,26 @@ static void key_event(struct x11_surface *s, XKeyEvent *key, bool repeat) else len = 0; } if (status != XLookupChars && status != XLookupBoth) len = 0; - } else len = XLookupString(key, local, sizeof(local), &sym, NULL); + } else { + /* XLookupString's bytes are Latin-1. Use its modifier-aware keysym + * and encode UTF-8 even when no input method is available. */ + XLookupString(key, local, sizeof(local), &sym, NULL); + len = xkb_keysym_to_utf8((xkb_keysym_t)sym, local, sizeof(local)); + len = len > 0 ? len - 1 : 0; /* xkb includes the terminating NUL. */ + } } uint32_t cp = xkb_keysym_to_utf32((xkb_keysym_t)base); - if (!cp) cp = xkb_keysym_to_utf32((xkb_keysym_t)sym); push(s, (struct yasl_input_event){ .kind = YASL_INPUT_KEY, - .key = {.key = (uint32_t)sym, .codepoint = cp, - .base = key->keycode >= 8 ? key->keycode - 8 : 0, - .keypad = sym >= XK_KP_Space && sym <= XK_KP_Equal, - .shifted = xkb_keysym_to_utf32((xkb_keysym_t)shifted), - .text = xkb_keysym_to_utf32((xkb_keysym_t)sym), .mods = d->mods, + .key = {.key = key->keycode < 256 ? d->keys[key->keycode] : YASL_KEY_UNKNOWN, + .codepoint = yasl_key_label(cp), .native_code = key->keycode, + .shifted = yasl_key_label(xkb_keysym_to_utf32((xkb_keysym_t)shifted)), + .mods = d->mods, .action = key->type == KeyRelease ? YASL_KEY_RELEASE : repeat ? YASL_KEY_REPEAT : YASL_KEY_PRESS}, }, NULL, 0); - if (len > 0 && text) + if (len > 0 && text && (unsigned char)text[0] >= 0x20 && text[0] != 0x7f && + !(d->mods & (YASL_MOD_CTRL | YASL_MOD_SUPER | YASL_MOD_ALT))) push(s, (struct yasl_input_event){.kind = YASL_INPUT_TEXT}, text, (size_t)len); if (text != local) free(text); } @@ -1256,6 +1291,17 @@ static void dispatch(struct yasl_display *base) XFreeEventData(d->native, &event.xcookie); continue; } + if (event.type == MappingNotify) { + XRefreshKeyboardMapping(&event.xmapping); + refresh_keyboard(d); + continue; + } + if (d->has_xkb && event.type == d->xkb_event) { + XkbEvent *xkb = (XkbEvent *)&event; + if (xkb->any.xkb_type == XkbMapNotify) XkbRefreshKeyboardMapping(&xkb->map); + refresh_keyboard(d); + continue; + } if (XFilterEvent(&event, None)) continue; if (event.type == SelectionRequest) { selection_request(d, &event.xselectionrequest); @@ -1353,7 +1399,8 @@ static void dispatch(struct yasl_display *base) if (button >= 4 && button <= 7) { if (event.type == ButtonRelease) break; mouse.kind = YASL_PTR_SCROLL; - mouse.scroll_lines = (button == 4 || button == 6) ? -1 : 1; + if (button <= 5) mouse.scroll.y = button == 4 ? -1 : 1; + else mouse.scroll.x = button == 6 ? -1 : 1; } else { mouse.kind = event.type == ButtonPress ? YASL_PTR_PRESS : YASL_PTR_RELEASE; mouse.button = pointer_button(button); @@ -1519,8 +1566,15 @@ static struct yasl_display *display_open(struct yasl_loop *loop, d->base.native_handle = d->native; d->screen = DefaultScreen(d->native); d->has_shm = XShmQueryExtension(d->native); - int xkb_opcode, xkb_event, xkb_error, xkb_major = XkbMajorVersion, xkb_minor = XkbMinorVersion; + int xkb_opcode = 0, xkb_event = 0, xkb_error = 0; + int xkb_major = XkbMajorVersion, xkb_minor = XkbMinorVersion; d->has_xkb = XkbQueryExtension(d->native, &xkb_opcode, &xkb_event, &xkb_error, &xkb_major, &xkb_minor); + d->xkb_event = xkb_event; + if (d->has_xkb) { + unsigned events = XkbNewKeyboardNotifyMask | XkbMapNotifyMask | XkbNamesNotifyMask; + XkbSelectEvents(d->native, XkbUseCoreKbd, events, events); + refresh_keyboard(d); + } int xi_event_base, xi_error_base; int major = 2, minor = 0; d->xi2 = XQueryExtension(d->native, "XInputExtension", &d->xi_opcode, diff --git a/tests/cocoa/test_cursor.m b/tests/cocoa/test_cursor.m index 0f3ba06..7a328f2 100644 --- a/tests/cocoa/test_cursor.m +++ b/tests/cocoa/test_cursor.m @@ -22,8 +22,12 @@ int main(void) assert(surface); NSWindow *window = (NSWindow *)yasl_surface_get_native_handle(surface); NSView *view = window.contentView; + NSEvent *cursor = [NSEvent enterExitEventWithType:NSEventTypeCursorUpdate + location:NSMakePoint(100, 120) modifierFlags:0 timestamp:0 + windowNumber:window.windowNumber context:nil eventNumber:0 trackingNumber:0 userData:NULL]; + assert(cursor); yasl_surface_set_cursor(surface, YASL_CURSOR_HIDDEN); - [view cursorUpdate:nil]; + [view cursorUpdate:cursor]; NSCursor *hidden = [NSCursor currentCursor]; assert_transparent(hidden); @@ -31,7 +35,7 @@ int main(void) location:NSMakePoint(100, 120) modifierFlags:0 timestamp:0 windowNumber:window.windowNumber context:nil eventNumber:0 clickCount:0 pressure:0]; [view mouseMoved:motion]; - [view cursorUpdate:nil]; + [view cursorUpdate:cursor]; assert([NSCursor currentCursor] == hidden); struct yasl_input_event event; bool moved = false; @@ -41,10 +45,10 @@ int main(void) assert(moved); [[NSCursor arrowCursor] set]; /* Simulate leaving and re-entering. */ - [view cursorUpdate:nil]; + [view cursorUpdate:cursor]; assert([NSCursor currentCursor] == hidden); yasl_surface_set_cursor(surface, YASL_CURSOR_ARROW); - [view cursorUpdate:nil]; + [view cursorUpdate:cursor]; assert([NSCursor currentCursor] == [NSCursor arrowCursor]); yasl_surface_destroy(surface); yasl_display_close(display); diff --git a/tests/cocoa/test_keyboard.m b/tests/cocoa/test_keyboard.m new file mode 100644 index 0000000..4854065 --- /dev/null +++ b/tests/cocoa/test_keyboard.m @@ -0,0 +1,134 @@ +#import <AppKit/AppKit.h> +#include <yasl/native.h> +#include <assert.h> +#include <math.h> +#include <string.h> + +/* Reject character queries on modifier-only events, as AppKit does. */ +@interface InputSample : NSObject +@property NSEventType type; +@property unsigned short keyCode; +@property NSEventModifierFlags modifierFlags; +@property(copy) NSString *label; +@property(copy) NSString *shiftedLabel; +@property NSPoint locationInWindow; +@property CGFloat scrollingDeltaX; +@property CGFloat scrollingDeltaY; +@property BOOL hasPreciseScrollingDeltas; +@end + +@implementation InputSample +- (NSString *)charactersByApplyingModifiers:(NSEventModifierFlags)modifiers +{ + assert(self.type == NSEventTypeKeyDown || self.type == NSEventTypeKeyUp); + return modifiers & NSEventModifierFlagShift ? self.shiftedLabel : self.label; +} +- (void)dealloc +{ + [_label release]; + [_shiftedLabel release]; + [super dealloc]; +} +@end + +static struct yasl_input_event next(struct yasl_surface *surface, enum yasl_input_kind kind) +{ + struct yasl_input_event event; + assert(yasl_surface_input_poll(surface, &event)); + assert(event.kind == kind && event.surface == surface); + return event; +} + +static void empty(struct yasl_surface *surface) +{ + struct yasl_input_event event; + assert(!yasl_surface_input_poll(surface, &event)); +} + +int main(void) +{ + @autoreleasepool { + struct yasl_display *display = yasl_display_open(NULL, NULL); + assert(display); + struct yasl_surface_spec spec = {.title = "Keyboard test", .size = {320, 240}}; + struct yasl_surface *surface = yasl_surface_create_toplevel(display, &spec); + assert(surface); + NSWindow *window = (NSWindow *)yasl_surface_get_native_handle(surface); + NSView<NSTextInputClient> *view = (id)window.contentView; + struct yasl_input_event event; + while (yasl_surface_input_poll(surface, &event)) {} + + InputSample *sample = [InputSample new]; + NSEvent *native = (NSEvent *)sample; + sample.type = NSEventTypeKeyUp; + sample.keyCode = 0; /* US A, even with a different active layout. */ + sample.label = @"q"; + sample.shiftedLabel = @"Q"; + [view keyUp:native]; + event = next(surface, YASL_INPUT_KEY); + assert(event.key.key == YASL_KEY_A && event.key.native_code == 0); + assert(event.key.action == YASL_KEY_RELEASE); + assert(event.key.codepoint == 'q' && event.key.shifted == 'Q'); + empty(surface); + sample.label = @"😀"; /* One scalar, two UTF-16 units. */ + sample.shiftedLabel = @"ab"; + [view keyUp:native]; + event = next(surface, YASL_INPUT_KEY); + assert(event.key.codepoint == 0x1f600 && event.key.shifted == 0); + sample.type = NSEventTypeFlagsChanged; + sample.keyCode = 56; /* Left Shift. */ + sample.modifierFlags = NSEventModifierFlagShift | 0x0002; + [view flagsChanged:native]; + event = next(surface, YASL_INPUT_KEY); + assert(event.key.key == YASL_KEY_LEFT_SHIFT && event.key.action == YASL_KEY_PRESS); + assert(event.key.mods == YASL_MOD_SHIFT && !event.key.codepoint && !event.key.shifted); + sample.modifierFlags = 0; + [view flagsChanged:native]; + assert(next(surface, YASL_INPUT_KEY).key.action == YASL_KEY_RELEASE); + + /* Native text services own preedit and commits. Marked text is not an + * insertion, and commits retain all UTF-8 bytes, including non-BMP. */ + [view setMarkedText:@"é" selectedRange:NSMakeRange(1, 0) + replacementRange:NSMakeRange(NSNotFound, 0)]; + assert(strcmp(yasl_surface_ime_preedit(surface), "é") == 0); + empty(surface); + [view insertText:@"😀é" replacementRange:NSMakeRange(NSNotFound, 0)]; + event = next(surface, YASL_INPUT_TEXT); + assert(event.text.len == strlen("😀é") && strcmp(event.text.text, "😀é") == 0); + assert(!yasl_surface_ime_preedit(surface)); + empty(surface); + + /* Exercise the keyDown -> interpretKeyEvents -> insertText route with + * an actual AppKit key event rather than the strict event double. */ + NSEvent *press = [NSEvent keyEventWithType:NSEventTypeKeyDown location:NSZeroPoint + modifierFlags:0 timestamp:0 windowNumber:window.windowNumber context:nil + characters:@"a" charactersIgnoringModifiers:@"a" isARepeat:NO keyCode:0]; + [view keyDown:press]; + assert(next(surface, YASL_INPUT_KEY).key.key == YASL_KEY_A); + event = next(surface, YASL_INPUT_TEXT); + assert(event.text.len == 1 && event.text.text[0] == 'a'); + empty(surface); + + sample.type = NSEventTypeScrollWheel; + sample.hasPreciseScrollingDeltas = YES; + sample.scrollingDeltaX = -2.5; + sample.scrollingDeltaY = 1.25; + [view scrollWheel:native]; + event = next(surface, YASL_INPUT_MOUSE); + assert(event.mouse.kind == YASL_PTR_SCROLL); + assert(event.mouse.scroll.x == 0.25 && event.mouse.scroll.y == -0.125); + sample.hasPreciseScrollingDeltas = NO; + sample.scrollingDeltaX = 1; + sample.scrollingDeltaY = -1; + [view scrollWheel:native]; + event = next(surface, YASL_INPUT_MOUSE); + assert(event.mouse.scroll.x == -1 && event.mouse.scroll.y == 1); + sample.scrollingDeltaX = NAN; + [view scrollWheel:native]; + empty(surface); + [sample release]; + yasl_surface_destroy(surface); + yasl_display_close(display); + } + return 0; +} diff --git a/tests/common/test_backends.c b/tests/common/test_backends.c index 4c99646..cf5b1f9 100644 --- a/tests/common/test_backends.c +++ b/tests/common/test_backends.c @@ -194,23 +194,105 @@ static void x11_behavior(struct yasl_loop *loop, struct yasl_display *d, struct yasl_display_copy(d, YASL_CLIPBOARD, "clipboard text"); yasl_display_paste(d, YASL_CLIPBOARD, w->surface); pump(loop, d, NULL); - bool saw_key = false, saw_paste = false; + bool saw_key = false, saw_paste = false, saw_text = false; struct yasl_input_event event; while (yasl_surface_input_poll(w->surface, &event)) { assert(event.surface == w->surface); if (event.kind == YASL_INPUT_KEY) { assert(event.key.codepoint == 'a'); assert(event.key.shifted == 'A'); - assert(event.key.base == 30); - saw_key = event.key.key == XK_a; + assert(event.key.native_code == key.xkey.keycode); + saw_key = event.key.key == YASL_KEY_A; } if (event.kind == YASL_INPUT_PASTE) { assert(event.paste.len == strlen("clipboard text")); assert(memcmp(event.paste.text, "clipboard text", event.paste.len) == 0); saw_paste = true; } + if (event.kind == YASL_INPUT_TEXT) { + assert(event.text.len == 1 && event.text.text[0] == 'a'); + saw_text = true; + } + } + assert(saw_key && saw_paste && saw_text); + /* Physical identity survives modifier and layout changes, including a + * release whose modifiers differ from its press. */ + key.xkey.state = ShiftMask; + XSendEvent(native, window, False, KeyPressMask, &key); + key.xkey.type = KeyRelease; + key.xkey.state = 0; + XSendEvent(native, window, False, KeyReleaseMask, &key); + XFlush(native); + pump(loop, d, NULL); + int key_count = 0, text_count = 0; + while (yasl_surface_input_poll(w->surface, &event)) { + if (event.kind == YASL_INPUT_KEY) { + assert(event.key.key == YASL_KEY_A); + assert(event.key.action == (key_count ? YASL_KEY_RELEASE : YASL_KEY_PRESS)); + key_count++; + } else if (event.kind == YASL_INPUT_TEXT) { + assert(event.text.len == 1 && event.text.text[0] == 'A'); + text_count++; + } + } + assert(key_count == 2 && text_count == 1); + key.xkey.type = KeyPress; + key.xkey.state = ControlMask; + XSendEvent(native, window, False, KeyPressMask, &key); + XFlush(native); + pump(loop, d, NULL); + assert(yasl_surface_input_poll(w->surface, &event)); + assert(event.kind == YASL_INPUT_KEY && event.key.key == YASL_KEY_A); + assert(event.key.mods & YASL_MOD_CTRL); + assert(!yasl_surface_input_poll(w->surface, &event)); + + int symbols_per_key = 0; + KeySym *saved_symbols = XGetKeyboardMapping(native, key.xkey.keycode, 1, &symbols_per_key); + assert(saved_symbols && symbols_per_key >= 2); + KeySym *changed_symbols = calloc((size_t)symbols_per_key, sizeof(KeySym)); + assert(changed_symbols); + changed_symbols[0] = XK_q; + changed_symbols[1] = XK_Q; + XChangeKeyboardMapping(native, key.xkey.keycode, symbols_per_key, changed_symbols, 1); + XSync(native, False); + pump(loop, d, NULL); /* Consume MappingNotify before translating the key. */ + key.xkey.state = 0; + XSendEvent(native, window, False, KeyPressMask, &key); + XFlush(native); + pump(loop, d, NULL); + saw_key = saw_text = false; + while (yasl_surface_input_poll(w->surface, &event)) { + if (event.kind == YASL_INPUT_KEY) { + assert(event.key.key == YASL_KEY_A && event.key.codepoint == 'q'); + saw_key = true; + } else if (event.kind == YASL_INPUT_TEXT) { + assert(event.text.len == 1 && event.text.text[0] == 'q'); + saw_text = true; + } + } + assert(saw_key && saw_text); + XChangeKeyboardMapping(native, key.xkey.keycode, symbols_per_key, saved_symbols, 1); + free(changed_symbols); + XFree(saved_symbols); + XSync(native, False); + pump(loop, d, NULL); + + for (unsigned button = 4; button <= 7; button++) { + XEvent wheel = {.xbutton = {.type = ButtonPress, .display = native, + .window = window, .root = DefaultRootWindow(native), + .same_screen = True, .button = button}}; + /* Direct delivery exercises the core fallback even with XI2 enabled. */ + XSendEvent(native, window, False, NoEventMask, &wheel); + wheel.xbutton.type = ButtonRelease; + XSendEvent(native, window, False, NoEventMask, &wheel); + XFlush(native); + pump(loop, d, NULL); + assert(yasl_surface_input_poll(w->surface, &event)); + assert(event.kind == YASL_INPUT_MOUSE && event.mouse.kind == YASL_PTR_SCROLL); + assert(event.mouse.scroll.x == (button == 6 ? -1 : button == 7 ? 1 : 0)); + assert(event.mouse.scroll.y == (button == 4 ? -1 : button == 5 ? 1 : 0)); + assert(!yasl_surface_input_poll(w->surface, &event)); } - assert(saw_key && saw_paste); assert(yasl_surface_timing(w->surface).source == YASL_TIMING_SUBMISSION); assert(!(yasl_display_caps(d) & YASL_CAP_FRAME_PACING)); diff --git a/tests/common/test_contracts.c b/tests/common/test_contracts.c index 4e22de1..8580dd6 100644 --- a/tests/common/test_contracts.c +++ b/tests/common/test_contracts.c @@ -232,6 +232,97 @@ static void test_scale(void) assert(yasl_scale_to_logical(1, 0) == 0); } +static int popup_calls; +static struct yasl_surface *popup_create(struct yasl_surface *parent, + const struct yasl_popup_spec *spec) +{ + (void)parent; (void)spec; + popup_calls++; + return NULL; /* Backend fails without setting errno. */ +} + +static bool popup_reposition(struct yasl_surface *popup, + const struct yasl_popup_spec *spec) +{ + (void)popup; (void)spec; + popup_calls++; + errno = EBUSY; + return false; +} + +static uint32_t popup_caps(const struct yasl_display *d) +{ (void)d; return YASL_CAP_POPUPS; } + +static int dispatch_failure(struct yasl_display *d, int timeout) +{ (void)d; (void)timeout; return -1; } + +static struct yasl_surface *create_failure(struct yasl_display *d, + const struct yasl_surface_spec *spec, void *device) +{ (void)d; (void)spec; (void)device; return NULL; } + +static int drag_starts; +static bool drag_without_listener(struct yasl_display *d, struct yasl_surface *s, + const struct yasl_drag_image *image, const struct yasl_drag_listener *listener, + void *ud) +{ + (void)d; (void)s; (void)image; (void)ud; + /* Backends may require a table even when no completion callback is needed. */ + assert(listener && !listener->end); + drag_starts++; + return true; +} + +static void test_errors(void) +{ + const struct yasl_backend_ops ops = {.display_caps = popup_caps, + .surface_create_toplevel = create_failure, + .surface_create_popup = popup_create, + .surface_popup_reposition = popup_reposition, + .display_drag_start = drag_without_listener, + .display_dispatch_timeout = dispatch_failure}; + struct yasl_display d = {.ops = &ops}; + struct yasl_surface s = {.display = &d}; + struct yasl_popup_spec spec = {.size = {120, 80}, .anchor = {0, 0, 1, 1}}; + assert(!yasl_surface_create_popup(NULL, &spec) && errno == EINVAL); + assert(!yasl_surface_create_popup(&s, NULL) && errno == EINVAL); + spec.anchor.width = -1; /* Must not reach Wayland's protocol marshaler. */ + assert(!yasl_surface_create_popup(&s, &spec) && errno == EINVAL); + assert(!yasl_surface_popup_reposition(&s, &spec) && errno == EINVAL); + spec.anchor.width = 1; + spec.content_offset.x = INT_MAX; + spec.content_size.x = INT_MAX; + assert(!yasl_surface_create_popup(&s, &spec) && errno == EINVAL); + spec.content_offset.x = spec.content_size.x = 0; + spec.size.x = 32768; + assert(!yasl_surface_create_popup(&s, &spec) && errno == EINVAL); + assert(!popup_calls); + spec.size.x = 120; + errno = ERANGE; + assert(!yasl_surface_create_popup(&s, &spec) && errno == ENODEV); + assert(!yasl_surface_popup_reposition(&s, &spec) && errno == EBUSY); + assert(popup_calls == 2); + const struct yasl_backend_ops unsupported = {0}; + d.ops = &unsupported; + assert(!yasl_surface_create_popup(&s, &spec) && errno == ENOTSUP); + assert(!yasl_surface_popup_reposition(&s, &spec) && errno == ENOTSUP); + assert(yasl_display_dispatch(&d, 0) == -1 && errno == ENOTSUP); + assert(yasl_display_dispatch(NULL, 0) == -1 && errno == EINVAL); + d.ops = &ops; + errno = ERANGE; + assert(yasl_display_dispatch(&d, 0) == -1 && errno == EIO); + struct yasl_surface_spec toplevel = {.size = {120, 80}}; + errno = ERANGE; + assert(!yasl_surface_create_toplevel(&d, &toplevel) && errno == ENODEV); + assert(yasl_display_drag_start(&d, &s, NULL, NULL, NULL)); + struct yasl_drag_image image = {.size = {1, 1}}; + assert(!yasl_display_drag_start(&d, &s, &image, NULL, NULL)); + uint32_t pixel = 0; + image.pixels = &pixel; + image.size.x = INT_MAX; + assert(!yasl_display_drag_start(&d, &s, &image, NULL, NULL)); + assert(drag_starts == 1); +} + int main(void) { test_timing_clock(); @@ -239,5 +330,6 @@ int main(void) test_validation(); test_native(); test_scale(); + test_errors(); return 0; } diff --git a/tests/common/test_keyboard.c b/tests/common/test_keyboard.c new file mode 100644 index 0000000..5a7f18e --- /dev/null +++ b/tests/common/test_keyboard.c @@ -0,0 +1,32 @@ +#include "common/keyboard.h" +#include "cocoa/keycodes.h" +#include <assert.h> + +int main(void) +{ + /* Same physical positions across native encodings, including keypad and + * left/right modifiers. macOS A is code zero, which is not UNKNOWN. */ + assert(yasl_key_from_evdev(30) == YASL_KEY_A); + assert(yasl_key_from_cocoa(kVK_ANSI_A) == YASL_KEY_A); + assert(yasl_key_from_xkb_name("AC01") == YASL_KEY_A); + assert(yasl_key_from_evdev(1) == YASL_KEY_ESCAPE); + assert(yasl_key_from_cocoa(kVK_Escape) == YASL_KEY_ESCAPE); + assert(yasl_key_from_xkb_name("ESC\0") == YASL_KEY_ESCAPE); + assert(yasl_key_from_evdev(96) == YASL_KEY_KP_ENTER); + assert(yasl_key_from_cocoa(kVK_ANSI_KeypadEnter) == YASL_KEY_KP_ENTER); + assert(yasl_key_from_cocoa(kVK_Return) == YASL_KEY_ENTER); + assert(yasl_key_from_evdev(100) == YASL_KEY_RIGHT_ALT); + assert(yasl_key_from_cocoa(kVK_RightOption) == YASL_KEY_RIGHT_ALT); + assert(yasl_key_from_evdev(42) == YASL_KEY_LEFT_SHIFT); + assert(yasl_key_from_cocoa(kVK_Shift) == YASL_KEY_LEFT_SHIFT); + assert(yasl_key_from_evdev(86) == YASL_KEY_ISO_BACKSLASH); + assert(yasl_key_from_cocoa(kVK_ISO_Section) == YASL_KEY_ISO_BACKSLASH); + assert(yasl_key_from_evdev(0) == YASL_KEY_UNKNOWN); + assert(yasl_key_from_evdev(UINT32_MAX) == YASL_KEY_UNKNOWN); + assert(yasl_key_from_cocoa(UINT32_MAX) == YASL_KEY_UNKNOWN); + assert(yasl_key_from_xkb_name("ZZZZ") == YASL_KEY_UNKNOWN); + assert(yasl_key_label(0x1f600) == 0x1f600); + assert(yasl_key_label(0xd800) == 0 && yasl_key_label(0x110000) == 0); + assert(yasl_key_label(0xf700) == 0 && yasl_key_label('\t') == 0); + return 0; +} diff --git a/tests/common/test_utf8.c b/tests/common/test_utf8.c new file mode 100644 index 0000000..72f8904 --- /dev/null +++ b/tests/common/test_utf8.c @@ -0,0 +1,27 @@ +#include "common/utf8.h" +#include <assert.h> +#include <stdlib.h> +#include <string.h> + +int main(void) +{ + char latin1[256]; + for (int i = 1; i <= 255; i++) latin1[i - 1] = (char)i; + latin1[255] = '\0'; + size_t len = 0, back_len = 0; + char *utf8 = yasl_utf8_from_latin1(latin1, 255, &len); + assert(utf8 && yasl_utf8_validate(utf8, len)); + char *back = yasl_utf8_to_latin1(utf8, &back_len); + assert(back && back_len == 255 && memcmp(back, latin1, 256) == 0); + free(back); + free(utf8); + assert(!yasl_utf8_to_latin1("😀", &len)); + assert(!yasl_utf8_to_latin1("\xc3", &len)); + assert(!yasl_utf8_validate("\xc3", 1)); + assert(!yasl_utf8_validate("\xe2\x82", 2)); + assert(!yasl_utf8_validate("\xf0\x9f\x98", 3)); + assert(!yasl_utf8_validate("\xed\xa0\x80", 3)); /* Surrogate. */ + assert(yasl_utf8_validate("😀", sizeof("😀") - 1)); + assert(yasl_utf8_validate(NULL, 0)); + return 0; +} diff --git a/tests/helpers/check_exports.py b/tests/helpers/check_exports.py index 0d10014..acb727d 100644 --- a/tests/helpers/check_exports.py +++ b/tests/helpers/check_exports.py @@ -9,6 +9,7 @@ import subprocess def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--allow-export', action='append', default=[]) + parser.add_argument('--platform', choices=['linux', 'darwin'], default='linux') parser.add_argument('nm') parser.add_argument('library') parser.add_argument('headers', nargs='+') @@ -23,10 +24,14 @@ def main(): if not expected: raise SystemExit("No public function declarations found") - output = subprocess.check_output( - [args.nm, "-D", "--defined-only", "--format=posix", args.library], text=True - ) + nm_options = ["-g", "-U", "-P"] if args.platform == 'darwin' else [ + "-D", "--defined-only", "--format=posix" + ] + output = subprocess.check_output([args.nm, *nm_options, args.library], text=True) exported = {line.split()[0] for line in output.splitlines() if line.strip()} + if args.platform == 'darwin': + # Mach-O decorates C symbols with one leading underscore. + exported = {name[1:] if name.startswith('_') else name for name in exported} missing = expected - exported leaked = exported - expected - set(args.allow_export) if missing or leaked: diff --git a/tests/helpers/package_cocoa_tests.py b/tests/helpers/package_cocoa_tests.py new file mode 100644 index 0000000..8f801f8 --- /dev/null +++ b/tests/helpers/package_cocoa_tests.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python3 +"""Package compiled Cocoa tests for execution on a matching macOS desktop.""" + +import argparse +import hashlib +import json +from pathlib import Path +import shutil +import tarfile +import tempfile + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('build', type=Path) + parser.add_argument('output', type=Path) + args = parser.parse_args() + build = args.build.resolve() + info = build / 'meson-info' + host = json.loads((info / 'intro-machines.json').read_text())['host'] + if host['system'] != 'darwin': + parser.error('Use a configured and compiled Cocoa build.') + tests = json.loads((info / 'intro-tests.json').read_text()) + required = {'native', 'native-ownership', 'keyboard-cocoa', 'tablet-cocoa', + 'cursor-cocoa', 'hello-cocoa-window', 'tablet-cocoa-window'} + missing = required - {test['name'] for test in tests} + if missing: + parser.error('Enable integration_tests; missing: ' + ', '.join(sorted(missing))) + options = json.loads((info / 'intro-buildoptions.json').read_text()) + sanitizer = next(option['value'] for option in options if option['name'] == 'b_sanitize') + if sanitizer not in ('none', [], ['none']): + parser.error('Use an unsanitized build; sanitizer runtimes are not bundled.') + + with tempfile.TemporaryDirectory(prefix='yasl-cocoa-bundle-') as directory: + root = Path(directory) / 'yasl-cocoa-tests' + root.mkdir() + files = {} + + def copy(source, relative): + destination = root / relative + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(source, destination) + files[str(relative)] = hashlib.sha256(destination.read_bytes()).hexdigest() + + copy(build / 'libyasl.dylib', Path('libyasl.dylib')) + source_root = Path(__file__).resolve().parents[2] + copy(source_root / 'LICENSE', Path('LICENSE')) + copy(Path(__file__).with_name('run_cocoa_bundle.py'), Path('run.py')) + commands = [] + for test in tests: + if test['name'] == 'public-exports': + continue # Check the dylib with nm on the build machine first. + executable = Path(test['cmd'][0]).resolve() + try: + relative = executable.relative_to(build) + except ValueError: + parser.error('Unexpected external test command: ' + str(executable)) + copy(executable, relative) + commands.append({'name': test['name'], 'cmd': [str(relative), *test['cmd'][1:]], + 'timeout': test['timeout']}) + manifest = {'architecture': host['cpu_family'], 'minimum_macos': 14, + 'tests': commands, 'sha256': files} + (root / 'manifest.json').write_text(json.dumps(manifest, indent=2) + '\n') + with tarfile.open(args.output, 'w:gz') as archive: + archive.add(root, arcname=root.name) + print(f'Packaged {len(commands)} runtime tests for {host["cpu_family"]}: {args.output}') + + +if __name__ == '__main__': + main() diff --git a/tests/helpers/run_backends.py b/tests/helpers/run_backends.py index 57cc9ab..70c82fb 100644 --- a/tests/helpers/run_backends.py +++ b/tests/helpers/run_backends.py @@ -21,7 +21,7 @@ def wait_for(process, ready): def main(): - weston, xwayland, test, timers, tablet = sys.argv[1:] + weston, xwayland, test, timers, tablet, hello, input_x11 = sys.argv[1:] servers = [] with tempfile.TemporaryDirectory(prefix="yasl-backends-") as directory: root = Path(directory) @@ -80,10 +80,16 @@ def main(): x_env["XDG_SESSION_TYPE"] = "x11" print("Test: X11 surface timers", flush=True) subprocess.run([timers], env=x_env, check=True, timeout=8) + print("Test: X11 UTF-8 keyboard fallback and clipboard", flush=True) + subprocess.run([input_x11], env=x_env, check=True, timeout=8) for backend in ("wayland", "x11"): print("Test: tablet example on", backend, flush=True) subprocess.run([tablet, "--backend", backend, "--smoke-test"], env=env, check=True, timeout=8) + print("Test: hello example on", backend, flush=True) + subprocess.run([hello, "--smoke-test"], + env=env if backend == "wayland" else x_env, + check=True, timeout=8) except BaseException: for log in (wl_log, x_log): log.flush() diff --git a/tests/helpers/run_cocoa_bundle.py b/tests/helpers/run_cocoa_bundle.py new file mode 100644 index 0000000..338f38e --- /dev/null +++ b/tests/helpers/run_cocoa_bundle.py @@ -0,0 +1,68 @@ +#!/usr/bin/env python3 +"""Run a packaged Cocoa suite, preserving output and a machine-readable report.""" + +import argparse +import hashlib +import json +import os +from pathlib import Path +import platform +import re +import subprocess +import sys + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--list', action='store_true', help='List tests without executing them.') + args = parser.parse_args() + root = Path(__file__).resolve().parent + manifest = json.loads((root / 'manifest.json').read_text()) + if args.list: + print('Architecture:', manifest['architecture']) + for test in manifest['tests']: + print(test['name']) + return + if sys.platform != 'darwin': + parser.error('Run this suite in a macOS desktop session.') + if int(platform.mac_ver()[0].split('.')[0]) < manifest['minimum_macos']: + parser.error('This suite requires macOS 14 or newer.') + architecture = {'arm64': 'aarch64'}.get(platform.machine(), platform.machine()) + if architecture != manifest['architecture']: + parser.error('Use the bundle matching this Python process architecture.') + for relative, expected in manifest['sha256'].items(): + if hashlib.sha256((root / relative).read_bytes()).hexdigest() != expected: + parser.error('Bundle file changed: ' + relative) + + logs = root / 'logs' + logs.mkdir(exist_ok=True) + env = os.environ.copy() + env['DYLD_LIBRARY_PATH'] = str(root) + results = [] + for test in manifest['tests']: + name = test['name'] + log = logs / (re.sub(r'[^A-Za-z0-9_-]', '_', name) + '.log') + command = [str(root / test['cmd'][0]), *test['cmd'][1:]] + with log.open('w') as output: + try: + process = subprocess.run(command, cwd=root, env=env, stdout=output, + stderr=subprocess.STDOUT, timeout=test['timeout'] or None) + result = {'name': name, 'returncode': process.returncode, + 'status': 'pass' if process.returncode == 0 else 'fail'} + except subprocess.TimeoutExpired: + output.write('\nTest timed out.\n') + result = {'name': name, 'status': 'timeout'} + except OSError as error: + output.write(str(error) + '\n') + result = {'name': name, 'status': 'error'} + results.append(result) + print(f'{name}: {result["status"]}', flush=True) + report = root / 'results.json' + report.write_text(json.dumps(results, indent=2) + '\n') + failed = sum(result['status'] != 'pass' for result in results) + print(f'{len(results) - failed} passed, {failed} failed. Logs: {logs}') + sys.exit(1 if failed else 0) + + +if __name__ == '__main__': + main() diff --git a/tests/meson.build b/tests/meson.build index 910f17c..c6570d9 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -30,16 +30,20 @@ if add_languages('cpp', native: false, required: false) 'yasl-cpp-api-test', 'test_api.cpp', dependencies: shared_dep, - cpp_args: cpp.get_supported_arguments('-pedantic-errors'), + cpp_args: cpp.get_supported_arguments('-pedantic-errors') + [ + '-DYASL_HAS_WAYLAND=' + (has_wayland ? '1' : '0'), + '-DYASL_HAS_X11=' + (has_x11 ? '1' : '0'), + '-DYASL_HAS_COCOA=' + (has_cocoa ? '1' : '0'), + ], override_options: ['cpp_std=c++11'], ) test('cpp-api', cpp_api_test) endif -python = find_program('python3') -if system == 'linux' - nm = find_program('nm') - export_args = [] +python = find_program('python3', native: true) +if system == 'linux' or system == 'darwin' + nm = find_program('nm', native: false) + export_args = ['--platform=' + system] if get_option('b_sanitize').contains('address') # Clang's ASan instrumentation exports these linker-generated markers. export_args += ['--allow-export=__start_asan_globals', @@ -57,6 +61,9 @@ if system == 'linux' if has_x11 exported_headers += files('../include/yasl/native/x11.h') endif + if has_cocoa + exported_headers += files('../include/yasl/native/cocoa.h') + endif test('public-exports', python, args: [files('helpers/check_exports.py')] + export_args + [nm, yasl_lib.get_shared_lib(), exported_headers], @@ -71,6 +78,16 @@ contracts_test = executable( ) test('contracts', contracts_test) +keyboard_test = executable('yasl-keyboard-test', 'common/test_keyboard.c', + include_directories: inc, dependencies: yasl_dep, +) +test('keyboard', keyboard_test) + +utf8_test = executable('yasl-utf8-test', 'common/test_utf8.c', + include_directories: inc, dependencies: yasl_dep, +) +test('utf8', utf8_test) + timer_test = executable( 'yasl-timer-test', 'common/test_timers.c', @@ -118,6 +135,14 @@ elif get_option('x11_tablet_tests') endif if has_wayland + clipboard_wayland_test = executable('yasl-clipboard-wayland-test', 'wayland/test_clipboard.c', + include_directories: inc, dependencies: yasl_dep, + ) + test('clipboard-wayland', clipboard_wayland_test) + keyboard_wayland_test = executable('yasl-keyboard-wayland-test', 'wayland/test_keyboard.c', + include_directories: inc, dependencies: yasl_dep, + ) + test('keyboard-wayland', keyboard_wayland_test) ime_test = executable('yasl-ime-test', 'wayland/test_input.c', include_directories: inc, dependencies: yasl_dep, @@ -143,6 +168,9 @@ benchmark('performance', benchmark_exe) if get_option('integration_tests') if has_cocoa + test('hello-cocoa-window', hello_example, + args: ['--smoke-test'], timeout: 20, + ) native_test = executable('yasl-native-test', 'cocoa/test_native.c', dependencies: shared_dep, ) @@ -151,6 +179,10 @@ if get_option('integration_tests') dependencies: [shared_dep, deps], ) test('native-ownership', ownership_test, timeout: 20) + keyboard_cocoa_test = executable('yasl-keyboard-cocoa-test', 'cocoa/test_keyboard.m', + dependencies: [shared_dep, deps], + ) + test('keyboard-cocoa', keyboard_cocoa_test, timeout: 20) tablet_cocoa_test = executable('yasl-tablet-cocoa-test', 'cocoa/test_tablet.m', dependencies: [shared_dep, deps], ) @@ -171,11 +203,14 @@ if get_option('integration_tests') 'common/test_backends.c', dependencies: [shared_dep, deps], ) + input_x11_test = executable('yasl-input-x11-test', 'x11/test_input.c', + include_directories: inc, dependencies: yasl_dep, + ) weston = find_program('weston') xwayland = find_program('Xwayland') test('backends', python, args: [files('helpers/run_backends.py'), weston, xwayland, - backend_test, timer_test, tablet_example], + backend_test, timer_test, tablet_example, hello_example, input_x11_test], timeout: 60, ) endif diff --git a/tests/test_api.cpp b/tests/test_api.cpp index 9fb8525..129a41e 100644 --- a/tests/test_api.cpp +++ b/tests/test_api.cpp @@ -5,6 +5,9 @@ #if YASL_HAS_X11 #include "yasl/native/x11.h" #endif +#if YASL_HAS_COCOA +#include "yasl/native/cocoa.h" +#endif #include "yasl/loop.h" #include <yasl/timing.h> #include <yasl/yasl.h> @@ -28,6 +31,10 @@ int main() yasl_loop_destroy(loop); yasl_input_event event{}; + event.key.key = YASL_KEY_A; + assert(event.key.key == YASL_KEY_A); + event.mouse.scroll = {0.25, -0.5}; + assert(event.mouse.scroll.x == 0.25 && event.mouse.scroll.y == -0.5); assert(!yasl_surface_input_poll(nullptr, &event)); assert(!yasl_display_drag_start(nullptr, nullptr, nullptr, nullptr, nullptr)); assert(!yasl_surface_drag_carry(nullptr, {0, 0})); @@ -42,5 +49,11 @@ int main() assert(!yasl_x11_surface_get_window(nullptr)); #endif +#if YASL_HAS_COCOA + assert(!yasl_cocoa_display_get_application(nullptr)); + assert(!yasl_cocoa_surface_get_window(nullptr)); + assert(!yasl_cocoa_surface_get_view(nullptr)); +#endif + return 0; } diff --git a/tests/wayland/test_clipboard.c b/tests/wayland/test_clipboard.c new file mode 100644 index 0000000..553e84d --- /dev/null +++ b/tests/wayland/test_clipboard.c @@ -0,0 +1,47 @@ +#include "../../src/wayland/clipboard.c" +#include <assert.h> + +struct received { int count; size_t len; char text[32]; }; + +static void receive(const char *text, size_t len, bool uri_list, + struct wl_surface *surface, void *ud) +{ + (void)surface; + struct received *r = ud; + assert(!uri_list && len < sizeof(r->text)); + memcpy(r->text, text, len); + r->text[len] = '\0'; + r->len = len; + r->count++; +} + +int main(void) +{ + struct received received = {0}; + struct clipboard c = {.loop = yasl_loop_create(), .receive = receive, .ud = &received}; + assert(c.loop); + const struct { const char *bytes; size_t len; bool valid; } cases[] = { + {"é字😀", sizeof("é字😀") - 1, true}, + {"", 0, true}, + {"\xff", 1, false}, + {"\xf0\x9f\x98", 3, false}, /* Incomplete non-BMP character. */ + }; + for (size_t i = 0; i < sizeof(cases) / sizeof(cases[0]); i++) { + received = (struct received){0}; + int fds[2]; + assert(pipe(fds) == 0); + assert(start_transfer(&c, fds[0], false, false)); + assert(write(fds[1], cases[i].bytes, cases[i].len) == (ssize_t)cases[i].len); + close(fds[1]); + for (int steps = 0; c.transfers && steps < 10; steps++) + assert(yasl_loop_step(c.loop, 0) >= 0); + assert(!c.transfers); + assert(received.count == (int)cases[i].valid); + if (cases[i].valid) { + assert(received.len == cases[i].len); + assert(memcmp(received.text, cases[i].bytes, received.len) == 0); + } + } + yasl_loop_destroy(c.loop); + return 0; +} diff --git a/tests/wayland/test_keyboard.c b/tests/wayland/test_keyboard.c new file mode 100644 index 0000000..dbe0a94 --- /dev/null +++ b/tests/wayland/test_keyboard.c @@ -0,0 +1,128 @@ +#include "../../src/wayland/keyboard.c" +#include <assert.h> + +static struct yasl_input_event next(struct wayland_surface *w, enum yasl_input_kind kind) +{ + struct yasl_input_event ev; + assert(yasl_surface_input_poll(&w->base, &ev)); + assert(ev.kind == kind && ev.surface == &w->base); + return ev; +} + +static void empty(struct wayland_surface *w) +{ + struct yasl_input_event ev; + assert(!yasl_surface_input_poll(&w->base, &ev)); +} + +static void layout(struct seat *s, const char *name, const char *variant) +{ + keyboard_text_reset(s); + if (s->xkb_state) xkb_state_unref(s->xkb_state); + if (s->xkb_keymap) xkb_keymap_unref(s->xkb_keymap); + struct xkb_rule_names names = {.layout = name, .variant = variant}; + s->xkb_keymap = xkb_keymap_new_from_names(s->conn->xkb_ctx, &names, 0); + assert(s->xkb_keymap); + s->xkb_state = xkb_state_new(s->xkb_keymap); + assert(s->xkb_state); + s->input_mods_ready = false; + s->mod_alt = xkb_keymap_mod_get_index(s->xkb_keymap, XKB_MOD_NAME_ALT); +} + +static void modifiers(struct seat *s, const char *name) +{ + xkb_mod_mask_t mask = name ? 1u << xkb_keymap_mod_get_index(s->xkb_keymap, name) : 0; + xkb_state_update_mask(s->xkb_state, mask, 0, 0, 0, 0, 0); +} + +static void key(struct seat *s, uint32_t code, bool down) +{ + keyboard_listener.key(s, NULL, 1, 0, code, down ? + WL_KEYBOARD_KEY_STATE_PRESSED : WL_KEYBOARD_KEY_STATE_RELEASED); +} + +int main(void) +{ + struct wayland_display d = {.base.ops = &yasl_wayland_backend}; + d.xkb_ctx = xkb_context_new(0); + assert(d.xkb_ctx); + struct wayland_surface w = {.base.display = &d.base, .conn = &d}; + wayland_surface_set_callbacks(&w, NULL, NULL); + struct seat s = {.conn = &d, .keyboard_focus = &w, .repeat_fd = -1, + .compose_attempted = true}; + const char compose[] = "<dead_acute> <e> : \"é\" U00E9\n"; + struct xkb_compose_table *table = xkb_compose_table_new_from_buffer(d.xkb_ctx, + compose, sizeof(compose) - 1, "C.UTF-8", XKB_COMPOSE_FORMAT_TEXT_V1, 0); + assert(table); + s.compose = xkb_compose_state_new(table, 0); + assert(s.compose); + xkb_compose_table_unref(table); + layout(&s, "us", NULL); + key(&s, KEY_A, true); + struct yasl_input_event ev = next(&w, YASL_INPUT_KEY); + assert(ev.key.key == YASL_KEY_A && ev.key.native_code == KEY_A); + assert(ev.key.codepoint == 'a' && ev.key.shifted == 'A' && !ev.key.mods); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "a") == 0); + modifiers(&s, XKB_MOD_NAME_SHIFT); + key(&s, KEY_A, false); /* Modifier changes cannot change physical identity. */ + ev = next(&w, YASL_INPUT_KEY); + assert(ev.key.key == YASL_KEY_A && ev.key.action == YASL_KEY_RELEASE); + assert(ev.key.mods == YASL_MOD_SHIFT); + empty(&w); + key(&s, KEY_A, true); + next(&w, YASL_INPUT_KEY); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "A") == 0); + modifiers(&s, XKB_MOD_NAME_CAPS); + key(&s, KEY_A, true); + assert(next(&w, YASL_INPUT_KEY).key.mods == YASL_MOD_CAPS); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "A") == 0); + const char *shortcuts[] = {XKB_MOD_NAME_CTRL, XKB_MOD_NAME_ALT, XKB_MOD_NAME_LOGO}; + for (size_t i = 0; i < sizeof(shortcuts)/sizeof(shortcuts[0]); i++) { + modifiers(&s, shortcuts[i]); + key(&s, KEY_A, true); + next(&w, YASL_INPUT_KEY); + empty(&w); /* Shortcut characters never leak into committed text. */ + } + layout(&s, "fr", NULL); + key(&s, KEY_A, true); + ev = next(&w, YASL_INPUT_KEY); + assert(ev.key.key == YASL_KEY_A && ev.key.codepoint == 'q'); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "q") == 0); + layout(&s, "de", NULL); + modifiers(&s, "Mod5"); /* AltGr is text input, not an Alt shortcut. */ + key(&s, KEY_E, true); + assert(next(&w, YASL_INPUT_KEY).key.key == YASL_KEY_E); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "€") == 0); + layout(&s, "us", "intl"); + key(&s, KEY_APOSTROPHE, true); + next(&w, YASL_INPUT_KEY); + empty(&w); + key(&s, KEY_E, true); + next(&w, YASL_INPUT_KEY); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "é") == 0); + assert(keyboard_dispatch_key(&s, &w, KEY_E, YASL_KEY_REPEAT)); + assert(next(&w, YASL_INPUT_KEY).key.action == YASL_KEY_REPEAT); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "e") == 0); + key(&s, KEY_APOSTROPHE, true); + next(&w, YASL_INPUT_KEY); + keyboard_reset_keys(&s, &w); + key(&s, KEY_E, true); + next(&w, YASL_INPUT_KEY); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "e") == 0); + key(&s, KEY_APOSTROPHE, true); + next(&w, YASL_INPUT_KEY); + s.ime_focus = &w; + text_input_listener.commit_string(&s, NULL, "字"); + text_input_listener.done(&s, NULL, 0); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "字") == 0); + key(&s, KEY_E, true); + next(&w, YASL_INPUT_KEY); + assert(strcmp(next(&w, YASL_INPUT_TEXT).text.text, "e") == 0); + empty(&w); + xkb_compose_state_unref(s.compose); + xkb_state_unref(s.xkb_state); + xkb_keymap_unref(s.xkb_keymap); + xkb_context_unref(d.xkb_ctx); + input_queue_clear(&w.input); + return 0; +} diff --git a/tests/wayland/test_tablet.c b/tests/wayland/test_tablet.c index 449c446..f8982b0 100644 --- a/tests/wayland/test_tablet.c +++ b/tests/wayland/test_tablet.c @@ -50,6 +50,7 @@ int main(void) tool_frame(&tool, NULL, 0); ev = next(&surface); assert(ev.kind == YASL_PTR_SCROLL && ev.device == YASL_PTR_DEV_ERASER); + assert(ev.scroll.x == 0 && ev.scroll.y == 1); tablet_tool_proximity_out(&tool, NULL); ev = next(&surface); assert(ev.kind == YASL_PTR_LEAVE && ev.device == YASL_PTR_DEV_ERASER && !ev.pen.pressure); @@ -57,6 +58,42 @@ int main(void) assert(!(yasl_display_caps(&display.base) & YASL_CAP_TABLET)); display.tablet_mgr = (void *)&display; /* Capability depends on protocol availability. */ assert(yasl_display_caps(&display.base) & YASL_CAP_TABLET); + + seat.pointer_focus = &surface; + /* A compositor may describe the same detent in three ways. value120 wins, + * and both axes belong to one event, without whole-line truncation. */ + pointer_axis(&seat, NULL, 0, WL_POINTER_AXIS_VERTICAL_SCROLL, wl_fixed_from_int(10)); + pointer_axis_discrete(&seat, NULL, WL_POINTER_AXIS_VERTICAL_SCROLL, 1); + pointer_axis_value120(&seat, NULL, WL_POINTER_AXIS_VERTICAL_SCROLL, 30); + pointer_axis_value120(&seat, NULL, WL_POINTER_AXIS_HORIZONTAL_SCROLL, -60); + pointer_frame(&seat, NULL); + ev = next(&surface); + assert(ev.kind == YASL_PTR_SCROLL && ev.device == YASL_PTR_DEV_MOUSE); + assert(ev.scroll.x == -0.5 && ev.scroll.y == 0.25); + struct yasl_input_event unused; + assert(!yasl_surface_input_poll(&surface.base, &unused)); + pointer_frame(&seat, NULL); + assert(!yasl_surface_input_poll(&surface.base, &unused)); + + /* Stops preserve offsets from the same frame. Repeated tiny movements + * must be visible immediately rather than held until a whole detent. */ + for (int i = 0; i < 3; i++) { + pointer_axis_source(&seat, NULL, WL_POINTER_AXIS_SOURCE_FINGER); + pointer_axis(&seat, NULL, 0, WL_POINTER_AXIS_VERTICAL_SCROLL, wl_fixed_from_double(1.25)); + pointer_axis(&seat, NULL, 0, WL_POINTER_AXIS_HORIZONTAL_SCROLL, wl_fixed_from_double(-2.5)); + pointer_axis_stop(&seat, NULL, 0, WL_POINTER_AXIS_VERTICAL_SCROLL); + pointer_frame(&seat, NULL); + ev = next(&surface); + assert(ev.scroll.x == -0.25 && ev.scroll.y == 0.125); + } + pointer_axis_discrete(&seat, NULL, WL_POINTER_AXIS_HORIZONTAL_SCROLL, 2); + pointer_frame(&seat, NULL); + ev = next(&surface); + assert(ev.scroll.x == 2 && ev.scroll.y == 0); + pointer_axis_value120(&seat, NULL, WL_POINTER_AXIS_VERTICAL_SCROLL, 60); + seat_pointer_reset(&seat); + pointer_frame(&seat, NULL); + assert(!yasl_surface_input_poll(&surface.base, &unused)); input_queue_clear(&surface.input); return 0; } diff --git a/tests/x11/test_input.c b/tests/x11/test_input.c new file mode 100644 index 0000000..11dca4f --- /dev/null +++ b/tests/x11/test_input.c @@ -0,0 +1,123 @@ +/* An isolated real X server supplies the keymap; disabling this surface's XIC + * deliberately exercises text insertion when no input method is available. */ +#include "../../src/x11/window.c" + +static void check_selection_encoding(struct x11_display *d, struct x11_surface *s) +{ + Window requestor = XCreateSimpleWindow(d->native, DefaultRootWindow(d->native), + 0, 0, 1, 1, 0, 0, 0); + Atom property = XInternAtom(d->native, "YASL_TEST_STRING", False); + XSelectionRequestEvent request = {.display = d->native, .requestor = requestor, + .selection = d->clipboard, .target = XA_STRING, .property = property}; + yasl_display_copy(&d->base, YASL_CLIPBOARD, "café £"); + selection_request(d, &request); + Atom actual; + int format; + unsigned long count, left; + unsigned char *data = NULL; + assert(XGetWindowProperty(d->native, requestor, property, 0, 100, True, + AnyPropertyType, &actual, &format, &count, &left, &data) == Success); + assert(actual == XA_STRING && format == 8 && count == 6); + assert(memcmp(data, "caf\xe9 \xa3", count) == 0); + XFree(data); + yasl_display_copy(&d->base, YASL_CLIPBOARD, "字"); + selection_request(d, &request); + assert(XGetWindowProperty(d->native, requestor, property, 0, 100, True, + AnyPropertyType, &actual, &format, &count, &left, &data) == Success); + assert(actual == None); /* Never mislabel UTF-8 as Latin-1. */ + if (data) XFree(data); + request.target = d->targets; + selection_request(d, &request); + assert(XGetWindowProperty(d->native, requestor, property, 0, 100, True, + AnyPropertyType, &actual, &format, &count, &left, &data) == Success); + assert(actual == XA_ATOM && format == 32 && count == 2); + assert(((Atom *)data)[0] == d->targets && ((Atom *)data)[1] == d->utf8); + XFree(data); + XDestroyWindow(d->native, requestor); + + /* Simulate a legacy owner returning STRING to the paste conversion window, + * then an empty UTF-8 owner and malformed UTF-8. */ + const struct { Atom type; const char *bytes; size_t len; const char *expected; } cases[] = { + {XA_STRING, "caf\xe9 \xa3", 6, "café £"}, + {d->utf8, "", 0, ""}, + {d->utf8, "\xff", 1, NULL}, + }; + for (size_t i = 0; i < sizeof(cases) / sizeof(cases[0]); i++) { + struct paste_request *pending = calloc(1, sizeof(*pending)); + assert(pending); + pending->window = XCreateSimpleWindow(d->native, DefaultRootWindow(d->native), + 0, 0, 1, 1, 0, 0, 0); + pending->target = s; + pending->next = d->pastes; + d->pastes = pending; + XChangeProperty(d->native, pending->window, property, cases[i].type, 8, + PropModeReplace, (const unsigned char *)cases[i].bytes, (int)cases[i].len); + XSelectionEvent reply = {.requestor = pending->window, .property = property}; + selection_notify(d, &reply); + struct yasl_input_event event; + if (cases[i].expected) { + assert(yasl_surface_input_poll(&s->base, &event)); + assert(event.kind == YASL_INPUT_PASTE); + assert(event.paste.len == strlen(cases[i].expected)); + assert(strcmp(event.paste.text, cases[i].expected) == 0); + } + assert(!yasl_surface_input_poll(&s->base, &event)); + } +} + +int main(void) +{ + struct yasl_display_spec ds = {.backend = YASL_BACKEND_X11}; + struct yasl_display *base = yasl_display_open(NULL, &ds); + assert(base); + struct x11_display *d = (struct x11_display *)base; + struct yasl_surface_spec spec = {.title = "Keyboard fallback", .size = {100, 100}}; + struct yasl_surface *surface = yasl_surface_create_toplevel(base, &spec); + assert(surface); + struct x11_surface *s = (struct x11_surface *)surface; + XIC saved_ic = s->ic; + s->ic = NULL; + unsigned code = XKeysymToKeycode(d->native, XK_a); + int width = 0; + KeySym *saved = XGetKeyboardMapping(d->native, code, 1, &width); + assert(saved && width >= 2); + KeySym *symbols = calloc((size_t)width, sizeof(*symbols)); + assert(symbols); + const struct { KeySym symbol, shifted; const char *text; uint32_t label; } cases[] = { + {XK_eacute, XK_Eacute, "é", 0xe9}, + {0x01000416, 0x01000416, "Ж", 0x416}, + {0x0101f600, 0x0101f600, "😀", 0x1f600}, + }; + for (size_t i = 0; i < sizeof(cases) / sizeof(cases[0]); i++) { + symbols[0] = cases[i].symbol; + symbols[1] = cases[i].shifted; + XChangeKeyboardMapping(d->native, code, width, symbols, 1); + XSync(d->native, False); + dispatch(base); + input_queue_clear(&s->input); + XKeyEvent native = {.type = KeyPress, .display = d->native, + .window = s->window, .keycode = code}; + key_event(s, &native, false); + struct yasl_input_event event; + assert(yasl_surface_input_poll(surface, &event)); + assert(event.kind == YASL_INPUT_KEY && event.key.key == YASL_KEY_A); + assert(event.key.codepoint == cases[i].label); + assert(yasl_surface_input_poll(surface, &event)); + assert(event.kind == YASL_INPUT_TEXT && event.text.len == strlen(cases[i].text)); + assert(strcmp(event.text.text, cases[i].text) == 0); + assert(!yasl_surface_input_poll(surface, &event)); + native.type = KeyRelease; + key_event(s, &native, false); + assert(yasl_surface_input_poll(surface, &event) && event.kind == YASL_INPUT_KEY); + assert(!yasl_surface_input_poll(surface, &event)); + } + XChangeKeyboardMapping(d->native, code, width, saved, 1); + XSync(d->native, False); + free(symbols); + XFree(saved); + s->ic = saved_ic; + check_selection_encoding(d, s); + yasl_surface_destroy(surface); + yasl_display_close(base); + return 0; +} diff --git a/tests/x11/test_tablet.c b/tests/x11/test_tablet.c index c35a266..ba815cb 100644 --- a/tests/x11/test_tablet.c +++ b/tests/x11/test_tablet.c @@ -341,6 +341,19 @@ int main(void) xi_pointer_event(&surface, &sample); ev = next(&surface); assert(ev.device == YASL_PTR_DEV_MOUSE && ev.button == 2 && ev.pen.pressure == 0); + for (int button = 4; button <= 7; button++) { + sample.detail = button; + sample.evtype = XI_ButtonPress; + xi_pointer_event(&surface, &sample); + ev = next(&surface); + assert(ev.kind == YASL_PTR_SCROLL); + assert(ev.scroll.x == (button == 6 ? -1 : button == 7 ? 1 : 0)); + assert(ev.scroll.y == (button == 4 ? -1 : button == 5 ? 1 : 0)); + sample.evtype = XI_ButtonRelease; + xi_pointer_event(&surface, &sample); + struct yasl_input_event unused; + assert(!yasl_surface_input_poll(&surface.base, &unused)); + } assert(pointer_button(2) == 1 && pointer_button(8) == 3); pointer.pressure = (struct tablet_axis){2, 1, 1, 50}; assert(pressure_value(&pointer.pressure) == 0); |