From dd1775a9927922c14f8679ccbc4d3ca8d5917e20 Mon Sep 17 00:00:00 2001 From: Berke Güzel Date: Tue, 13 Oct 2026 21:23:03 +0300 Subject: public api refactor --- include/yasl/app.h | 87 ++++++++++-------------------------------------------- 1 file changed, 16 insertions(+), 71 deletions(-) (limited to 'include/yasl/app.h') diff --git a/include/yasl/app.h b/include/yasl/app.h index b7e1c13..78e62c4 100644 --- a/include/yasl/app.h +++ b/include/yasl/app.h @@ -21,74 +21,12 @@ extern "C" { typedef enum yasl_app_result { YASL_APP_CONTINUE = 0, /**< Continue running the application. */ YASL_APP_QUIT, /**< Request graceful termination of yasl_run(). */ + YASL_APP_ERROR, /**< Request orderly cleanup and a failing run result. */ } yasl_app_result; -/** Pacing mode governing when frame() callbacks are invoked. */ -typedef enum yasl_pacing_mode { - /** - * Reactive / on-demand presentation (ideal for IDEs, text editors, tools). - * The application sleeps at 0% CPU when idle. frame() is only invoked when - * explicitly requested via yasl_surface_request_frame() or upon OS window - * expose/resize events. - */ - YASL_PACING_ON_DEMAND = 0, - - /** - * Continuous vsync-aligned tick (ideal for game engines and animations). - * frame() is driven continuously at the display's native refresh rate - * (e.g. 60/120/144 Hz) via DisplayLink, Wayland frame callbacks, or loop timers. - */ - YASL_PACING_CONTINUOUS, -} yasl_pacing_mode; - -/** Frame context provided to yasl_app_desc.frame() during presentation. */ -struct yasl_frame_context { - struct yasl_surface *surface; - uint64_t frame_index; - uint64_t target_time_ns; /**< Monotonic timestamp aligned to display refresh. */ - struct yasl_vector2i size; /**< Surface content size in device pixels. */ - uint32_t scale_120; - - /** CPU software rendering target, if surface was created for CPU blitting. */ - struct { - uint32_t *pixels; /**< Writable premultiplied 0xAARRGGBB device pixels. */ - int stride_bytes; /**< Row stride in bytes. */ - } cpu; - - /** Native GPU rendering layer/surface, if surface was created for GPU rendering. */ - struct { - void *native_layer; /**< CAMetalLayer* on Cocoa, wl_surface* on Wayland, Window on X11. */ - } gpu; - - /** Internal handle used by yasl_frame_present_cpu. Applications must not touch. */ - void *internal_handle; -}; - -/** - * Present CPU software target pixels. - * @param ctx Active frame context passed to yasl_app_desc.frame(). - * @param dirty_rects Optional array of damaged rectangles in device pixels. - * Pass NULL or count <= 0 to indicate full-surface damage. - * @param count Number of rectangles in dirty_rects. - * @return true if accepted, false on presentation failure. - */ -YASL_API bool yasl_frame_present_cpu(struct yasl_frame_context *ctx, - const struct yasl_rect2i *dirty_rects, - int count); - -/** - * Configure the presentation pacing mode for a surface. - * @param s Surface. - * @param mode YASL_PACING_ON_DEMAND for reactive UI, YASL_PACING_CONTINUOUS for games. - */ -YASL_API void yasl_surface_set_pacing(struct yasl_surface *s, yasl_pacing_mode mode); - -/** - * Mark a surface as needing a redraw on the next frame pass. - * Wakes the event loop if sleeping under YASL_PACING_ON_DEMAND. - * @param s Surface. - */ -YASL_API void yasl_surface_request_frame(struct yasl_surface *s); +/** Migration adapter; prefer yasl_frame_present() from yasl.h. */ +YASL_API bool yasl_frame_present_cpu(struct yasl_frame *frame, + const struct yasl_rect2i *dirty_rects, int count); /** * Safely post a custom user event to the main event loop from ANY thread. @@ -99,7 +37,9 @@ YASL_API void yasl_surface_request_frame(struct yasl_surface *s); * @param payload Arbitrary pointer passed through to the event. * @param size Optional payload size. * @return true if queued; false if memory failed or d is not run by yasl_run(). - * Applications that run their own loop use yasl_loop_post() instead. + * Migration adapter: keep s alive through the call, and stop producers before + * shutdown. Prefer yasl_display_post() with a captured ID and release callback + * in either loop style; legacy payloads have no cancellation cleanup. */ YASL_API bool yasl_post_event(struct yasl_display *d, struct yasl_surface *s, uint32_t code, void *payload, size_t size); @@ -159,15 +99,15 @@ struct yasl_app_desc { /** * Optional; called once after display and event machinery initialization. * Use this to create further windows and initialize application resources. - * Return YASL_APP_CONTINUE or YASL_APP_QUIT. + * Return YASL_APP_CONTINUE, YASL_APP_QUIT, or YASL_APP_ERROR. */ enum yasl_app_result (*init)(void *ud, struct yasl_display *d); /** - * Unified event handler for input, window and user events, in arrival order. + * Unified event handler for input, window and user events, in display-wide enqueue order. * Event payloads and borrowed strings are valid for the duration of the callback. * INPUT_RESET has no payload and requires clearing held application input. - * Return YASL_APP_CONTINUE or YASL_APP_QUIT. Optional; without it, a + * Return YASL_APP_CONTINUE, YASL_APP_QUIT, or YASL_APP_ERROR. Optional; without it, a * WINDOW_CLOSE request on any window stops yasl_run(). */ enum yasl_app_result (*event)(void *ud, const struct yasl_event *ev); @@ -176,7 +116,7 @@ struct yasl_app_desc { * Invoked when a surface needs to present a frame. * Synchronized automatically with display pacing and live window resizing. */ - void (*frame)(void *ud, struct yasl_surface *s, struct yasl_frame_context *ctx); + void (*frame)(void *ud, struct yasl_surface *s, struct yasl_frame *frame); /** * Called right before the display is closed and yasl_run() exits. @@ -185,6 +125,11 @@ struct yasl_app_desc { void (*quit)(void *ud, struct yasl_display *d); }; +/** Request orderly exit from any display-thread callback; ERROR returns failure. */ +YASL_API void yasl_app_exit(struct yasl_display *d, enum yasl_app_result result); +/** Borrow the optional desc.window surface during init or later; NULL if absent/destroyed. */ +YASL_API struct yasl_surface *yasl_app_window(struct yasl_display *d); + /** * Run the application with the inverted lifecycle runner. * Handles the display event loop, live-resizing, pacing, and cleanup. -- cgit v1.2.3