Skip to content

Composition

Jump to bottom
vicrodh edited this page Mar 15, 2026 · 1 revision

Composition (Graphics Settings)

QBZ uses WebKit for rendering its interface. The Composition settings control how QBZ interacts with your GPU, display server, and compositor. These settings live in Settings > Appearance > Composition.

Most users never need to touch these — QBZ auto-detects your hardware and applies safe defaults. This page is for when things go wrong or when you want to optimize.

Quick Reference

Problem Solution
Black screen on launch qbz --reset-graphics
Flickering / glitches QBZ_HARDWARE_ACCEL=0 qbz
Crash on NVIDIA + Wayland QBZ_FORCE_X11=1 qbz
Sluggish UI in a VM Apply the Max Performance profile
Want to start fresh qbz --reset-graphics

Settings

Hardware Acceleration

Controls whether QBZ uses your GPU for rendering.

  • Enabled (default): GPU-accelerated rendering. Better performance, smoother animations.
  • Disabled: Software rendering only. Maximum compatibility, higher CPU usage.

Disable this if you see rendering glitches, black screens, or crashes related to your GPU driver.

Force X11

Forces QBZ to use XWayland instead of native Wayland rendering. Requires restart.

  • Off (default): Uses your session's native display server.
  • On: Forces X11/XWayland even on Wayland sessions.

Turn this on if you're on Wayland with an NVIDIA GPU and experience crashes, protocol errors, or rendering corruption. This is the single most common fix for NVIDIA + Wayland issues.

GSK Renderer

Controls which GTK rendering backend QBZ uses.

Value Description Best For
Auto (default) Let GTK choose Most users
GL OpenGL renderer NVIDIA GPUs
NGL New GL renderer AMD / Intel on Wayland
Vulkan Vulkan renderer Modern GPUs with Vulkan support
Cairo Software rendering Maximum compatibility, VMs

If you're unsure, leave it on Auto. If you have an NVIDIA GPU, GL is often the safest choice.

GDK Scale

Integer scaling factor for the UI when using Force X11 / XWayland.

  • Only meaningful when Force X11 is enabled.
  • Values: 1 (no scaling), 2 (2x scaling for HiDPI displays).
  • Leave empty for automatic detection.

GDK DPI Scale

Fine-grained DPI scaling multiplier. Works on all display backends (X11, XWayland, native Wayland).

  • Values: 0.5, 1, 1.1, 1.5, etc.
  • Useful for tweaking text and UI element size without integer jumps.
  • Leave empty for automatic detection.

Force DMA-BUF Renderer

Advanced setting that forces WebKit's DMA-BUF buffer sharing with the compositor.

  • Off (default): DMA-BUF auto-managed based on GPU detection.
  • On: Force DMA-BUF rendering. May improve performance on AMD/Intel but can crash on NVIDIA + Wayland.

Only enable this if you know your GPU and compositor support DMA-BUF well (typically AMD or Intel on Wayland).

Composition Profiles

QBZ includes four preset profiles that configure multiple settings at once. These are quick presets — you can still customize individual settings after applying a profile.

Native Wayland (Sharpest)

Best for AMD or Intel GPUs on Wayland.

  • Force X11: off
  • DPI scaling: auto
  • GSK Renderer: auto
  • Background blur: enabled

Gives the sharpest rendering by using native Wayland. Not recommended for NVIDIA GPUs.

X11 Balanced

Good for mixed-DPI setups or NVIDIA GPUs.

  • Force X11: on
  • GDK Scale: 1
  • GDK DPI Scale: 1.1
  • Background blur: enabled

Slightly larger UI elements with blur effects. A good middle ground for NVIDIA users.

X11 Performance

Lean XWayland setup with lower GPU overhead.

  • Force X11: on
  • GDK Scale: 1
  • GDK DPI Scale: 1 (neutral)
  • Background blur: disabled

Disables blur for lower GPU load. Good for older hardware.

Max Performance

Maximum compatibility, minimum GPU usage.

  • Force X11: off (uses native, but with software renderer)
  • GSK Renderer: Cairo (software)
  • Background blur: disabled

Uses software rendering only. Best for virtual machines, Intel Arc with driver issues, or any setup where GPU rendering causes problems.

Auto-Configuration

QBZ can auto-detect your hardware and apply optimal settings:

qbz --autoconfig-graphics

This detects:

  • GPU type: NVIDIA, AMD, Intel, or unknown
  • Display server: Wayland or X11
  • Desktop environment: GNOME, KDE, etc.
  • Virtual machine: VirtualBox, VMware, QEMU, etc.

And recommends settings based on the combination. It asks for confirmation before applying changes.

What it applies per hardware:

Hardware Settings Applied
NVIDIA + Wayland GL renderer, DMA-BUF off, compositing mode off
NVIDIA + X11 GL renderer, DMA-BUF off
AMD + Wayland NGL renderer, DMA-BUF on
AMD + X11 Full hardware acceleration
Intel + Wayland NGL renderer, DMA-BUF on
Intel + X11 Full hardware acceleration
Virtual Machine Cairo (software), DMA-BUF off, blur off

Recovery Commands

When QBZ won't start or renders incorrectly, use these commands from a terminal.

Reset All Graphics Settings

qbz --reset-graphics

Resets everything to safe defaults: hardware acceleration on, Force X11 off, DMA-BUF off, all scaling auto. This is the first thing to try when things break.

For Flatpak:

flatpak run com.blitzfc.qbz --reset-graphics

Reset DMA-BUF Only

qbz --reset-dmabuf

Resets just the DMA-BUF setting without touching other graphics settings. Useful when only DMA-BUF is causing crashes.

Auto-Configure

qbz --autoconfig-graphics

Re-runs hardware detection and applies recommended settings. Useful after changing GPUs or switching between Wayland and X11.

Environment Variables

These override database settings and are useful for one-off testing or permanent workarounds.

Variable Values Effect
QBZ_HARDWARE_ACCEL=0 0 or 1 Disable (0) or force-enable (1) all GPU rendering
QBZ_FORCE_X11=1 0 or 1 Force XWayland on Wayland sessions
QBZ_FORCE_DMABUF=1 1 Force DMA-BUF renderer on
QBZ_DISABLE_DMABUF=1 1 Force DMA-BUF renderer off
QBZ_SOFTWARE_RENDER=1 1 Force software rendering (Mesa llvmpipe)

Environment variables always override database settings. They're evaluated once at startup.

Examples

# Nuclear option: disable all GPU rendering
QBZ_HARDWARE_ACCEL=0 qbz

# NVIDIA + Wayland fix
QBZ_FORCE_X11=1 qbz

# Combine: force X11 + disable GPU
QBZ_HARDWARE_ACCEL=0 QBZ_FORCE_X11=1 qbz

# Flatpak with GPU disabled
QBZ_HARDWARE_ACCEL=0 flatpak run com.blitzfc.qbz

# Force software rendering
QBZ_SOFTWARE_RENDER=1 qbz

Making Environment Variables Permanent

If you always need an override, add it to your shell profile or create a desktop entry override:

# In ~/.bashrc or ~/.zshrc
export QBZ_FORCE_X11=1

# Or create a wrapper script
echo 'QBZ_FORCE_X11=1 exec qbz "$@"' > ~/.local/bin/qbz-x11
chmod +x ~/.local/bin/qbz-x11

Common Scenarios

NVIDIA + Wayland: Crashes or Black Screen

This is the most common graphics issue. NVIDIA's Wayland support has known issues with WebKit's DMA-BUF renderer and compositing.

Quick fix:

QBZ_FORCE_X11=1 qbz

Permanent fix:

  1. Launch QBZ with QBZ_FORCE_X11=1
  2. Go to Settings > Appearance > Composition
  3. Apply the X11 Balanced profile
  4. Restart QBZ normally (no env var needed)

Virtual Machine: Slow or Broken Rendering

VMs often have limited GPU passthrough. QBZ auto-detects VMs, but if rendering is still broken:

QBZ_HARDWARE_ACCEL=0 qbz

Or apply the Max Performance profile in settings.

HiDPI Display: UI Too Small or Too Large

  1. Go to Settings > Appearance > Composition
  2. Adjust GDK DPI Scale (try 1.25 or 1.5)
  3. If using Force X11, also adjust GDK Scale (1 or 2)
  4. Restart QBZ

Intel Arc: Rendering Issues

Intel Arc GPUs sometimes have issues with the NGL renderer. Try:

  1. Set GSK Renderer to GL instead of Auto
  2. If still broken, set to Cairo (software)
  3. Or apply the Max Performance profile

Override Priority

When multiple settings conflict, QBZ uses this priority (highest wins):

  1. QBZ_HARDWARE_ACCEL=0 — disables everything
  2. QBZ_HARDWARE_ACCEL=1 — enables everything, bypasses all safety
  3. QBZ_FORCE_DMABUF / QBZ_DISABLE_DMABUF — fine-grained DMA-BUF control
  4. Environment variables (QBZ_FORCE_X11, QBZ_SOFTWARE_RENDER)
  5. Database settings (Settings > Appearance > Composition)
  6. Auto-detection defaults

Technical Details

  • Graphics settings are stored in ~/.local/share/qbz/graphics_settings.db (SQLite)
  • Developer settings (DMA-BUF) are stored in ~/.local/share/qbz/developer_settings.db
  • All composition changes require an app restart to take effect
  • QBZ logs all graphics decisions at startup — launch from a terminal to see them

Website | GitHub | Issues | Flathub

QBZ Wiki

Getting Started

Audio

Appearance

Features

Help

Clone this wiki locally