diff options
| -rw-r--r-- | CONTRIBUTING.md | 27 | ||||
| -rw-r--r-- | Doxyfile | 25 | ||||
| -rw-r--r-- | LICENSE | 21 | ||||
| -rw-r--r-- | README.md | 46 | ||||
| -rw-r--r-- | docs/api-policy.md | 18 | ||||
| -rw-r--r-- | docs/doxygen_filter.py | 24 | ||||
| -rw-r--r-- | docs/examples.dox | 12 | ||||
| -rw-r--r-- | docs/getting-started.md | 77 | ||||
| -rw-r--r-- | docs/guide.md | 141 | ||||
| -rw-r--r-- | docs/testing.md | 36 |
10 files changed, 0 insertions, 427 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7e31c97..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,27 +0,0 @@ -# Contributing - -YASL is a small desktop surface/input library for application-owned loops and -renderers. Read [the guide](docs/guide.md) and [API policy](docs/api-policy.md). -Keep public C APIs direct: opaque surface pointers, plain IDs/numeric arguments, -and one tagged event. Avoid new descriptor/geometry/string/handle helper structs, -application runners, graphics engines, or hidden presentation policy. - -Portable lifetime, event ownership, validation, and rendering bridges live in -src/common. Native implementations live in src/platform/wayland, x11, and cocoa. -Private backend geometry/frame/loop types are implementation details, not installed -API. Linux desktop services live in src/platform/freedesktop; POSIX synchronization -and waiting live in src/platform/posix. Keep native handles typed in extension headers. - -Document public units, ownership, errors, thread requirements, callback timing, -and unsupported behavior. Add useful behavior coverage and examples. Run: - -```sh -meson compile -C build -meson test -C build --print-errorlogs -``` - -Changes to portable/native behavior need both Linux backends and installed shared/ -static consumers checked. Use the isolated GPU suite described in [testing](docs/testing.md). -Cocoa changes require a native macOS build/test; disclose platforms not exercised. -Do not edit generated protocol files for unrelated changes. Check exact exports and -public C/C++ compilation. Contributions use the project's MIT license. diff --git a/Doxyfile b/Doxyfile deleted file mode 100644 index 406abac..0000000 --- a/Doxyfile +++ /dev/null @@ -1,25 +0,0 @@ -PROJECT_NAME = YASL -PROJECT_BRIEF = "Desktop surfaces for application-owned rendering" -OUTPUT_DIRECTORY = build-docs -INPUT = include/yasl docs -RECURSIVE = YES -FILE_PATTERNS = *.h *.md *.dox -EXAMPLE_PATH = examples -FILTER_PATTERNS = *.md="python3 docs/doxygen_filter.py" -USE_MDFILE_AS_MAINPAGE = docs/getting-started.md -EXTRACT_ALL = NO -EXTRACT_STATIC = YES -JAVADOC_AUTOBRIEF = YES -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -PREDEFINED = YASL_API= __cplusplus -GENERATE_HTML = YES -GENERATE_LATEX = NO -SOURCE_BROWSER = YES -FULL_PATH_NAMES = NO -QUIET = YES -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_AS_ERROR = FAIL_ON_WARNINGS diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 0d0ad12..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Berke Güzel - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README.md b/README.md deleted file mode 100644 index e528220..0000000 --- a/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# YASL — Yet Another Surface Library - -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 EGL/OpenGL contexts on Linux, Vulkan window surfaces, and direct -Metal layers on macOS. -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); -``` - -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 on Linux. `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. - -**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`. - -Build with a C23 compiler, Meson 1.6+, and Ninja: - -```sh -meson setup build -meson compile -C build -./build/yasl-hello -meson test -C build --print-errorlogs -``` - -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. - -- [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 licensed; see [LICENSE](LICENSE). diff --git a/docs/api-policy.md b/docs/api-policy.md deleted file mode 100644 index f2f4d92..0000000 --- a/docs/api-policy.md +++ /dev/null @@ -1,18 +0,0 @@ -# Public API policy - -YASL is pre-release 0.1. Source and ABI compatibility are not guaranteed. Rebuild -consumers against matching installed headers/library; do not serialize public events -or assume their layout is a stable file/network format. - -Only installed include/yasl headers are public. The surface library exposes an -opaque surface and one tagged event record, with direct C arguments and ordinary -pointer/integer results. Native backend headers, geometry records, callbacks, loops, -and drawing targets under src are private even when a static archive contains them. -The shared library exports exactly the installed public declarations. - -Do not restore removed runner/frame/display APIs or compatibility aliases. Keep -rendering bridges separate from the portable surface/input core and preserve the -application's ownership of GPU resources and its loop. Public additions need clear -units, ownership, thread/callback timing, errors and unsupported behavior, useful -examples, and behavior coverage. Update the guide and test installed shared/static -consumers and exports. Changes affecting Cocoa need a native macOS build/test. diff --git a/docs/doxygen_filter.py b/docs/doxygen_filter.py deleted file mode 100644 index ed6e6e8..0000000 --- a/docs/doxygen_filter.py +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env python3 -"""Resolve repository source links to Doxygen reference/example pages. - -Markdown keeps ordinary relative links for repository and installed-document -readers. Doxygen gets @ref links so its standalone HTML has no source-tree URLs. -""" - -from pathlib import Path -import re -import sys - -text = Path(sys.argv[1]).read_text(encoding="utf-8") - - -def reference(match): - label, target = match.groups() - if target.startswith("../include/yasl/") and target.endswith(".h"): - return f"[{label}](@ref {Path(target).name})" - if target.startswith("../examples/") and target.endswith(".c"): - return f"[{label}](@ref {Path(target).name})" - return match.group(0) - - -sys.stdout.write(re.sub(r"\[([^\]]+)\]\(([^)]+)\)", reference, text)) diff --git a/docs/examples.dox b/docs/examples.dox deleted file mode 100644 index 8e9d06a..0000000 --- a/docs/examples.dox +++ /dev/null @@ -1,12 +0,0 @@ -/** @example hello.c - * A complete beginner window using CPU pixels, checked creation/presentation, - * and ordered shutdown. Run with --smoke-test to present once and exit. - */ - -/** @example simple_window.c - * Interactive pointer and tablet samples over a CPU-rendered gradient. - */ - -/** @example tablet.c - * Retained drawing content with pressure, tilt, eraser input, and scale changes. - */ diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index aeed4cd..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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, and UserNotifications -system frameworks. Use Metal or MoltenVK for GPU rendering on macOS; Cocoa does -not provide OpenGL contexts. Optional Vulkan SDK enables MoltenVK WSI. - -```sh -meson setup build -meson compile -C build -./build/yasl-hello -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. -On Linux with EGL, `./build/yasl-game` runs [game.c](../examples/game.c), which -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. diff --git a/docs/guide.md b/docs/guide.md deleted file mode 100644 index 5435370..0000000 --- a/docs/guide.md +++ /dev/null @@ -1,141 +0,0 @@ -# Surface and input guide - -## Lifetime, threads, and errors - -The first successful `yasl_surface_create` or `yasl_gl_surface_create` initializes -shared native state. Subsequent surfaces share one backend. Optional `yasl_set_app_id` -and `yasl_set_backend` configure the next initialization; they fail after initialization. -Destroying the final surface preserves shared state. `yasl_shutdown` destroys remaining -surfaces, releases the backend, and restores defaults. Release application-owned GPU -objects before their surface or shutdown. Parent destruction destroys popup descendants. - -Creation, window operations, event pumping, and shutdown use the first creation's -thread, which must be the main thread on Cocoa. GL context binding/drawing/swapping -may use a rendering thread; detach its context before destroying the window. The -application synchronizes renderer state/geometry and joins workers before shutdown. -`yasl_wake` is thread-safe and does nothing before initialization or after shutdown. - -Constructors return NULL on failure; fallible mutations return bool. Event reads -return 1 for an event, 0 for empty/timeout/wake, -1 for failure. `yasl_get_error` -returns a stable per-thread error and static description; `yasl_get_native_error` -returns supplementary native diagnostics. Success does not clear a preceding error. -Valid-object size/scale/userdata getters return ordinary values. Destroyed pointers -are invalid. Strings passed to creation and setters are copied; userdata is borrowed. - -## Events and coordinates - -`yasl_poll_event` and `yasl_wait_event` process native events and consume one shared -FIFO. No manual dispatch/flush cycle. A failed/empty read leaves output unchanged. -Wait timeout zero polls, negative waits for work, positive milliseconds bound waiting. -A wake can return zero. Polling before initialization returns zero; waiting reports -NOT_INITIALIZED. Close and quit are requests; the application decides how to respond. -Display loss is a terminal native failure; destroy resources and shut down. - -Read the union member selected by type. Events own their text through -`yasl_event_release`, independently of later polls and source destruction. Release -every successful event exactly once; numeric events need no allocation to release. -Do not duplicate event ownership by shallow copying. Event surface pointers remain -borrowed and become invalid when their surface is destroyed. Undelivered events for -a destroyed surface are canceled. Sequence orders capture by YASL, not OS causality. -Timestamps use monotonic nanoseconds; native_time states whether normalized native -sample timing was available or capture time was used. - -Creation dimensions, pointer/pen coordinates, popup placement, caret, and CSD actions -use logical content units. Fractional positions use doubles. Image dimensions, -byte stride, framebuffer size, and damage use device pixels. Query actual framebuffer -extent for swapchain/viewport sizing; scale alone need not determine integer rounding. -Request functions report acceptance, while geometry/state events report actual results. -There is no portable absolute window-position promise. State's known mask distinguishes -reported false from unavailable state fields. - -## Rendering - -GPU creation (flags zero) does not create a device, context, or software framebuffer. -One presenter attaches to each surface. Incompatible second attachments fail. - -- Vulkan: inject vkGetInstanceProcAddr, query instance extensions and flags through - the live GPU surface, create the instance, then `yasl_vulkan_create_surface`. - The application owns VkInstance/VkDevice/queues/swapchains/VkSurfaceKHR, handles - image acquisition, synchronization and recreation, and presents with Vulkan. -- Metal: `yasl_metal_layer` returns a borrowed CAMetalLayer on Cocoa. YASL owns - the native view/layer and updates its dimensions. The app sets device/pixel format, - obtains drawables, and submits/presents commands. No additional YASL present call. -- GL: `yasl_gl_surface_create` accepts title, dimensions, flags, a per-call int - key/value attribute list terminated by YASL_GL_END, and an optional sharing surface. - NULL attributes default to GL3.2 core, RGBA8, depth24/stencil8. The surface owns - its context. Bind, load procedures, set swap interval, and swap explicitly. - Available on Linux with EGL; GL API support depends on the native driver. Cocoa - reports UNSUPPORTED for GL creation; use Metal or MoltenVK. -- CPU: create with YASL_SURFACE_CPU and call `yasl_cpu_present` with premultiplied - numeric 0xAARRGGBB, width/height, byte stride, and optional damage rows containing - x/y/width/height. Extent must match current framebuffer. NULL/zero damage means full; - explicit lists must be nonempty. Initial submission and changed extent require full - images. Later patches update the retained submitted image. Source bytes are copied - before return, so the app may reuse/free them. Native uploads may copy the entire - retained image, but never unsubmitted source changes. `yasl_cpu_read_pixels` reads - that submitted CPU image, not the composited screen. - -GPU creation/presentation uses native requests directly; YASL acknowledges Wayland -configuration before external GPU submission. Native refresh events can be handled -in the ordinary loop. An optional refresh callback permits drawing while the native -window system remains in a modal resize path. It runs only during pumping and never -recursively; it may query geometry and render, but must not pump, create/destroy -surfaces, or shut down. Geometry events may not yet have been consumed, so query -current geometry there. Without a hook, CPU exposes reuse committed pixels and GPU -redraw waits for the application's loop to resume. - -## Keyboard, pen, and scrolling - -Physical YASL_KEY names identify US keyboard positions independent of layout. -Layout labels support shortcuts; committed UTF-8 TEXT is for document insertion. -Keys and text need not correspond one-to-one. Input RESET/focus loss cancels held -application input. Keep pointer and pen streams separate to avoid duplicate strokes. - -PEN events carry connection-local device/tool IDs, tool type, proximity/contact, -button transitions, coherent position and axes. Pressure is 0..1; zero does not end -contact. Tilt uses degrees -90..90; rotation uses clockwise degrees; distance is -normalized, not a physical unit. Axis validity distinguishes unavailable from zero. -Changed masks indicate native updates. Tools/axes depend on hardware and backend; -IDs do not guarantee persistent hardware serials. Pen-generated mouse duplicates -are suppressed where recognized; do not treat tool class as a multi-contact API. - -SCROLL preserves wheel-line and precise-pixel values with validity, source, phase, -and momentum metadata where supplied. Applications choose layout pixels per wheel -line. X11 supplies native wheel/smooth valuator data where available. Missing native -metadata stays explicitly unavailable instead of being inferred. - -## Text input, clipboard, popups, and drags - -Activate text input for a text control with `yasl_surface_set_text_input`. Set purpose, -caret, and copied UTF-8 surrounding text/selection/revision through direct setters. -Snapshot offsets and TEXT_EDIT replacement ranges are UTF-8 bytes; COMPOSITION is -uncommitted preedit. Apply a matching-revision edit once, update your snapshot, and -ignore/rebase stale edits. Activation generation distinguishes controls. Ordinary key -text remains TEXT. Never insert preedit as committed document text. Wayland requires -text-input-v3 for native IME; absence is reported as unsupported. Cocoa translates -native UTF-16 replacement/deletion to snapshot UTF-8 ranges. X11 XIM supplies ordinary -text/preedit but cannot promise surrounding-text replacement support. - -Clipboard set copies UTF-8; read returns a nonzero request ID and later CLIPBOARD -completion with OK, UNAVAILABLE, or FAILED. Empty successful text is distinct from -failure. Destroying the target cancels transfer and delivery. Primary selection stays -independent and reports unsupported where unavailable. Linux external transfers time -out after 30 seconds; X11 currently lacks INCR for large transfers. File drops carry -URI-list text; `yasl_drop_next_path` decodes supported local paths into caller buffers. - -Popup arguments use logical parent anchor coordinates, anchor/gravity directions, -and flip/slide/resize constraint bits. Popup size includes its content. Destroying a -parent retires descendants too. Native grabs, CSD moves/resizes, menus, and surface -drags require a live triggering press event; unsupported/expired input fails explicitly. -Surface drags support application tab/window carry; they are not an arbitrary MIME -source API. Check operation results even when feature bits advertise support. - -## Backend limits - -Wayland support varies by compositor protocols; no portable absolute placement or -minimized-state query is assumed. X11 currently reports unit scale and lacks an -implemented relative-pointer lock. Cocoa requires macOS 14+; native Metal/GL and -Objective-C paths require validation on macOS. EGL/wayland-egl and Vulkan SDK support -are independently optional at build time. Feature bits describe implementation/ -server support, not guaranteed permission or attached hardware. The current work was -compiled and tested on Linux; macOS validation remains a separate required check. diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index ce2082f..0000000 --- a/docs/testing.md +++ /dev/null @@ -1,36 +0,0 @@ -# Tests - -```sh -meson setup build -meson compile -C build -meson test -C build --print-errorlogs -``` - -Tests cover public static/shared C and C++11 consumers, exact shared exports, -queue ownership/order/destruction, UTF-8, GL attributes, private native event loops, -clipboard, IME editing, pointer/pen coherence, cursor, and popup positioning. Native -unit fixtures deliberately use private implementation headers; applications must use -installed public headers. - -For private Linux display servers and actual GPU presentation, install Weston, -Xwayland, EGL/wayland-egl, and Vulkan/Mesa software drivers, then: - -```sh -meson configure build -Dintegration_tests=true -meson compile -C build -meson test -C build --print-errorlogs -``` - -The integration harness starts its own headless GL Weston and Xwayland, runs public -surface ownership/CPU damage/wakeup/refresh checks, GL drawing/readback/context-sharing/ -resize, Vulkan swapchain clear/present, and example smoke tests. It selects Mesa -software rendering and Lavapipe when available. It needs permission to create local -Unix sockets. A sandbox blocking those sockets is not a backend test result. - -`-Dx11_tablet_tests=true` additionally uses Xorg dummy/inputtest drivers for pen input -without physical hardware. These are separate from the compositor-free native unit -fixtures. Cocoa integration tests run only on macOS and need the native SDK/display. -Linux results do not validate Cocoa compilation or runtime. - -For memory/undefined-behavior checks use a separate build with `-Db_sanitize=address,undefined` -and run the same suites. Keep sanitizer builds isolated from the normal build. |