egui_overlay

Egui Overlay is a crate designed to create GUI applications with the following characteristics:

1. Transparent window surface: The window background is transparent.
2. Toggleable decorations: Ability to toggle window borders and title bars.
3. Input passthrough: The ability to let mouse clicks and other inputs pass through the window surface to the applications underneath when egui does not need the input.

It combines egui_window_glfw_passthrough for windowing management with rendering backends like egui_render_three_d (for general drawing) or egui_render_wgpu (specifically for macOS support).

When targeting wasm32-unknown-emscripten, you must configure specific linker flags in your .cargo/config.toml to enable GLFW and WebGL2 support.

Required flags for GLFW and WebGL2:

• USE_GLFW=3
• MAX_WEBGL_VERSION=2
• MIN_WEBGL_VERSION=2 (to disable WebGL1)

Optional flags:

• FULL_ES2 or FULL_ES3 for OpenGL ES emulation.
• ERROR_ON_UNDEFINED_SYMBOLS=0 (may be required for wgpu to ignore certain EGL symbols).

# inside .cargo/config.toml
[target.wasm32-unknown-emscripten]
rustflags = [
    "-C",
    "link-arg=-s",
    "-C",
    "link-arg=USE_GLFW=3",
    "-C",
    "link-arg=-s",
    "-C",
    "link-arg=MAX_WEBGL_VERSION=2 ",
    "-C",
    "link-arg=-s",
    "-C",
    "link-arg=MIN_WEBGL_VERSION=2",
    "-C",
    "link-arg=-s",
    "-C",
    "link-arg=DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=1",
]

To see a standard implementation of the overlay functionality, run the basic example using cargo:

cargo run -p basic

For WASM applications using SDL2/GLFW, the HTML canvas element must have specific attributes and a JavaScript Module configuration to ensure the library can find the backing window.

Requirements:

1. The <canvas> element must have id="canvas" and data-raw-handle="1".
2. A Module object must be defined in a <script> tag before the generated .js glue code is loaded. This object must provide a canvas function that returns the canvas element.

<!DOCTYPE html>
<html
  <body
    <canvas data-raw-handle="1" id="canvas"></canvas>
    <!-- this script MUST be loaded before the cargo-generated script -->
    <script type="text/javascript">
      var Module = {
        canvas: (function () {
          return document.getElementById("canvas");
        })(),
      };
    </script>
    <script src="my_project_name.js"></script>
  </body>
</html>

To build and deploy your project, compile for the wasm32-unknown-emscripten target, copy the resulting .wasm, .js, and index.html files to a distribution directory, and serve them using a local server.

#!/bin/sh
echo "building for emscripten target"
# Ensure .cargo/config.toml contains the necessary linker options
cargo build --target=wasm32-unknown-emscripten --release

echo "copying files to dist directory"
mkdir -p dist

# Copy the WASM binary
cp target/wasm32-unknown-emscripten/release/my_project_name.wasm dist
# Copy the JS glue code generated by cargo
cp target/wasm32-unknown-emscripten/release/my_project_name.js dist
# Copy the HTML entry point
cp index.html dist

# Start a local development server (DO NOT USE IN PRODUCTION)
(cd dist && python -m http.server)

Windows

Supported.

Linux

• Display Servers: X11 is supported natively. Wayland works via Xwayland, though support may vary depending on the window manager.
• Compositing: You must use a compositor that supports transparency (e.g., kwin). If using tiling window managers like i3wm, you will need an external compositor like picom.
• Window Management: In tiling window managers (like i3wm), you may need to configure the overlay window as "floating" to ensure it stays above other tiled windows.

macOS

• Supported, but uses egui_render_wgpu for rendering because Apple does not support OpenGL.
• Known Bug: When passthrough is enabled, the window titlebar can only be clicked in the bottom half; the top half becomes passthrough.

To inject custom WGPU rendering commands into the egui draw stream, use the CallbackFn structure. This allows you to run arbitrary code during the render pass.

CallbackFn consists of two parts:

1. prepare: A callback used to perform resource allocation or data uploads on the Device and Queue before rendering begins.
2. paint: A callback that receives the RenderPass and PaintCallbackInfo (containing viewport, clip rect, and screen size) to execute drawing commands.

Note that CallbackFn must be wrapped in an Arc to be used within the egui callback system.

// Example structure for a custom callback
let my_callback = CallbackFn {
    prepare: Arc::new(|device, queue, custom_data| {
        // Perform setup here
    }),
    paint: Arc::new(|info, rpass, custom_data| {
        // Execute WGPU commands here using rpass
    }),
};

While start() provides sensible defaults for an overlay (transparent, no borders, always on top), you can influence window creation by providing a custom GlfwConfig if you were to use the underlying GlfwBackend directly. In the current start() implementation, the following behaviors are hardcoded:

• transparent_window: Some(true)
• glfw_callback: Includes a hint to ScaleToMonitor(true).
• window.set_floating(true): Makes the window always on top.
• window.set_decorated(false): Removes the title bar and borders.

To use egui_render_wgpu, you must initialize an EguiPainter. This struct manages the vertex/index buffers, textures, and the render pipeline required to draw egui primitives using WGPU.

When creating a new painter, you must provide the WGPU Device and the TextureFormat of your surface. The painter will automatically set up the necessary uniform buffers for screen size, texture bind group layouts, and samplers (linear, nearest, and font).

let painter = EguiPainter::new(&device, surface_format);