wio

This is a fork. The original is ypsvlq/wio. The pipit branch adds what Pipit needs, a music player that draws its own title bar and runs once per session:

• CreateWindowOptions.decorations, which when false asks for a window with no title bar or borders: on Wayland a plain xdg-shell toplevel, declining a compositor's own frame through xdg-decoration where one is offered, and Motif hints saying so on X11. libdecor is left for windows that want decorations, and opened only when one does — a window without them never loads it, or the toolkit its plugins bring (GTK, cairo, pango). The xdg-shell bindings are generated by zig-wayland from the protocol XML of the wayland and wayland-protocols releases, fetched as dependencies, and they link libwayland-client rather than opening it;
• Window.beginMove and Window.beginResize, which hand the pointer to the system to move or resize the window from a button press — through the toplevel or libdecor on Wayland and _NET_WM_MOVERESIZE on X11;
• Window.showWindowMenu, which opens the menu a right click on a title bar would — through the toplevel or libdecor on Wayland and GTK's _GTK_SHOW_WINDOW_MENU on X11;
• Window.activate, which brings the window forward for another launch of the same application — with the launcher's xdg_activation_v1 token on Wayland, and EWMH's _NET_ACTIVE_WINDOW on X11;
• Window.setMinSize, the smallest the window may be resized to — the toplevel's minimum size on Wayland, WM_NORMAL_HINTS on X11;
• on Wayland, scroll_vertical and scroll_horizontal counted in clicks of the wheel, as they are on X11 and Windows, from axis_value120, rather than in the compositor's surface distance — ten times as much in mutter. A touchpad's distance is divided by ten to match;
• on Wayland, the keyboard through zig-xkb rather than libxkbcommon: the compositor's keymap, the modifier state, and Compose sequences, in Zig. The layout the compositor says is in use is followed, so a second layout types its own characters. A key repeats only if the keymap says it does, and a Compose sequence that makes a string types all of it. The Compose sequences come from the X locale directory zig-xkb builds from libX11's release, which wio passes on as the named lazy path x11_locale for the program to install as share/X11/locale.

On other platforms the first three do nothing yet, and activate is requestAttention.

The branch builds with Zig 0.17.0. The last of it to build with Zig 0.16 is tagged v0.1.0 and kept on the zig-0.16 branch.

main is the upstream commit the branch starts from. The fork lives at https://git.jcollie.dev/jeff/wio, on Tangled at https://tangled.org/jcollie.dev/wio, and on Radicle as rad:z2VkMRt5Pv3LsuaVUNcdWhVBvDNp8 (rad clone rad:z2VkMRt5Pv3LsuaVUNcdWhVBvDNp8).

wio is a platform abstraction library, providing:

• window management and events
• clipboard access
• alert dialogs
• joystick input
• audio
• software framebuffer
• OpenGL context creation
• Vulkan WSI

Minimal example

const std = @import("std");
const wio = @import("wio");

pub fn main(init: std.process.Init) !void {
    try wio.init(.{
        .allocator = init.gpa,
        .io = init.io,
        .eventFn = wio.EventQueue.eventFn,
    });
    defer wio.deinit();

    var events: wio.EventQueue = .empty;
    defer events.deinit();

    var window = try wio.Window.create(.{ .event_fn_data = &events });
    defer window.destroy();

    var framebuffer = try window.createFramebuffer(.{ .width = 1, .height = 1 });
    defer framebuffer.destroy();
    framebuffer.setPixel(0, 0, 0xF7A41D);

    while (true) {
        wio.update();
        while (events.pop()) |event| {
            switch (event) {
                .close => return,
                .draw => window.presentFramebuffer(&framebuffer),
                else => {},
            }
        }
    }
}

Getting started

wio supports the latest Zig release, but compatibility with Zig master is maintained when possible.

The public API can be browsed in src/wio.zig.

The demo directory contains a test program which covers most functionality and uses OpenGL.

The examples directory contains small programs using other rendering APIs.

By default, only a subset of the API is available. The following build options enable additional features:

• enable_drop
• enable_framebuffer
• enable_opengl
• enable_vulkan
• enable_audio
• enable_joystick

Platform support

Actively tested:

• Windows
• macOS (10.13+)
• Linux
• Android (API 26+ / Android 8 and up)
• WebAssembly

Not actively tested, but most code is shared with Linux:

• OpenBSD
• NetBSD
• FreeBSD
• DragonFlyBSD
• illumos

Not actively tested:

• Haiku

API support

The joystick API is not currently implemented for Android, OpenBSD, NetBSD, FreeBSD, DragonFlyBSD, or illumos.

The audio API is not currently implemented for NetBSD, FreeBSD, DragonFlyBSD, or illumos.

Platform notes

Windows

wio embeds an application manifest by default. To use a custom manifest, set the win32_manifest build option to false.

If drag-and-drop or audio support is enabled, wio calls OleInitialize.

macOS

An application bundle is provided in demo/wio.app, which can be adapted by changing the CFBundleExecutable and CFBundleName values in Info.plist.

Unix

messageBox is implemented by spawning kdialog or zenity.

openUri is implemented by spawning xdg-open.

Unix-like systems support different backends in the same executable. By default all backends are enabled, the unix_backends build option can be used to limit the choices.

When building a project that uses wio, passing -fsys=wio to zig build will link libraries explicitly (rather than using dlopen).

To assist with packaging your project, it is recommended to expose unix_backends in your build script and document -fsys=wio.

The following libraries are loaded for the X11 backend:

• libX11.so.6
• libXrandr.so.2
• libXcursor.so.1
• libGL.so.1 (if OpenGL is enabled)
• libXext.so.6 (if Vulkan is enabled, as a workaround for this issue)

The following libraries are loaded for the Wayland backend:

• libwayland-client.so.0
• libdecor-0.so.0 (only when a window asks for decorations)
• libwayland-egl.so.1 (if OpenGL is enabled)
• libEGL.so.1 (if OpenGL is enabled)

The following libraries are loaded under Linux:

• libudev.so.1 (if joysticks are enabled)
• libpulse.so.0 (if audio is enabled)

Android

To ensure the entry point is exported from the shared library, the root source file should contain comptime { _ = wio; } at the top level.

demo/build.zig is an example of a build script supporting Android.

WebAssembly

If OpenGL is enabled, wio imports createContext and makeContextCurrent from the gl module. wio.glGetProcAddress always returns null.

If audio is enabled, memory must be imported and shared.

A basic WebAssembly example is provided in examples/framebuffer, whilst the demo is more advanced and includes audio support.

WebGL 1 bindings are provided in demo/wasm.js.

Platform-specific API

The following variables and fields may be considered part of the public API for a given platform:

Windows

• Window.backend.window is the Win32 HWND

macOS

• Window.backend.window is the AppKit NSWindow

Unix

wio.backend.active is an enum variable specifying the backend in use:

.x11

• wio.backend.x11.display is the Xlib display
• Window.backend.x11.window is the Xlib window

.wayland

• wio.backend.wayland.display is the Wayland wl_display
• Window.backend.wayland.surface is the Wayland wl_surface

WebAssembly

• Window.backend.id is the index into the JavaScript window array

Haiku

• Window.backend.window is the InterfaceKit BWindow