diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 83 |
1 files changed, 31 insertions, 52 deletions
@@ -1,66 +1,45 @@ # 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 +YASL is a small C desktop surface and input library for applications that own +their event loop and renderer. It supports Wayland, X11, and Cocoa, with CPU +images, optional OpenGL contexts, Vulkan window surfaces, and direct Metal layers. +Pen input includes tool identity, proximity/contact, pressure, tilt, and available +rotation/distance/tangential/wheel axes. It also supplies IME composition/editing, +clipboard text, popups, file drops, and surface drags. + +The first surface initializes a shared backend. Surface operations use ordinary +arguments; there are no public display objects, creation descriptors, frame +objects, point/size/string wrappers, or mandatory application runner. + +```c +yasl_surface *surface = yasl_surface_create("Example", 800, 600, 0); +``` -- [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 redesign](docs/api-redesign.md): queue, frame, ownership, and backend contracts. -- [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. +Flags zero creates a GPU window without choosing a graphics API. The application +attaches a Vulkan surface or Metal layer, or uses `yasl_gl_surface_create` to create +an OpenGL window/context. `YASL_SURFACE_CPU` gives the window a pixel buffer: draw into +`yasl_cpu_pixels` and call `yasl_cpu_present`. Native handles are available through typed extension headers. -## Build a window +**Status:** pre-release 0.1; source and ABI compatibility are not promised. +Use matching headers and library. Supported operations depend on the backend, +server, and optional dependencies; check results and `yasl_get_error`. -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`). Optional `dbus-1` enables -desktop notifications and appearance queries on Linux. Cocoa requires macOS 14 or -newer and the system SDK, with a Metal-capable device for window drawing. +Build with a C23 compiler, Meson 1.6+, and Ninja: ```sh meson setup build meson compile -C build -./build/yasl-notepad +./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/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. -Both loop styles consume one display event FIFO and receive `yasl_frame`; -`yasl_frame_present()` submits its target. 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. +Linux needs Wayland or X11 development packages; EGL and wayland-egl enable GL, +and the Vulkan SDK enables its typed bridge. Cocoa needs macOS 14+ and its SDK. -## License +- [Getting started](docs/getting-started.md): creation, linking, and rendering. +- [Application guide](docs/guide.md): ownership, events, GPUs, pen, and backend limits. +- [Testing](docs/testing.md): unit tests and isolated GPU/backend tests. +- [API policy](docs/api-policy.md) and [contributing](CONTRIBUTING.md). +- Public headers live in [include/yasl](include/yasl); examples live in [examples](examples). -[MIT](LICENSE). +MIT licensed; see [LICENSE](LICENSE). |