Platform API: GPU Specs, Power Mode, and Window Appearance

Kael abstracts over macOS, Windows, Linux (X11 and Wayland), and FreeBSD through a single internal Platform trait. You rarely implement this trait yourself, but you interact with the types it exposes — GpuSpecs, PowerMode, WindowAppearance, and related enums — whenever you need to adapt your application’s behavior to the host environment. This page documents all of those surface-level types and the patterns Kael uses to select the right backend at runtime.

GpuSpecs

GpuSpecs carries information about the GPU (or CPU-based software renderer) that Kael’s rendering backend is running on. You can retrieve it from a Window with window.gpu_specs().

rust

pub struct GpuSpecs {
    /// Whether the GPU is a software emulator running on the CPU (e.g. llvmpipe).
    pub is_software_emulated: bool,
    /// The device name as reported by Vulkan.
    pub device_name: String,
    /// The driver name as reported by Vulkan.
    pub driver_name: String,
    /// Further driver information as reported by Vulkan.
    pub driver_info: String,
}

GpuSpecs derives Default, Debug, Clone, serde::Serialize, and serde::Deserialize.

is_software_emulated

bool

true when Kael is rendering on a software GPU such as llvmpipe. This indicates the system has no discrete or integrated GPU, or that the platform fell back to a CPU renderer. You can use this flag to disable expensive visual effects that would be too slow on a software renderer.

device_name

String

The human-readable name of the GPU device, as reported by Vulkan (or Direct3D on Windows). Examples: "NVIDIA GeForce RTX 4090", "Apple M3 Pro", "llvmpipe (LLVM 17.0.6, 256 bits)".

driver_name

String

The name of the graphics driver. On Linux/Wayland and macOS this comes from the Blade renderer’s device_information().driver_name. On Windows it is derived from the DXGI adapter’s VendorId.

driver_info

String

Further driver detail (e.g. a version string). On Windows this is the driver version formatted from the DXGI adapter description.

Retrieving GpuSpecs

rust

fn render(&self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
    if let Some(specs) = window.gpu_specs() {
        if specs.is_software_emulated {
            // Disable blur, shadows, or other GPU-intensive effects
        }
        log::info!("GPU: {} ({})", specs.device_name, specs.driver_name);
    }
    // ...
}

window.gpu_specs() returns Option<GpuSpecs>. On test platform targets it always returns None, so guard all uses with if let Some.

PowerMode

PowerMode reflects the host operating system’s current power policy. Kael queries this through the Platform trait and exposes it on Window::power_mode().

rust

pub enum PowerMode {
    /// Full performance mode, typically when external power is available.
    #[default]
    Performance,
    /// Reduced-power mode, typically when the system is running on battery.
    Balanced,
    /// The system's low-power or battery-saver mode is active.
    LowPower,
}

PowerMode derives Debug, Clone, Copy, PartialEq, Eq, and Default (Performance).

Performance

variant

The system is plugged in or operating at full capacity. No frame-rate throttling is applied. This is the default.

Balanced

variant

The system is on battery but not in an aggressive power-save state. Kael may allow some background work to complete normally.

LowPower

variant

The OS low-power or battery-saver mode is active. Kael internally throttles frame scheduling to a maximum of roughly 30 fps (≈33 ms/frame) when LowPower is active.

Platform-specific detection

Each backend queries the OS power state natively:

Platform	Detection mechanism
macOS	`NSProcessInfo.isLowPowerModeEnabled`, `NSProcessInfo.thermalState`
Windows	`PowerGetEffectiveOverlayScheme` via WinAPI
Linux	`/sys/class/power_supply` or D-Bus `upower`

Reacting to power changes

The SystemPowerEvent::PowerModeChanged event fires whenever the OS power policy changes. Subscribe to it through the Platform trait’s event callback to update your application behavior dynamically:

rust

// Inside a window callback
let mode = window.power_mode();
let is_low_power = mode == PowerMode::LowPower;

// Disable expensive animations when on battery saver
if is_low_power {
    // skip animation setup
}

You can check window.is_full_speed() as a convenience boolean — it returns true when power_mode != PowerMode::LowPower.

WindowAppearance

WindowAppearance describes the OS-level light/dark appearance assigned to a window. Kael surfaces it via Window::appearance() and Platform::window_appearance().

rust

pub enum WindowAppearance {
    /// A light appearance (macOS: "aqua").
    #[default]
    Light,
    /// A light appearance with vibrant colors (macOS: "NSAppearanceNameVibrantLight").
    VibrantLight,
    /// A dark appearance (macOS: "darkAqua").
    Dark,
    /// A dark appearance with vibrant colors (macOS: "NSAppearanceNameVibrantDark").
    VibrantDark,
}

WindowAppearance derives Copy, Clone, Debug, Default, PartialEq, and Eq.

Light

variant

Standard light mode. The default on all platforms. On macOS this corresponds to the aqua NSAppearance.

VibrantLight

variant

Light mode with translucency effects. macOS only (NSAppearanceNameVibrantLight). On other platforms Kael maps this to Light.

Dark

variant

Standard dark mode. On macOS this corresponds to the darkAqua NSAppearance.

VibrantDark

variant

Dark mode with translucency effects. macOS only (NSAppearanceNameVibrantDark). On other platforms Kael maps this to Dark.

Using WindowAppearance with themes

The most common use of WindowAppearance is selecting the right theme at window creation:

rust

cx.open_window(options, |window, cx| {
    let theme = Theme::for_appearance(window);
    cx.set_global(theme);
    MyRootView::new(cx)
})

Theme::for_appearance internally matches on WindowAppearance:

rust

// from theme.rs
pub fn for_appearance(window: &Window) -> Self {
    match window.appearance() {
        WindowAppearance::Light | WindowAppearance::VibrantLight => Self::light(),
        WindowAppearance::Dark  | WindowAppearance::VibrantDark  => Self::dark(),
    }
}

On Linux, appearance is read from the XDG Desktop Portal’s color scheme preference (PreferDark → Dark, everything else → Light). On Windows, Kael reads the registry key for the system dark mode flag.

The Platform trait

Platform is an internal trait (pub(crate)) that each backend implements. You interact with it indirectly through App and Window methods, but the trait’s shape is useful to understand:

rust

pub(crate) trait Platform: 'static {
    fn background_executor(&self) -> BackgroundExecutor;
    fn foreground_executor(&self) -> ForegroundExecutor;
    fn text_system(&self) -> Arc<dyn PlatformTextSystem>;

    fn run(&self, on_finish_launching: Box<dyn 'static + FnOnce()>);
    fn quit(&self);
    fn restart(&self, binary_path: Option<PathBuf>);
    fn activate(&self, ignoring_other_apps: bool);
    fn hide(&self);
    fn hide_other_apps(&self);
    fn unhide_other_apps(&self);

    fn displays(&self) -> Vec<Rc<dyn PlatformDisplay>>;
    fn primary_display(&self) -> Option<Rc<dyn PlatformDisplay>>;
    fn active_window(&self) -> Option<AnyWindowHandle>;

    fn window_appearance(&self) -> WindowAppearance;
    fn power_mode(&self) -> PowerMode;
    // ...
}

Backend selection

Kael picks a backend at startup based on the compile target and environment variables:

// always uses MacPlatform
pub(crate) fn current_platform(headless: bool) -> Rc<dyn Platform> {
    Rc::new(MacPlatform::new(headless))
}

Compositor detection on Linux

guess_compositor() checks environment variables to decide which Wayland or X11 backend to use:

rust

pub fn guess_compositor() -> &'static str {
    if std::env::var_os("ZED_HEADLESS").is_some() {
        return "Headless";
    }

    let use_wayland = std::env::var_os("WAYLAND_DISPLAY")
        .is_some_and(|d| !d.is_empty());
    let use_x11    = std::env::var_os("DISPLAY")
        .is_some_and(|d| !d.is_empty());

    if use_wayland { "Wayland" }
    else if use_x11 { "X11" }
    else { "Headless" }
}

guess_compositor does not attempt to connect to the compositor — it only reads environment variables. A connection failure will be reported later when the backend client initializes.

SystemPowerEvent

Fired when significant OS power state transitions occur.

rust

pub enum SystemPowerEvent {
    Suspend,          // system is about to sleep
    Resume,           // system woke from sleep
    PowerModeChanged, // battery-saver or performance mode changed
    LockScreen,       // screen was locked
    UnlockScreen,     // screen was unlocked
    Shutdown,         // system is shutting down
}

WindowBackgroundAppearance

Controls the visual treatment of the window background when no content is present.

rust

pub enum WindowBackgroundAppearance {
    #[default]
    Opaque,       // solid background; compositor does not need to draw behind this window
    Transparent,  // plain alpha channel transparency
    Blurred,      // blur the content behind the window (not always supported)
}

WindowBackgroundAppearance::Blurred is not supported on all backends. Check your target platform’s capabilities before relying on it for visual design.

PowerSaveBlockerKind

Passed to the platform’s power-save-blocker API to prevent the system from suspending or the display from sleeping.

rust

pub enum PowerSaveBlockerKind {
    PreventAppSuspension, // keep the app running even when idle
    PreventDisplaySleep,  // keep the display on
}

Application

Elements

System

Platform API: GPU Specs, Power Mode, and Window Appearance

GpuSpecs

Retrieving GpuSpecs

PowerMode

Platform-specific detection

Reacting to power changes

WindowAppearance

Using WindowAppearance with themes

The Platform trait

Backend selection

Compositor detection on Linux

SystemPowerEvent

WindowBackgroundAppearance

PowerSaveBlockerKind

Build docs developers (and LLMs) love

Application

Elements

System

Documentation Index

​GpuSpecs

​Retrieving GpuSpecs

​PowerMode

​Platform-specific detection

​Reacting to power changes

​WindowAppearance

​Using WindowAppearance with themes

​The Platform trait

​Backend selection

​Compositor detection on Linux

​Related platform enums

​SystemPowerEvent

​WindowBackgroundAppearance

​PowerSaveBlockerKind

Build docs developers (and LLMs) love

GpuSpecs

Retrieving GpuSpecs

PowerMode

Platform-specific detection

Reacting to power changes

WindowAppearance

Using WindowAppearance with themes

The Platform trait

Backend selection

Compositor detection on Linux

Related platform enums

SystemPowerEvent

WindowBackgroundAppearance

PowerSaveBlockerKind