github.com/rajveermalviya/gamen@v0.1.2-0.20220930195403-9be15877c1aa/README.md (about) 1 # gamen 2 3 [](https://pkg.go.dev/github.com/rajveermalviya/gamen) 4 [](https://matrix.to/#/#gamen:matrix.org) 5 6 `gamen` is cross-platform GUI window creation and management library in Go. It natively supports Windows, Linux, Android and Web. on Linux both X11 (via xcb) and Wayland are supported. 7 8 `gamen` provides consistent api for creating and managing GUI windows across different platforms. `gamen` also lets you handle events generated by platform window via callbacks. `gamen` is fairly low level, it provides platform native window 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`](https://github.com/rajveermalviya/go-webgpu) or similar. 9 10 `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. 11 12 ## usage 13 14 ```go 15 package main 16 17 import ( 18 "runtime" 19 20 "github.com/rajveermalviya/gamen/display" 21 ) 22 23 func init() { 24 runtime.LockOSThread() 25 } 26 27 func main() { 28 d, err := display.NewDisplay() 29 if err != nil { 30 panic(err) 31 } 32 defer d.Destroy() 33 34 w, err := display.NewWindow(d) 35 if err != nil { 36 panic(err) 37 } 38 defer w.Destroy() 39 40 w.SetCloseRequestedCallback(func() { d.Destroy() }) 41 42 for { 43 if !d.Poll() { 44 break 45 } 46 47 // render() 48 } 49 } 50 ``` 51 52 check out more examples under [`examples/`](./examples/) dir 53 54 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) 55 56 ## dependencies 57 58 ### windows 59 60 windows (win32) backend **does not** use CGO, i.e **does not** require a C toolchain, only Go compiler is enough 61 62 ### linux 63 64 resulting binaries shouldn't require any dependency to be installed by the users. Even developers don't need to install any distro packages (it just works!), because required headers are vendored and all libraries are dynamically loaded. 65 66 ### android 67 68 android backend uses [`game-activity`](https://developer.android.com/games/agdk/game-activity). 69 70 [`tsukuru`](https://github.com/rajveermalviya/tsukuru) should be used to help with dependency resolution and building the android app. 71 72 ```shell 73 # make sure you have android sdk installed 74 # connect your device and setup adb connection / run android emulator 75 76 go install github.com/rajveermalviya/tsukuru/cmd/tsukuru@latest 77 78 tsukuru run apk ./examples/hello 79 ``` 80 81 ### web 82 83 web backend uses `syscall/js` package. 84 85 [`tsukuru`](https://github.com/rajveermalviya/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. 86 87 ```shell 88 go install github.com/rajveermalviya/tsukuru/cmd/tsukuru@latest 89 90 tsukuru run wasm ./examples/hello 91 ``` 92 93 ## features 94 95 an incomplete list of features in no particular order that are supported or that we want to support but aren't currently. 96 97 | feature | win32 | xcb | wayland | android | web | 98 | ------------------------------ | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | 99 | window initialization | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 100 | handles for OpenGL init | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 101 | handles for Vulkan WSI | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 102 | show window with decorations | :heavy_check_mark: | :heavy_check_mark: | :exclamation: [#2] | :heavy_check_mark: | **N/A** | 103 | window decorations toggle | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | **N/A** | 104 | window resizing events | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | 105 | resize window programmatically | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | **N/A** | 106 | window transparency | :x: | :x: | :x: | :x: | :x: | 107 | window maximization toggle | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | **N/A** | 108 | window minimization | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | **N/A** | 109 | window minimum size | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | **N/A** | 110 | window maximum size | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | **N/A** | 111 | fullscreen toggle | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 112 | HiDPI support | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 113 | popups | :x: | :x: | :x: | **N/A** | **N/A** | 114 | monitor list | :x: | :x: | :x: | :x: | :x: | 115 | video mode query | :x: | :x: | :x: | :x: | :x: | 116 | mouse events | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | :heavy_check_mark: | 117 | cursor locking | :x: | :x: | :x: | :x: | :x: | 118 | cursor confining | :x: | :x: | :x: | :x: | :x: | 119 | cursor icon | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | :heavy_check_mark: | 120 | cursor hittest | :x: | :x: | :x: | **N/A** | :x: | 121 | touch events | :x: | :x: | :x: | :heavy_check_mark: | :x: | 122 | keyboard events | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 123 | drag window with cursor | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | **N/A** | **N/A** | 124 | drag & drop | :x: | :x: | :x: | **N/A** | :x: | 125 | raw device events | :x: | :x: | :x: | :x: | :x: | 126 | gamepad/joystick events | :x: | :x: | :x: | :x: | :x: | 127 | ime | :x: | :x: | :x: | :x: | :x: | 128 | clipboard | :x: | :x: | :x: | :x: | :x: | 129 | theme change events | :x: | :x: | :x: | :x: | :x: | 130 131 [#2]: https://github.com/rajveermalviya/gamen/issues/2 132 133 (as you can see there are many :x:s so any help will be greatly appreciated) 134 135 Note: for macos/ios support see [#1](https://github.com/rajveermalviya/gamen/issues/1) 136 137 ## contact 138 139 join [matrix room](https://matrix.to/#/#gamen:matrix.org) 140 141 ## thanks 142 143 `gamen`'s api is a mix of glfw and winit and some terminologies from Wayland. 144 145 - glfw - https://github.com/glfw/glfw 146 - winit - https://github.com/rust-windowing/winit