diff options
Diffstat (limited to 'docs/guide.md')
| -rw-r--r-- | docs/guide.md | 141 |
1 files changed, 0 insertions, 141 deletions
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. |