gamen

README

gamen

gamen is cross-platform windowing library in Go. It natively supports Windows, Linux, Android and Web. on Linux both X11 (via xcb) and Wayland are supported.

gamen provides api for creating and handling windows. It also lets you handle events generated by platform window via callbacks. It is fairly low level, it provides native handles for graphics APIs like OpenGL and Vulkan to initialize from, gamen by itself doesn't provide you a drawing primitive you have to use a library like go-webgpu or similar.

gamen has a callback based api for handling events i.e it doesn't do queueing (except for web backend) by itself. Because most of the backends already do internal queueing of events, doing it again inside the library can introduce unnecessary latency. Also this keep api flexible, a separate library can introduce event queue on top of gamen for easier developer experience.

usage

package main

import (
	"runtime"

	"github.com/rajveermalviya/gamen/display"
)

func init() {
	runtime.LockOSThread()
}

func main() {
	d, err := display.NewDisplay()
	if err != nil {
		panic(err)
	}
	defer d.Destroy()

	w, err := display.NewWindow(d)
	if err != nil {
		panic(err)
	}
	defer w.Destroy()

	w.SetCloseRequestedCallback(func() { d.Destroy() })

	for {
		// render here

		if !d.Wait() {
			break
		}
	}
}

check out more examples under examples/ dir

examples wgpu_poll and wgpu_wait shows how to use the event loop for a Game and a GUI respectively. Though an ideal client will switch between Poll and Wait. (GUI temporarily showing an animation)

dependencies

windows

windows (win32) backend does not use CGO, i.e does not require a C toolchain, only Go compiler is enough

linux

resulting binaries shouldn't require any dependency to be installed by the users. but developers will need some devel packages.

fedora

sudo dnf install wayland-devel libX11-devel libXcursor-devel libxkbcommon-x11-devel xcb-util-image-devel xcb-util-wm-devel

ubuntu

sudo apt install libwayland-dev libxkbcommon-x11-dev libx11-xcb-dev libxcb-randr0-dev libxcb-xinput-dev libxcb-icccm4-dev libxcursor-dev libxcb-image0-dev

android

android backend uses game-activity.

tsukuru should be used to help with dependency resolution and building the android app.

# make sure you have android sdk installed
# connect your device and setup adb connection / run android emulator

go install github.com/rajveermalviya/tsukuru@latest

tsukuru run apk ./examples/hello

web

web backend uses syscall/js package.

tsukuru can be used to help with automatically building wasm and copying wasm_exec.js & wasm_exec.html from $GOROOT to a directory and spinning up a local file server for you.

go install github.com/rajveermalviya/tsukuru@latest

tsukuru run wasm ./examples/hello

features

an incomplete list of features in no particular order that are supported or that we want to support but aren't currently.

feature	win32	xcb	wayland	android	web
window initialization	✔	✔	✔	✔	✔
handles for OpenGL init	✔	✔	✔	✔	✔
handles for Vulkan WSI	✔	✔	✔	✔	✔
show window with decorations	✔	✔	❗ #2	✔	N/A
window decorations toggle	✔	✔	✔	❌	N/A
window resizing events	✔	✔	✔	✔	N/A
resize window programmatically	✔	✔	✔	N/A	N/A
window transparency	❌	❌	❌	❌	❌
window maximization toggle	✔	✔	✔	N/A	N/A
window minimization	✔	✔	✔	N/A	N/A
window minimum size	✔	✔	✔	N/A	N/A
window maximum size	✔	✔	✔	N/A	N/A
fullscreen toggle	✔	✔	✔	✔	✔
HiDPI support	❌	❌	✔	✔	✔
popups	❌	❌	❌	N/A	N/A
monitor list	❌	❌	❌	❌	❌
video mode query	❌	❌	❌	❌	❌
mouse events	✔	✔	✔	N/A	✔
cursor locking	❌	❌	❌	❌	❌
cursor confining	❌	❌	❌	❌	❌
cursor icon	✔	✔	✔	N/A	✔
cursor hittest	❌	❌	❌	N/A	❌
touch events	❌	❌	❌	✔	❌
keyboard events	✔	✔	✔	✔	✔
drag window with cursor	✔	✔	✔	N/A	N/A
drag & drop	❌	❌	❌	N/A	❌
raw device events	❌	❌	❌	❌	❌
gamepad/joystick events	❌	❌	❌	❌	❌
ime	❌	❌	❌	❌	❌
clipboard	❌	❌	❌	❌	❌
theme change events	❌	❌	❌	❌	❌

(as you can see there are many ❌s so any help will be greatly appreciated)

Note: for macos/ios support see #1

contact

join matrix room

thanks

gamen's api is a mix of glfw and winit and some terminologies from Wayland.

• glfw - https://github.com/glfw/glfw
• winit - https://github.com/rust-windowing/winit