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
|
# 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), [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).
## 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-hello
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/yasl.h>` for the core. The complete [hello.c](examples/hello.c)
handles creation failures, drawing, dispatch, input draining, and cleanup.
Its drawing callback fills every pixel before presenting:
```c
static void draw(struct yasl_surface *surface, struct yasl_frame *frame, void *ud)
{
(void)ud;
size_t count = (size_t)frame->target.size.x * frame->target.size.y;
for (size_t i = 0; i < count; i++)
frame->target.pixels[i] = 0xff306090;
struct yasl_damage_list damage = {.n = -1};
if (!yasl_surface_present(surface, &frame->target, &damage)) {
/* Arrange application error handling after returning. */
}
}
```
Toplevel creation sizes are logical pixels; drawing and input use device pixels.
Targets are borrowed for one draw callback. Keep durable content in application
memory, dispatch events, drain input queues, then flush scheduled drawing. These
rules are explained with examples in the application guide.
## License
[MIT](LICENSE).
|
