# Ventoy resolution_fit Theme Filtering: How It Matches Display Outputs to Theme Files

> Learn how Ventoy's resolution_fit theme plugin matches display outputs to theme files. See how it filters based on screen resolution for optimal boot themes.

- Repository: [longpanda/Ventoy](https://github.com/ventoy/Ventoy)
- Tags: internals
- Published: 2026-03-01

---

**Ventoy's `resolution_fit` option filters theme files by checking if their filenames contain the current boot-time screen resolution, falling back to all themes if no match exists.**

The `resolution_fit` feature in the Ventoy boot loader enables automatic theme selection based on the active video mode detected at boot. As implemented in the `ventoy/Ventoy` repository, this filtering mechanism ensures that high-resolution displays receive appropriately sized theme assets while maintaining compatibility across diverse hardware configurations.

## How resolution_fit Works in Ventoy

The filtering logic executes in three distinct stages within the GRUB2 plugin architecture, specifically inside [`GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c`](https://github.com/ventoy/Ventoy/blob/main/GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c).

### Parsing the JSON Configuration

When Ventoy loads a theme set described in JSON, the plugin reads the integer field `resolution_fit` at lines 381-393. Only the value `1` enables the feature; any other value converts to `0`. The parsed result stores in the global variable `g_theme_res_fit` and exports as the environment variable `vtoy_res_fit` for downstream use.

```json
{
    "file": [
        "mytheme_1024x768.cfg",
        "mytheme_1920x1080.cfg"
    ],
    "resolution_fit": 1,
    "random": "boot_second"
}

```

### Querying the Current Video Mode

During the `set_theme` command execution (lines 47-55), the code checks `g_theme_res_fit`. When enabled, it calls `grub_video_get_info(&info)` to retrieve the active video dimensions from the GRUB2 video API. The plugin formats these values as a `"WxH"` string (for example, `"1024x768"` or `"1920x1080"`) and stores it in a temporary buffer for comparison.

### Filtering the Theme Linked List

The plugin maintains discovered themes in the linked list `g_theme_head`. At lines 47-60, it iterates through this list and uses `grub_strstr(node->theme.path, buf)` to check if each theme's file path contains the exact resolution substring. Matching paths collect in the temporary array `pThemePath`. If the array remains empty, the filter drops and **all** themes become eligible for selection. Finally, Ventoy selects randomly (or by user preference) from the filtered candidates.

## Theme File Naming Conventions

For `resolution_fit` to function correctly, theme files must embed the target resolution directly into their filenames. The substring match uses `grub_strstr`, which performs a simple string search without regex complexity.

- **Valid examples**: [`mytheme_1024x768.cfg`](https://github.com/ventoy/Ventoy/blob/main/mytheme_1024x768.cfg), `mytheme_1920x1080.png`, [`ultrawide_2560x1440.txt`](https://github.com/ventoy/Ventoy/blob/main/ultrawide_2560x1440.txt)
- **Resolution string**: Must exactly match the format returned by the video driver (width + "x" + height)
- **Placement**: The resolution can appear anywhere in the filename, though typically it precedes the extension

The uniqueness of resolution strings (e.g., "1024x768" rarely appears coincidentally in unrelated filenames) prevents false positives during the substring scan.

## Fallback Behavior and Edge Cases

The implementation includes robust fallback mechanisms to ensure boot reliability. If `grub_video_get_info` fails to return valid dimensions—common on headless systems or with unsupported GPUs—the plugin ignores `g_theme_res_fit` and proceeds with normal theme selection. Similarly, when no theme filename contains the current resolution string, the filter gracefully deactivates and the full theme list becomes available.

This design guarantees that enabling `resolution_fit` never results in a boot failure due to missing theme assets; the system simply reverts to standard random or ordered selection semantics.

## Summary

- **Enable in JSON**: Set `resolution_fit` to `1` in the theme configuration to activate filtering.
- **Video detection**: Uses `grub_video_get_info()` to obtain current width and height at boot time.
- **String matching**: Filters `g_theme_head` via `grub_strstr()` looking for the "WxH" pattern in file paths.
- **Storage**: Parsed value lives in `g_theme_res_fit` and exports as `vtoy_res_fit` environment variable.
- **Graceful degradation**: Falls back to all themes if video detection fails or no filename matches the resolution.

## Frequently Asked Questions

### What happens if my theme filename does not include a resolution?

Ventoy treats the theme as a generic candidate available for all resolutions. When `resolution_fit` is enabled but no themes match the current display output, the plugin automatically includes all themes in the selection pool, ensuring the boot menu still renders with a valid theme.

### Can I use resolution_fit with multiple themes at the same resolution?

Yes. If multiple theme files contain the same resolution substring (for example, [`dark_1920x1080.cfg`](https://github.com/ventoy/Ventoy/blob/main/dark_1920x1080.cfg) and [`light_1920x1080.cfg`](https://github.com/ventoy/Ventoy/blob/main/light_1920x1080.cfg)), both entries pass the filter and collect in `pThemePath`. Ventoy then applies the configured selection method (random or sequential) to choose among the matching candidates.

### Why does resolution_fit require the value 1 specifically instead of any non-zero number?

The parser at lines 381-393 in [`ventoy_plugin.c`](https://github.com/ventoy/Ventoy/blob/main/ventoy_plugin.c) explicitly checks for equality with `1`. Any other integer value (including negative numbers or values greater than 1) converts to `0` through a conditional assignment. This strict validation prevents ambiguous configurations and ensures the feature activates only with explicit user intent.

### Does resolution_fit work with all graphics hardware?

The feature depends on GRUB2's `grub_video_get_info()` API successfully returning valid width and height values. If the underlying firmware or graphics driver does not expose standard VBE/VESA or EFI GOP information, the video query fails and Ventoy disables the filter automatically, falling back to unfiltered theme selection.