From 76073fe5fad8799e5850805f2f090af2cb62c741 Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Tue, 13 Oct 2026 23:41:31 +0300 Subject: Simplify the public event and CPU API Applications now need far less ceremony: hello.c is a 20-line loop that handles REFRESH, CLOSE and QUIT and draws into the surface's own pixels. - Fold GEOMETRY, STATE and FOCUS into one WINDOW event carrying size, scale and state; unchanged values send nothing. - Guarantee REFRESH once a window has a size and after every resize, never at size zero. - Merge DROP_HOVER into DROP with over/leave/data actions and give drag and drop actions enums. - Keep event strings valid until the next wait and drop yasl_event_release; empty or failed waits report NONE. - Replace copy-in presentation with a lent pixel buffer: yasl_cpu_pixels and yasl_cpu_present. - Remove yasl_poll_event, yasl_cpu_read_pixels, unused event fields and comments that restated names. - Wayland: resize floating windows in request_size instead of reporting it unsupported, and stop marking new GPU surfaces as Vulkan so yasl_vulkan_create_surface no longer fails with NATIVE_WINDOW_IN_USE. Also includes the in-progress public API refactor that was uncommitted in the tree (removal of the app/loop layer, new surface, GL and Vulkan entry points). Co-Authored-By: Claude Opus 5.5 --- docs/api-policy.md | 48 ++++++++++++++---------------------------------- 1 file changed, 14 insertions(+), 34 deletions(-) (limited to 'docs/api-policy.md') diff --git a/docs/api-policy.md b/docs/api-policy.md index 3e510f3..f2f4d92 100644 --- a/docs/api-policy.md +++ b/docs/api-policy.md @@ -1,38 +1,18 @@ # Public API policy -YASL 0.1 is pre-release. The headers under `include/yasl/` 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 public headers. -Native backend accessors are exported only for built backends. Installation -copies both libraries, public headers, enabled native headers, and pkg-config metadata. +YASL is pre-release 0.1. Source and ABI compatibility are not guaranteed. Rebuild +consumers against matching installed headers/library; do not serialize public events +or assume their layout is a stable file/network format. -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 release version is declared in -`meson.build`. +Only installed include/yasl headers are public. The surface library exposes an +opaque surface and one tagged event record, with direct C arguments and ordinary +pointer/integer results. Native backend headers, geometry records, callbacks, loops, +and drawing targets under src are private even when a static archive contains them. +The shared library exports exactly the installed public declarations. -See [migration notes](migrating.md) for window creation, portable keyboard, and -fractional scroll API changes. - -API changes should keep ordinary CPU drawing usable with only `` -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 consumers of the installed library 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. +Do not restore removed runner/frame/display APIs or compatibility aliases. Keep +rendering bridges separate from the portable surface/input core and preserve the +application's ownership of GPU resources and its loop. Public additions need clear +units, ownership, thread/callback timing, errors and unsupported behavior, useful +examples, and behavior coverage. Update the guide and test installed shared/static +consumers and exports. Changes affecting Cocoa need a native macOS build/test. -- cgit v1.2.3