diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 41 |
1 files changed, 33 insertions, 8 deletions
@@ -24,6 +24,25 @@ It provides window creation, frame pacing, high-DPI scaling, and input routing w - Self-contained event queue. - No terminal-specific telemetry or hardcoded application names. +## Public API + +Include `<yasl/yasl.h>` for surface creation, drawing, input, and display dispatch. +`yasl_surface_geometry()` returns device-pixel size and scale together. +`yasl_display_dispatch(display, timeout_ms)` polls with zero, waits indefinitely +with a negative timeout, or waits up to a positive number of milliseconds. +Pending input or redraw work returns immediately; call `yasl_display_flush()` +after processing input and scheduling redraws. + +Include `<yasl/loop.h>` to use the optional event loop, file watches, or timers. +Timers use one callback model and nanoseconds throughout; use `YASL_MS_TO_NS(5)` +for a five-millisecond interval. Add application timers to +`yasl_display_loop(display)`. Add surface timers with `yasl_surface_add_timer()` +when they should be canceled automatically on surface destruction. + +Include `<yasl/native.h>` for platform handles and application-managed native +rendering. These extensions are separate from the portable CPU drawing API. +`<yasl/timing.h>` contains the public timing result types. + ## Backend selection YASL selects the native window backend at runtime. @@ -58,6 +77,8 @@ Call `yasl_display_backend(display)` to read the selected backend. All surfaces on a display use that backend. Open separate displays to use Wayland and X11 in one process. The public API needs no window system headers. +Shared libraries export only the functions declared in the installed YASL headers. +Input queues, frame clocks, backend entry points, and protocol helpers are private implementation details. Use `yasl_display_caps()` to check optional features. X11 supports CPU pixel buffers, keyboard and pointer input, and clipboard transfer. @@ -67,14 +88,18 @@ Those features return their normal unsupported result. The surface spec needs no native graphics device for CPU drawing. On Cocoa, YASL creates its own Metal device for this mode. -An app that renders with Metal can supply its device through `graphics_device`. -That app submits and presents the native drawable. +An app that renders with Metal includes `<yasl/native.h>` and calls +`yasl_surface_create_native(display, &spec, device)`. During its draw callback, +`yasl_surface_get_native_frame()` returns the current Metal drawable. The app +submits and presents it, then calls `yasl_surface_present()` to record submission. The native display handle is a `wl_display *` on Wayland. It is a `Display *` on X11. 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 *`. +On Cocoa, the native display handle is `NSApplication *` and the surface handle +is `NSWindow *`. Access its view through `window.contentView`. Native getters +are declared only in `<yasl/native.h>`; handles are borrowed until destruction. ## Ownership and backend contracts @@ -104,10 +129,10 @@ On Cocoa, the native surface handle is the content `NSView *`. - 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_surface_create_native()` requires `YASL_CAP_NATIVE_GRAPHICS` (currently + Cocoa) and a non-NULL graphics device; other backends return `ENOTSUP`. Native + drawable queries are valid only for the current draw target and expire on + successful present, callback return, or surface destruction. - `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 @@ -191,7 +216,7 @@ int main(void) yasl_surface_schedule_redraw(s); while (running) { - yasl_display_dispatch(d); + yasl_display_dispatch(d, -1); struct yasl_input_event ev; while (yasl_surface_input_poll(s, &ev)) { if (ev.kind == YASL_INPUT_KEY && ev.key.action == YASL_KEY_PRESS) { |