# Getting started

YASL creates desktop surfaces and delivers queued input. You own the event loop,
renderer, graphics device/context use, and application lifetime.

Build with a C23 compiler, Meson 1.6+, and Ninja. Linux backend dependencies are
wayland-client, wayland-cursor, xkbcommon, or x11, xi, xext, xkbcommon (optional
xrandr). Optional egl and wayland-egl enable GL contexts; Vulkan SDK development
files enable the Vulkan bridge. Optional dbus-1 enables Linux desktop services.
Cocoa requires macOS 14+ and the AppKit, Metal, QuartzCore, OpenGL, and
UserNotifications system frameworks. Optional Vulkan SDK enables MoltenVK WSI.

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

Backend options `-Dwayland=enabled|disabled|auto`, `-Dx11=...`, and `-Ddbus=...`
control dependency selection. At least one window backend must be built. Runtime
AUTO selects the native session and falls back to another built Linux backend.
For an explicit choice call `yasl_set_backend` before creating any surface.

## A window

```c
#include <yasl/yasl.h>

int main(void)
{
    yasl_surface *s = yasl_surface_create("Example", 800, 600, 0);
    if (!s) return 1;
    /* Attach a GPU renderer here and draw on each REFRESH. */
    yasl_event event;
    while (yasl_wait_event(&event, -1) >= 0 &&
           event.type != YASL_EVENT_CLOSE && event.type != YASL_EVENT_QUIT) {
    }
    /* Destroy GPU objects before shutting down. */
    yasl_shutdown();
    return 0;
}
```

The first creation initializes a shared backend. More windows use that backend;
there is no public display/context object. Closing the final window does not
implicitly terminate the application or reset configuration. `yasl_shutdown`
releases shared resources and restores defaults.

If the Wayland compositor restarts, windows stay open: YASL sends DISPLAY_LOST,
reconnects, and sends DISPLAY_RESTORED. CPU windows need nothing; GPU renderers drop
their Vulkan surfaces and GL objects on loss and rebuild them on restore.

[hello.c](../examples/hello.c) draws into a CPU surface's pixel buffer on every REFRESH.
[game.c](../examples/game.c) creates a GL context, binds it, loads procedures, draws,
swaps, and rebinds the context after a compositor restart. [tablet.c](../examples/tablet.c) retains a canvas
and draws pressure-sensitive pen/eraser strokes. [notepad.c](../examples/notepad.c)
uses a worker queue, wakeups, clipboard, IME, and its own blink deadline.

## Link and install

```sh
meson setup build --prefix=/usr/local --libdir=lib
meson compile -C build
meson install -C build
cc -std=c23 examples/hello.c -o hello $(pkg-config --cflags --libs yasl)
```

Use a writable prefix. For a custom prefix configure PKG_CONFIG_PATH and the
runtime library search path. Static consumers use `pkg-config --static --libs yasl`.
Public headers also compile as C++11. Native headers and the Vulkan header are
installed only when their respective support is built.

See the [guide](guide.md) for geometry, event lifetime, GPU ownership, input, and
backend limits. `doxygen Doxyfile` builds the reference in build-docs/html.