wio

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();

    while (true) {
        wio.update();
        while (events.pop()) |event| {
            switch (event) {
                .close => return,
                .draw => {
                    // Note that on Wayland, the window might not appear until
                    // something is drawn.
                },
                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.

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

The demo directory contains a test program covering most of the API and supporting all platforms.

The examples directory contains small programs for various graphics APIs. In general these support all possible platforms, but the OpenGL example omits support for Android and WebAssembly to act as a reference for desktop-only applications.

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 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
• libxkbcommon.so.0
• libdecor-0.so.0
• 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.globals.display is the Xlib display
• Window.backend.x11.window is the Xlib window

.wayland

• wio.backend.wayland.globals.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