diff options
Diffstat (limited to 'docs/migrating.md')
| -rw-r--r-- | docs/migrating.md | 45 |
1 files changed, 42 insertions, 3 deletions
diff --git a/docs/migrating.md b/docs/migrating.md index 86804c8..912ea4d 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -4,6 +4,45 @@ YASL 0.1 has no stable source or binary compatibility promise. Rebuild all consumers against matching public headers and the library after updating. See the [application guide](guide.md) for the full window and input workflow. +## Display queue, frames, and application failures + +The runner now consumes the display-wide FIFO directly. Manual loops should +replace per-surface polling with `yasl_display_poll_event(display, &event)`. +Surface polling remains an input-only adapter that discards pending non-input +notifications delivered through legacy callbacks. Do not mix polling styles. Strings from either poll +now survive recipient destruction and expire at the next successful poll on +that display, or display close. Queue allocation failure is reported by dispatch +as an error instead of silently losing a lifecycle notification. + +Replace `struct yasl_frame_context` with `struct yasl_frame`, `frame->cpu.pixels` +with `frame->target.pixels`, and `frame->size` with `frame->target.size`. +`target.stride_bytes` replaces `cpu.stride_bytes`. Native drawing uses +`yasl_surface_get_native_frame(surface, &frame->target, &native)`. +`yasl_frame_present(frame, NULL, 0)` replaces the CPU presentation wrapper. +A non-NULL damage array with count zero now explicitly means no damaged pixels. +Lists larger than the backend limit become full damage instead of truncating. + +`YASL_APP_ERROR` and `yasl_app_exit(display, result)` report application failures +through `yasl_run`. `yasl_app_window(display)` gives init access to desc.window. +Use `yasl_surface_set_userdata` / `yasl_surface_userdata` for per-window state, +or `window.userdata` during creation. `yasl_surface_set_callbacks` now returns a +boolean and rejects runner-owned surfaces with EBUSY. + +Spell toplevel creation sizes `size_logical`; `size` remains an alias. +New window request functions report acceptance with errno. Pacing now works +outside the runner too, and returns a boolean instead of silently ignoring calls. + +Replace clipboard copy/paste with `yasl_clipboard_set` / `yasl_clipboard_request`. +Check the returned request ID and `event.paste.status` on completion. Empty text +is successful; missing data and transfer errors now have explicit outcomes. +Preedit snapshots arrive through `YASL_EVENT_COMPOSITION`; state and hover use +`YASL_EVENT_WINDOW_STATE`, `YASL_EVENT_DRAG`, and `YASL_EVENT_DROP_HOVER`. + +For worker messages, capture a surface ID on the display thread and use +`yasl_display_post` with an optional release callback. Do not also free the +payload in the event handler when release owns cleanup. Stop producer threads +before display shutdown; retired IDs reject posting with ENOENT. + ## Application callbacks All examples now use `<yasl/app.h>` and `yasl_run()`. Describe a single window @@ -11,7 +50,7 @@ in `yasl_app_desc.window`, or create windows in `.init`; move input handling to `.event` and drawing to `.frame`. Replace manual dispatch/poll/flush loops with the runner and request redraws with `yasl_surface_request_frame()`. Present the frame context with -`yasl_frame_present_cpu()`; the runner destroys remaining surfaces on exit. +`yasl_frame_present()`; the runner destroys remaining surfaces on exit. Window state remains a `YASL_STATE_*` bitmask; `YASL_STATE_TILED` is reported for tiled Wayland toplevels. @@ -19,8 +58,8 @@ for tiled Wayland toplevels. ## Events The core API and the runner now share one `struct yasl_event`, declared in -`<yasl/yasl.h>`. `yasl_surface_poll_event()` returns the same events that -`yasl_app_desc.event` receives, so input handling code works under both. +`<yasl/yasl.h>`. `yasl_display_poll_event()` returns the same events that +`yasl_app_desc.event` receives. Legacy surface polling returns only input types. | Previous use | Replacement | | --- | --- | |