diff options
Diffstat (limited to 'docs')
| -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 |
6 files changed, 0 insertions, 308 deletions
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. |