3 releases (breaking)
0.4.0 | Jun 3, 2023 |
---|---|
0.2.0 | Sep 8, 2022 |
0.1.0 | Aug 25, 2022 |
#59 in #input-event
37 downloads per month
Used in 3 crates
26KB
173 lines
Egui Backend
egui
is an immediate mode gui library which can be embedded into existing framworks/game engines. The library basically takes RawInput
as input and outputs ClippedShapes
as output.
RawInput
This is basically a struct containing window events like resize, mouse events like cursor position / clicks, keyboard events like key press/release/ IME input etc..
Most of these events come from a Window Backend like winit
, glfw
, sdl2
etc.. which are cross platform windowing libraries.
Clipped Shapes
These are basically gpu friendly data structs which need to be rendered to the screen via a graphics backend.
This can be a low level graphics like opengl
, vulkan
etc.. or higher level abstractions like wgpu
or vulkano
. Or even higher abstractions like 2d renderers eg: skia
egui_backend
crate tries to reduce these backends into a trait implementation. This allows one to write an egui app, and swap out the backends as needed.
Eframe
egui already has an official backend crate called eframe
. It uses winit on desktop and a custom written js-based backend on web.
If winit works good enough, it is recommended to stick to eframe.
Usecases
Workaround bugs using alternate backends
If you are using winit, and suddenly some users are complaining about a crash on some specific configuration like fedora + nvidia. we have no idea how long it will take to fix that crash upstream. So, you immediately switch the backend to some alternative window backend like glfw
which might not have this specific bug. This can be released as a different version or you can include both backends and based on user configuration, decide at startup which backend to use.
If you realized that it was a vulkan bug, you can immediately switch to an opengl backend too in that same way as above.
Expose internals
If you don't particularly care about multiple backends, you can use internals of a windowing backend getting accesss to its "window" struct or raw "events" list etc..
For example, glfw-passthrough
crate has a feature to make windows passthrough which is very useful for overlays. If you are making an overlay, there's no point in abstracting over other backends. This allows a single crate to serve both usecases.
Serve as Modular reference implementations
Every attempt at creating a custom backend will have bugs like not knowing whether a size is in physical or logical pixels/coordinates. But having a decent reference implementation will serve as a launch platform for new backend implementations.
At the same time, devs can always reuse some items from the crates. like key
or mousebutton
or other event converting functions.
Separate Gfx and Windowing APIs
egui_backend is trying to separate out the api boundaries using traits. This will allow crates like wgpu/glow/three-d/rend3 and other gfx backends to only implement the GfxBackend trait. winit/sdl2/glfw will also only implement a WindowBackend trat. this will enable them to work with each other, without no (or minimal) glue code. So, if someone wants to create a new backend using a crate like vulkano or ash or erupt, they will only have to implement this trait and then allow it to work with windowing crates like winit/sdl2/glfw.
Limitations
There are some features which are explicitly excluded to keep this simple.
- no multiple windows. gfx and window apis need to sync window and swapchain lifecycle synchronization. This is niche requirement which shouldn't affect the ergonomics of the vast majority of other users.
For now, we will just assume that there's atmost one window at any point in the app's lifecycle.
Dependencies
~4–9.5MB
~90K SLoC