diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 47 |
1 files changed, 46 insertions, 1 deletions
@@ -76,6 +76,47 @@ The native surface handle is a `wl_surface *` on Wayland. On X11, convert it to `Window` through `uintptr_t`. On Cocoa, the native surface handle is the content `NSView *`. +## 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. 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. +- A non-NULL `graphics_device` requires `YASL_CAP_NATIVE_GRAPHICS` (currently + Cocoa); other backends reject it with `ENOTSUP`. In native Metal mode the app + submits and presents the drawable, then calls `yasl_surface_present()` to + record that submission. +- `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. @@ -104,7 +145,11 @@ 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. +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. |