Graphics and Display

Waydroid's graphics stack is designed for high performance by avoiding traditional emulation overhead and leveraging modern Linux desktop technologies.

Wayland Integration

Waydroid is built exclusively for Wayland-based desktop environments. It does not support X11. The core principle is to treat Android application windows as native Wayland windows.

Here's how it works:

  1. The host system must be running a Wayland compositor (e.g., GNOME on Wayland, KDE Plasma on Wayland, Sway).
  2. When a user starts a Waydroid session (waydroid session start), Waydroid identifies the user's Wayland socket (e.g., /run/user/1000/wayland-0).
  3. This socket is bind-mounted into the Android container.
  4. Android's Hardware Composer (HWC) is implemented to act as a Wayland client. It connects to the host's Wayland compositor through the mounted socket.
  5. When an Android app draws to its surface, the HWC renders this surface into a Wayland window on the host desktop.

This direct rendering approach ensures that there is minimal latency and overhead, allowing for smooth animations and good graphics performance.

GPU Passthrough and Driver Detection

Waydroid achieves near-native graphics performance by passing the host's GPU directly into the container. This is done by bind-mounting the host's DRM (Direct Rendering Manager) device nodes into the container.

Specifically, Waydroid looks for render nodes, typically found at /dev/dri/renderD*.

The tools/helpers/gpu.py script contains the logic for detecting the appropriate GPU and Vulkan driver to use inside the container. It maps the kernel driver reported by the host to a specific Android Vulkan driver.

Host Kernel Driver Android Vulkan Driver
i915 intel or intel_hasvk
amdgpu radeon
radeon radeon
panfrost panfrost
msm, msm_dpu freedreno
vc4 broadcom
nouveau nouveau

This allows Android to use the host GPU for hardware-accelerated rendering via Vulkan. If a supported GPU is not found, Waydroid may fall back to software rendering (e.g., SwiftShader), which will have significantly lower performance.

The chosen DRM device can be overridden in /var/lib/waydroid/waydroid.cfg by setting the drm_device key.

[waydroid]
drm_device = /dev/dri/renderD129

This is useful on systems with multiple GPUs.