Resources

The HiDPI & 4K Manual

Glass-Sharp Displays: Configuring 4K, Retina, and HiDPI Scaling.

The Strategy

In the "Old Linux" world (X11), 4K scaling was a nightmare of blurry text and misaligned icons. Wayland and Sway have fixed this at the C-level. Tebian provides a "one-click" setup for HiDPI Scaling that ensures every pixel is sharp, from your terminal to your web browser.

This guide explains how to configure Tebian for high-resolution displays (Retina, 4K monitors, and modern laptop screens).

1. Output Scaling (Sway)

Sway's native scaling is superior to traditional OS scaling because it happens in the Compositor. We pre-configure the output * scale 2 command for detected 4K displays.

  • Integer Scaling: We recommend 2x (200%) scaling for 4K displays to maintain sharp, non-interpolated pixels.
  • Fractional Scaling: Sway supports 1.25x, 1.5x, and 1.75x, though integer scaling is always "cleaner" for the GPU.
  • Per-Monitor: You can set different scales for different monitors (e.g., 2x for the laptop, 1x for the external monitor) with zero flicker.

2. Toolkit Scaling (GDK & QT)

Sway's output scaling only handles the window management. To get your actual apps (like Firefox or PCManFM) to look sharp, you need to set the GDK_SCALE and QT_SCALE_FACTOR environment variables.

  • GDK_SCALE=2: Sharpens GTK-based apps (Firefox, LibreOffice).
  • QT_SCALE_FACTOR=2: Sharpens QT-based apps (VLC, Bitwig).
  • Tebian Profile: We pre-populate these in ~/.profile during the HiDPI setup.

3. Font Rendering (Pango)

Sharp displays require sharp fonts. Tebian uses Pango and Freetype with custom font-config settings to ensure your text is clear and readable on any resolution.

  • Hinting: We enable slight hinting for the best balance between sharpness and character shape.
  • Anti-Aliasing: Subpixel rendering (RGBA) is enabled by default.
  • Nerd Fonts: We use JetBrains Mono Nerd Font as our system font for its exceptional 4K clarity.

4. Browser Hardware Acceleration

On 4K displays, the browser has to render 4x as many pixels as on 1080p. To keep it smooth, you must have GPU hardware acceleration enabled. Tebian's "HiDPI Setup" automatically configures VA-API for your browser.

  • Zero Frame Drops: Smooth 4K YouTube playback on any hardware.
  • GPU Rendering: Offloads text rendering and CSS animations to your NVIDIA/AMD card.

Why HiDPI on Tebian?

Because our compositor (Sway) is written in C and our theme (Stealth Glass) is minimal, there is no "Performance Penalty" for 4K scaling. You get the world's sharpest display experience with the world's fastest UI. One ISO. One menu. Glass-sharp productivity.