Crate webkit2gtk_nvidia_quirk

Expand description

§webkit2gtk-nvidia-quirk

A crate that provides session-aware workarounds for WebKitGTK rendering issues on Linux systems with the proprietary NVIDIA driver.

§Problem

When running WebKitGTK-based applications (such as Tauri apps) on Linux with the proprietary NVIDIA driver, rendering issues occur that vary by session type:

X11: The DMABUF renderer causes blank windows
Wayland: The application does not start

Related upstream issues:

§Solution

This crate detects the proprietary NVIDIA driver and the session type (X11/Wayland), then applies the appropriate workaround:

Session Type	Workaround	Environment Variable
X11	Disable DMABUF renderer	`WEBKIT_DISABLE_DMABUF_RENDERER=1`
Wayland	Disable NVIDIA explicit sync	`__NV_DISABLE_EXPLICIT_SYNC=1`

§Detection Method

The crate detects the NVIDIA driver by:

If the primary/boot GPU (via boot_display or boot_vga attributes) has vendor ID 0x10de
If the proprietary nvidia kernel module is loaded (/sys/module/nvidia exists)

GPU detection uses sysfs exclusively (/sys/class/drm/). This provides a simpler and more reliable detection mechanism with no external runtime dependencies.

This specifically targets the proprietary NVIDIA driver, not the open-source nouveau driver.

§Usage

use webkit2gtk_nvidia_quirk::{ApplyWorkaroundOptions, apply_workaround_with_options};

let disable_dmabuf = std::env::args().any(|arg| arg == "--disable-dmabuf-renderer");
let disable_nv_sync = std::env::args().any(|arg| arg == "--disable-nv-explicit-sync");

let options = ApplyWorkaroundOptions::default()
    .force_disable_dmabuf(disable_dmabuf)
    .force_disable_nv_explicit_sync(disable_nv_sync);

apply_workaround_with_options(options);

§API

§`is_primary_gpu_nvidia() -> bool`

Checks whether the primary GPU is an NVIDIA GPU.

Returns true if the primary GPU (boot_display or boot_vga attribute) has vendor ID 0x10de (NVIDIA), Returns false otherwise. This function does not check kernel module loading.

§`needs_workaround() -> WorkaroundKind`

Determines which workaround should be applied based on NVIDIA detection and session type.

Returns WorkaroundKind::None if no workaround is needed, WorkaroundKind::DisableWebkitDmabufRenderer for X11 sessions, or WorkaroundKind::DisableNvExplicitSync for Wayland sessions.

§`set_webkit_disable_dmabuf_renderer()`

Sets the WEBKIT_DISABLE_DMABUF_RENDERER environment variable. Use this for X11 sessions.

§`nv_disable_explicit_sync()`

Sets the __NV_DISABLE_EXPLICIT_SYNC environment variable. Use this for Wayland sessions.

§`apply_workaround_with_options(options: ApplyWorkaroundOptions)`

Convenience function that applies workarounds based on the provided options. If any force options are set, it applies those directly. Otherwise, it calls needs_workaround to detect which workaround is needed.

This is the recommended way to apply workarounds from CLI arguments.

§`WorkaroundKind`

Enum representing the type of workaround to apply:

None: No workaround needed
DisableWebkitDmabufRenderer: Disable the DMABUF renderer (for X11)
DisableNvExplicitSync: Disable NVIDIA explicit sync (for Wayland)

§`ApplyWorkaroundOptions`

Builder struct for configuring which workarounds to force-apply. Use the builder pattern to set options:

use webkit2gtk_nvidia_quirk::{ApplyWorkaroundOptions, apply_workaround_with_options};

let options = ApplyWorkaroundOptions::default()
    .force_disable_dmabuf(true);

apply_workaround_with_options(options);

§Platform Support

This crate is Linux-only and provides no functionality on other platforms.

Structs§

ApplyWorkaroundOptions: Builder struct for configuring which workarounds to force-apply.

Enums§

WorkaroundKind: Represents the type of workaround to apply for NVIDIA WebKitGTK issues.

Functions§

apply_workaround_with_options: Applies workarounds based on the provided options.
is_primary_gpu_nvidia: Checks if the primary GPU is an NVIDIA GPU.
needs_workaround: Checks if a workaround should be applied.
nv_disable_explicit_sync: Sets the __NV_DISABLE_EXPLICIT_SYNC environment variable.
set_webkit_disable_dmabuf_renderer: Sets the WEBKIT_DISABLE_DMABUF_RENDERER environment variable.