diff options
Diffstat (limited to 'include/yasl')
| -rw-r--r-- | include/yasl/native.h | 5 | ||||
| -rw-r--r-- | include/yasl/yasl.h | 25 |
2 files changed, 21 insertions, 9 deletions
diff --git a/include/yasl/native.h b/include/yasl/native.h index d65f8d3..64bc161 100644 --- a/include/yasl/native.h +++ b/include/yasl/native.h @@ -48,15 +48,16 @@ YASL_API void *yasl_surface_get_native_handle(struct yasl_surface *s); /** * 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 spec Copied window options, with logical-pixel size and optional callbacks. * @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. + * Callback ownership and timing follow yasl_surface_create_toplevel(). */ YASL_API struct yasl_surface *yasl_surface_create_native(struct yasl_display *d, - const struct yasl_surface_spec *spec, void *graphics_device); + const struct yasl_window_spec *spec, void *graphics_device); /** Borrowed native drawable for the current draw target, currently Cocoa/Metal. */ struct yasl_native_frame { diff --git a/include/yasl/yasl.h b/include/yasl/yasl.h index f40264e..e2c1d77 100644 --- a/include/yasl/yasl.h +++ b/include/yasl/yasl.h @@ -437,10 +437,11 @@ struct yasl_display_cbs { void (*lost)(void *ud); }; -/** Optional surface notifications, copied by yasl_surface_set_callbacks(). +/** Optional window/popup notifications, copied from yasl_window_spec.cbs or 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 { +struct yasl_window_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. */ @@ -586,7 +587,7 @@ 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 { +struct yasl_window_spec { /** Copied UTF-8 title; NULL uses backend defaults. */ const char *title; /** Requested logical-pixel width and height; both must be positive. */ @@ -595,6 +596,10 @@ struct yasl_surface_spec { bool fullscreen; /** Permit unpaced presentation where supported; a hint, not a guarantee. */ bool tearing; + /** Copied optional window callbacks; NULL disables them. */ + const struct yasl_window_cbs *cbs; + /** Borrowed window callback userdata. */ + void *ud; }; /** Popup options, entirely in device pixels, including size. @@ -623,10 +628,16 @@ struct yasl_popup_spec { * @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. + * size may differ from the request. The callback table in spec->cbs is copied; + * spec->ud stays borrowed until callbacks are replaced or the surface is destroyed. + * This window's callbacks cannot run before creation returns. Use + * yasl_surface_geometry() for initial geometry; an initial configure callback + * is not guaranteed. Schedule an initial redraw after setting up application state. + * On a display owned by yasl_run(), the runner installs its own callbacks instead; + * use yasl_app_desc.event and yasl_app_desc.frame for application notifications. */ YASL_API struct yasl_surface *yasl_surface_create_toplevel(struct yasl_display *d, - const struct yasl_surface_spec *spec); + const struct yasl_window_spec *spec); /** * Create an owned popup attached to a parent surface. * @param parent Borrowed parent; destroy the popup before the parent. @@ -668,12 +679,12 @@ YASL_API struct yasl_display *yasl_surface_display(const struct yasl_surface *s) * @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. + * This call only replaces callbacks; it does not invoke them. * 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); + const struct yasl_window_cbs *cbs, void *ud); /** * Replace the window title with copied UTF-8 text. * @param s Surface. |