KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

wio

★ 128 Open GitHub ↗

windowed i/o

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

```zig
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][1].

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

The [examples][3] 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 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][4] 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][5], 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][6])

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][7] 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][8], whilst
the [demo][2] is more advanced and includes audio support.

WebGL 1 bindings are provided in [demo/wasm.js][9].

## 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`

[1]: https://github.com/ypsvlq/wio/blob/master/src/wio.zig
[2]: https://github.com/ypsvlq/wio/tree/master/demo
[3]: https://github.com/ypsvlq/wio/tree/master/examples
[4]: https://learn.microsoft.com/en-us/windows/win32/sbscs/application-manifests
[5]: https://github.com/ypsvlq/wio/tree/master/demo/wio.app
[6]: https://gitlab.freedesktop.org/xorg/lib/libxext/-/work_items/3
[7]: https://github.com/ypsvlq/wio/blob/master/demo/build.zig
[8]: https://github.com/ypsvlq/wio/tree/master/examples/framebuffer
[9]: https://github.com/ypsvlq/wio/blob/master/demo/wasm.js

wio

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README