1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
# 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
in its frame callback:
```c
static void draw(void *ud, struct yasl_surface *surface, struct yasl_frame_context *frame)
{
(void)ud;
size_t count = (size_t)frame->size.x * frame->size.y;
for (size_t i = 0; i < count; i++)
frame->cpu.pixels[i] = 0xff306090;
if (!yasl_frame_present_cpu(frame, NULL, 0))
yasl_surface_destroy(surface);
}
```
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).
|
