lib/windowing/src/root.zig
daab053ee43316e1809a84551d573ddd1e5bf3d2
1 //! The package gives a program its own windows on the desktop: it opens and
2 //! closes them, delivers the keyboard, mouse and gamepad input aimed at them,
3 //! and shows the images the program draws, on macOS and on Linux under Wayland
4 //! or X11. A program that draws its own pixels needs a window from the host
5 //! system, the input events that reach that window, and a way to hand each
6 //! finished image to the display. The same program code should run on each of
7 //! those window systems, with the parts that differ kept out of its way, and a
8 //! program that runs for hours should keep its bookkeeping storage at the size
9 //! it had when the window opened.
10 //!
11 //! The three systems name and deliver windows, input and pixels in different
12 //! forms, so a shared API can carry only what every one of them can answer for,
13 //! and code that needs one system directly needs a way to reach it. Input can
14 //! arrive faster than a program reads it, and a queue whose size is fixed in
15 //! advance has to decide what happens to an event that finds it full. The
16 //! display takes a new image on its own schedule, so an image the program hands
17 //! over may have to wait. Copying the whole image for every small change costs
18 //! the bandwidth of the whole image, and a 3840 by 2160 image is about 33 MB.
19 //! Every storage size has to be known before the first window opens, so an
20 //! impossible size has to be refused before any window exists.
21 //!
22 //! The native window systems answer these problems each in its own way: Apple's
23 //! [AppKit](https://developer.apple.com/documentation/appkit) on macOS, and the
24 //! [Wayland](https://wayland.freedesktop.org/) and [X11](https://www.x.org/)
25 //! display systems on Linux, each with a window that receives events and a
26 //! drawing surface that receives pixels. The package keeps what those systems
27 //! share: native windows, event delivery, drawing surfaces, and one
28 //! implementation per platform, and it hands out each window's native surface
29 //! for code that needs the platform directly.
30 //!
31 //! Over those implementations the package offers one API, with one
32 //! implementation per window system (*backend*), and on Linux it picks Wayland
33 //! or X11 when a window is created, falling back to the other when the first
34 //! choice is unavailable. Every store a window keeps, among them the event
35 //! queue, the input state and the presentation storage, is sized from the sizes
36 //! the caller passes at creation (*limits*), and each byte count is derived and
37 //! checked before the window opens. Each poll fills the event queue afresh and
38 //! the program drains it with an iterator, and an event that finds the queue
39 //! full is counted and dropped, so the program can read how many it lost. Each
40 //! hand-over to the display (*present*) names the rectangle of the image that
41 //! changed, and a backend that can send only those pixels does so. Hand-overs
42 //! follow the display's pace: the Wayland backend keeps an image that arrives
43 //! while the program that draws the Linux desktop under Wayland (the
44 //! compositor) is busy and sends it when the compositor signals for the next
45 //! frame, and a backend reports when a frame reached the screen where its
46 //! platform offers that report.
47 //!
48 //! - *region*: an axis-aligned rectangle of a frame, given as an origin, a
49 //! width and a height in pixels, which a caller passes to report the part of
50 //! the frame that changed.
51
52 const native_wayland = @import("wayland");
53 const native_xkb = @import("xkb");
54
55 const window = @import("window.zig");
56 pub const event = @import("event.zig");
57 const key = @import("key.zig");
58 const mouse = @import("mouse.zig");
59 const modifier = @import("modifier.zig");
60 const cursor = @import("cursor.zig");
61 const clipboard_module = @import("clipboard.zig");
62 const gamepad_module = @import("gamepad.zig");
63 const input_module = @import("input.zig");
64 const config = @import("config.zig");
65 const wayland = @import("wayland/root.zig");
66 const surface_module = @import("surface.zig");
67 pub const presentation = @import("presentation.zig");
68
69 pub const Window = window.Window;
70 pub const Size = window.Size;
71 pub const Scale = window.Scale;
72 pub const EventSource = window.EventSource;
73 pub const PresentRegion = window.PresentRegion;
74 pub const Event = event.Event;
75 pub const EventIterator = event.EventIterator;
76 pub const KeyEvent = event.KeyEvent;
77 pub const TextInputEvent = event.TextInputEvent;
78 pub const MouseButtonEvent = event.MouseButtonEvent;
79 pub const MouseMoveEvent = event.MouseMoveEvent;
80 pub const MouseWheelEvent = event.MouseWheelEvent;
81 pub const SizeEvent = event.SizeEvent;
82 pub const FocusEvent = event.FocusEvent;
83 pub const Key = key.Key;
84 pub const MouseButton = mouse.MouseButton;
85 pub const Modifier = modifier.Modifier;
86 pub const CursorShape = cursor.CursorShape;
87 pub const clipboard = clipboard_module;
88 pub const input = input_module;
89 pub const gamepad = gamepad_module;
90 pub const surface = surface_module;
91 pub const Gamepad = gamepad_module.Gamepad;
92 pub const GamepadButton = gamepad_module.Button;
93 pub const GamepadAxis = gamepad_module.Axis;
94 pub const WindowConfig = config.WindowConfig;
95 pub const BackendPreference = config.BackendPreference;
96 pub const default_wayland_compose_limits = config.default_wayland_compose_limits;
97 pub const default_wayland_compose_scratch_limits =
98 config.default_wayland_compose_scratch_limits;
99 pub const default_wayland_output_count = config.default_wayland_output_count;
100 pub const Surface = surface_module.Surface;
101 pub const SurfaceKind = surface_module.Kind;
102 pub const SurfaceExtent = surface_module.Extent;
103 pub const WaylandSurface = surface_module.Wayland;
104 pub const WaylandDmabuf = wayland.DmabufSurface;
105 pub const wayland_dmabuf = wayland.present.dmabuf;
106 pub const X11Surface = surface_module.X11;
107 pub const CocoaSurface = surface_module.Cocoa;
108 pub const UnsupportedSurface = surface_module.Unsupported;
109 pub const ClipboardCapacity = clipboard_module.Capacity;
110 pub const EventQueueCapacity = event.Capacity;
111 pub const GamepadCapacity = gamepad_module.Capacity;
112 pub const InputCapacity = input_module.Capacity;
113 pub const PresentationCapacity = presentation.Capacity;
114 pub const WaylandSessionCapacity = wayland.session.Capacity;
115 pub const WaylandPresentationCapacity = wayland.presentation.Capacity;
116 pub const WaylandRuntimeLimits = native_wayland.runtime.Limits;
117 pub const WaylandRuntimeCapacity = native_wayland.runtime.Capacity;
118 pub const WaylandRuntimeStorageStatus = native_wayland.runtime.StorageStatus;
119 pub const WaylandComposeLimits = native_xkb.compose.Limits;
120 pub const WaylandComposeCapacity = native_xkb.compose.Capacity;
121 pub const WaylandComposeScratchLimits = native_xkb.compose.ScratchLimits;
122 pub const WaylandComposeScratchCapacity = native_xkb.compose.ScratchCapacity;
123 pub const WaylandClientIdCapacity = native_wayland.ClientIdCapacity;
124 pub const WaylandObjectCapacity = native_wayland.runtime.ObjectCapacity;
125 pub const WaylandGlobalCapacity = native_wayland.runtime.GlobalCapacity;
126 pub const WaylandEventStorageCapacity = native_wayland.runtime.EventStorageCapacity;
127 pub const WaylandEventStorageStatus = native_wayland.runtime.EventStorageStatus;
128 pub const WaylandTransportCapacity = native_wayland.TransportCapacity;
129 pub const WaylandTransportStatus = native_wayland.TransportStatus;
130 pub const WaylandProcessEnvironmentLimits = native_wayland.ProcessEnvironmentLimits;
131 pub const WaylandProcessEnvironmentCapacity = native_wayland.ProcessEnvironmentCapacity;
132 pub const WaylandProcessEnvironmentCapacityError =
133 native_wayland.ProcessEnvironmentCapacityError;
134 pub const wayland_process_environment_capacity =
135 native_wayland.process_environment_capacity;
136
137 pub const CreateError = window.CreateError;
138 pub const PollError = window.PollError;
139 pub const PresentError = window.PresentError;