Skip to the main content

I dual booted to Arch Linux few months ago and started running Hyprland on it. The experience is out of the world. I just love how I can open any number of windows without bothering with layout, navigate between them without lifting a finger off my keyboard, and when it gets messy just open a new workspace. So naturally I have been trying to slowly shift most of my work from Windows to my Linux setup.

This weekend I decided to finally watch the movie I had been wanting to for a long time. I thought why not use Arch for that? I already had VLC installed, but I had never used it. When I opened VLC, I noticed it was all blurry. So I spent my afternoon solving this issue. I felt the issue was pretty interesting so I thought of writing a short blog about it.

Background

To understand why a simple video player looks blurry, we need some technical context:

1. HiDPI (High Dots Per Inch) Displays

This is the physical reality of your screen. Traditionally, computer screens had about 96 pixels per inch. A 50-pixel button looked about half an inch wide. Modern screens pack twice as many pixels into the same space. If Qt draws that same 50-pixel button on a HiDPI screen, it will be physically tiny (1/4 inch). To look correct, Qt needs to know it should rasterize a 100-pixel button instead.

When developers design an interface, they define components using logical sizes, like '12pt font' or '100 logical pixels.' On a standard monitor (96 DPI), 1 logical unit roughly equals 1 physical pixel. However, on a HiDPI display, pixels are packed twice as densely. If the application ignores this density, that '100px' button will physically shrink by half, becoming unreadably small.

To fix this, the system must apply a Scale Factor (e.g., 200%), instructing the application to use two physical pixels for every logical pixel. This ensures the interface remains readable and sharp, regardless of how small the actual pixels are.

2. Qt

Qt is the framework VLC uses to create its interface. Its primary job is Rasterization.

What is Rasterization?

Think of it as the difference between a blueprint and a photograph.

• 
  The Blueprint (Vector): The application code describes the UI mathematically: "Draw a perfect circle with a 50-unit radius." This mathematical description has infinite resolution—it's just an equation.


• 
  The Photograph (Raster): To show this on a screen, Qt must convert that equation into a specific grid of colored dots (pixels). This process of turning "math" into "dots" is rasterization.

Once Qt rasterizes the interface, it stores the result in a chunk of memory called a Graphical Buffer. Think of the buffer as a finished bitmap image (like a PNG) sitting in your RAM. Qt then hands this finished image to the Display Server to be placed on the screen.

3. The Display Server

The Display Server is the piece of software that sits between the applications (clients) and the hardware (kernel/GPU). Its job is to take the buffers (images) from all your open apps and decide exactly where they appear on the physical screen.

4. The Protocols: X11 vs Wayland

These are the communication standards that define how an application talks to the display hardware.

X11

Designed in the 1980s as a network-transparent protocol, X11 mandates a strict separation of concerns. It requires three distinct components:

1. 
   The Client (App): Requests to draw a window.


2. 
   The X Server (Display Server): A "dumb" middleman that controls the hardware but has no logic about window placement.


3. 
   The Window Manager: A separate program that decides where windows go.

Because the X11 protocol forbids the Display Server from making policy decisions (like window placement), every action requires a complex three-way conversation (App ↔ Server ↔ WM).

This architecture relies on a Global Coordinate Space, where the Server manages a single, unified canvas across all screens. Because every app shares the same global grid, they all have to agree on the "scale" of that grid. If you have a HiDPI screen that needs a dense grid and a normal screen that needs a coarse grid, X11 struggles to stretch just one part of the canvas.

While X11 does have DPI awareness through settings like Xft.dpi, it's system-wide rather than per-monitor, and many legacy apps simply ignore it. When a modern HiDPI screen enters the picture, X11 can't elegantly communicate per-monitor scaling requirements to applications.

Wayland

Wayland was designed to eliminate this inefficiency. The protocol defines a direct relationship between the client and the entity controlling the screen. To implement the Wayland protocol, the "Display Server" and the "Window Manager" must be merged into a single piece of software called the Compositor (in our case, Hyprland).

• 
  Direct Control: Clients allocate their own buffers and hand them directly to the Compositor.


• 
  Isolation: Instead of a shared global grid, Wayland gives every app its own isolated Surface. The application draws on its private surface without knowing where it is on the full screen. Because each window is an isolated "sheet of paper," the Compositor can easily manipulate them individually. It can tell one surface to scale up by 2x while leaving another at 1x. This per-window flexibility is exactly what modern HiDPI screens require.

Wayland handles HiDPI seamlessly—the compositor can explicitly tell each application: 'You are on a HiDPI display—scale yourself up by 2x.' The app receives this message and redraws itself with high-resolution assets.

5. The Bridge: XWayland

X11 was the standard for over 30 years. Thousands of applications (like older games, Steam, and yes, VLC 3.0) were written to speak only X11. Since standard X11 applications cannot communicate via the Wayland protocol, XWayland acts as a translation layer. It is a fully functional X Server that runs inside your Wayland session.

• 
  To the App (VLC): XWayland looks like a standard X Server.


• 
  To the Compositor (Hyprland): XWayland looks like a single application window.

But this creates a problem. XWayland apps inherit X11's scaling limitations—they can't receive per-window scaling instructions from the Wayland compositor. This forces Hyprland to make a compromise:

• Let them render at native 1x resolution (sharp but tiny)


• Scale them up using xwayland:force_zero_scaling (readable size but blurry)

Hyprland's xwayland:force_zero_scaling setting (enabled by default) chooses the second option: it tells XWayland apps they're on a low-DPI display, then scales up their output. The result is legible text at the cost of blurriness—because the app drew itself at 1x thinking it was on a standard display, and Hyprland stretched those pixels to fit your HiDPI screen.

The issue and the fix

VLC 3.0 lacks native Wayland support, so it falls back to XWayland. This creates a scaling problem: VLC 3.0 ignores X11's DPI hints and renders at native 1x resolution. When Hyprland's xwayland:force_zero_scaling is disabled (the default), it scales up VLC's 1x output, resulting in a blurry display.

To fix this, first disable force scaling in Hyprland, by adding this to the Hyprland config file:

xwayland {

    force_zero_scaling = true

}

This makes VLC render sharp—but tiny. To get it to the correct size, we bypass X11's DPI system entirely and tell Qt directly to scale at 2x:

QT_SCALE_FACTOR=2 vlc

This works because VLC respects Qt's environment variables even though it ignores X11 DPI settings. Qt renders the UI at 2x internally, and since force scaling is disabled, Hyprland doesn't scale it again—giving you sharp, properly-sized text.

Closing Thoughts

This journey gave me an opportunity to get to know the Linux GUI ecosystem a bit better. I am still learning the intricacies of the Linux graphics stack (it’s a deep rabbit hole!). If I have oversimplified any architectural details or if you know a cleaner way to handle this in Hyprland, I would love to hear your feedback. Feel free to reach out or correct me!