# YASL — Yet Another Surface Library

YASL is a C desktop surface library for applications that own their renderer.
It creates windows and supplies CPU pixel targets, scale-aware geometry, queued
input, clipboard text, popups, surface drags, and optional frame pacing.
It runs on Wayland, X11, and macOS Cocoa.

A software-rendered editor, terminal, drawing tool, or custom interface can open
a window and paint pixels without creating an OpenGL context or adopting a
widget toolkit. YASL also exposes tablet pressure/tilt and IME composition.
It does not provide fonts, widgets, audio, or a graphics engine. Native handles
and Cocoa/Metal rendering are separate extensions.

**Status:** pre-release 0.1; source and ABI compatibility are not yet guaranteed.
Physical keys have portable names, committed text arrives as UTF-8, and scroll
offsets use fractional X/Y line units. Read the [application guide](docs/guide.md)
for platform capabilities and limits.

## Start here

- [Getting started](docs/getting-started.md): build, install, link, and run a window.
- [Application guide](docs/guide.md): geometry, drawing, input, ownership, and backend limits.
- [Public reference](include/yasl/yasl.h), [app runner](include/yasl/app.h), [loop](include/yasl/loop.h),
  [timing](include/yasl/timing.h), and [native extensions](include/yasl/native.h).
  Run `doxygen Doxyfile` for a searchable HTML reference in `build-docs/html`.
- [API policy](docs/api-policy.md), [migration notes](docs/migrating.md), and
  [contributing](CONTRIBUTING.md).
- [Tests, tablet example, and benchmarks](docs/testing.md).
- [IDE integration](IDE_INTEGRATION.md): step through example and window creation code with Zed's debugger.

## Build a window

Use a C23 compiler, Meson 1.6 or newer, and Ninja. Linux needs the development
packages for Wayland (`wayland-client`, `wayland-cursor`, `xkbcommon`) or X11
(`x11`, `xi`, `xkbcommon`, `xext`; optional `xrandr`). Cocoa requires macOS 14 or
newer and the system SDK, with a Metal-capable device for window drawing.

```sh
meson setup build
meson compile -C build
./build/yasl-notepad
meson test -C build --print-errorlogs
```

Linux builds automatically include backends with available dependencies. Require
one with `-Dwayland=enabled` or `-Dx11=enabled`; omit one with `disabled`. Runtime
selection chooses the native session and allows fallback, or you can request an
explicit backend with `yasl_display_spec.backend`.

Include `<yasl/app.h>` and pass application callbacks to `yasl_run()`.
The complete [hello.c](examples/hello.c) describes its window in
`yasl_app_desc.window`, lets the runner quit when it is closed, and fills every
pixel with an RGB gradient in its frame callback.

Toplevel creation sizes are logical pixels; drawing and input use device pixels.
Targets are borrowed for one frame callback. Keep durable content in application
memory; the runner handles dispatch, input polling, pacing, and cleanup.
Applications managing their own loop can use `<yasl/yasl.h>` directly. Both
workflows are explained in the application guide.

## License

[MIT](LICENSE).