tiny.windowing

Overview · API · Code relationships · Verification · Audit

Overview

The package gives a program its own windows on the desktop: it opens and closes them, delivers the keyboard, mouse and gamepad input aimed at them, and shows the images the program draws, on macOS and on Linux under Wayland or X11. A program that draws its own pixels needs a window from the host system, the input events that reach that window, and a way to hand each finished image to the display. The same program code should run on each of those window systems, with the parts that differ kept out of its way, and a program that runs for hours should keep its bookkeeping storage at the size it had when the window opened.

The three systems name and deliver windows, input and pixels in different forms, so a shared API can carry only what every one of them can answer for, and code that needs one system directly needs a way to reach it. Input can arrive faster than a program reads it, and a queue whose size is fixed in advance has to decide what happens to an event that finds it full. The display takes a new image on its own schedule, so an image the program hands over may have to wait. Copying the whole image for every small change costs the bandwidth of the whole image, and a 3840 by 2160 image is about 33 MB. Every storage size has to be known before the first window opens, so an impossible size has to be refused before any window exists.

The native window systems answer these problems each in its own way: Apple's AppKit on macOS, and the Wayland and X11 display systems on Linux, each with a window that receives events and a drawing surface that receives pixels. The package keeps what those systems share: native windows, event delivery, drawing surfaces, and one implementation per platform, and it hands out each window's native surface for code that needs the platform directly.

Over those implementations the package offers one API, with one implementation per window system (backend), and on Linux it picks Wayland or X11 when a window is created, falling back to the other when the first choice is unavailable. Every store a window keeps, among them the event queue, the input state and the presentation storage, is sized from the sizes the caller passes at creation (limits), and each byte count is derived and checked before the window opens. Each poll fills the event queue afresh and the program drains it with an iterator, and an event that finds the queue full is counted and dropped, so the program can read how many it lost. Each hand-over to the display (present) names the rectangle of the image that changed, and a backend that can send only those pixels does so. Hand-overs follow the display's pace: the Wayland backend keeps an image that arrives while the program that draws the Linux desktop under Wayland (the compositor) is busy and sends it when the compositor signals for the next frame, and a backend reports when a frame reached the screen where its platform offers that report.

• region: an axis-aligned rectangle of a frame, given as an origin, a width and a height in pixels, which a caller passes to report the part of the frame that changed.

Definitions

Types and contracts

Public types and contracts.

• GamepadCapacity
• ClipboardCapacity
• InputCapacity
• EventQueueCapacity
• PresentationCapacity
• CocoaSurface
• EventIterator
• FocusEvent
• Gamepad
• GamepadAxis
• GamepadButton
• KeyEvent
• MouseButtonEvent
• MouseMoveEvent
• MouseWheelEvent
• SizeEvent
• Surface
• SurfaceExtent
• SurfaceKind
• TextInputEvent
• UnsupportedSurface
• WaylandSurface
• X11Surface
• BackendPreference
• CreateError
• CursorShape
• EventSource
• Key
• Modifier
• MouseButton
• PollError
• PresentError
• PresentRegion
• Scale
• Size
• WaylandClientIdCapacity
• WaylandComposeCapacity
• WaylandComposeLimits
• WaylandComposeScratchCapacity
• WaylandComposeScratchLimits
• WaylandDmabuf: Presents buffers another device rendered on a Wayland window, as dma-bufs with explicit synchronization.
• WaylandEventStorageCapacity
• WaylandEventStorageStatus
• WaylandGlobalCapacity
• WaylandObjectCapacity
• WaylandPresentationCapacity
• WaylandProcessEnvironmentCapacity
• WaylandProcessEnvironmentCapacityError
• WaylandProcessEnvironmentLimits
• WaylandRuntimeCapacity
• WaylandRuntimeLimits
• WaylandRuntimeStorageStatus
• WaylandSessionCapacity
• WaylandTransportCapacity
• WaylandTransportStatus
• Window
• WindowConfig
• Event

Namespaces

Public namespaces.

• surface
• event
• gamepad
• clipboard
• presentation
• input

Values and defaults

Public values and defaults.

• default_wayland_compose_limits
• default_wayland_compose_scratch_limits
• default_wayland_output_count
• wayland_dmabuf
• wayland_process_environment_capacity

Code relationships

Direct static dependencies extracted from parsed source by semantic graph analysis.

Uses: tiny.bench, tiny.css, tiny.http, tiny.hypothesis, tiny.sdfii, tiny.sys, tiny.tldr, tiny.wayland, tiny.xkb
Used by: tiny.gui

Verification

No verification records are cataloged for this module in this build.

Audit