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

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.

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.

{
    "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, mytheme_1920x1080.png, 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 and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}