grub-render-label

grub-render-label [OPTIONS] TEXT [OUTPUT_FILE]

--output=FILE
    Specifies the path for the output image file. If not provided, the rendered image data is written to standard output.

--format=FORMAT
    Sets the output image format (e.g., png, tga, jpg). The supported formats depend on the underlying image rendering libraries available to GRUB.

--font=FILE
    Specifies the font file (e.g., a TrueType font .ttf file) to use for rendering the text.

--fontsize=SIZE
    Defines the font size in pixels for the rendered text.

--color=COLOR
    Sets the foreground color of the text. Colors can be specified as hexadecimal values (e.g., #RRGGBB) or by common color names (e.g., red, blue).

--bgcolor=COLOR
    Sets the background color of the image. Defaults to transparent if the output format supports an alpha channel; otherwise, it defaults to black.

--width=WIDTH
    Specifies the desired width of the output image in pixels. If not specified, the width is determined by the text content.

--height=HEIGHT
    Specifies the desired height of the output image in pixels. If not specified, the height is determined by the text content.

--wrap
    Enables word wrapping for the input text, causing long lines to break into multiple lines within the specified --width.

--version
    Prints the version information of grub-render-label and exits.

--help
    Displays a help message detailing command usage and options, then exits.

The grub-render-label command is a utility provided by the GRUB (GRand Unified Bootloader) suite. Its primary function is to render a given text string, typically a label intended for a GRUB boot menu entry, into an image file. This is particularly useful for creating custom graphical boot menus where text labels need to be displayed as part of a background image or as standalone graphical elements.

The command allows for extensive customization of the rendered text, including font selection, font size, foreground and background colors, and the dimensions of the output image. It supports various image formats, making it versatile for integration into different GRUB theme designs. Essentially, it transforms textual boot menu descriptions into visually appealing graphical components.

• Font Availability: The specified font file must be accessible and readable by the command. Incorrect font paths or unsupported font types will lead to errors.
• Image Format Support: The range of supported output image formats depends on the GRUB build and its underlying library dependencies (e.g., FreeType, ImageMagick).
• Transparency: Transparent backgrounds (--bgcolor=transparent) are only effective if the chosen output format (e.g., PNG) supports alpha channels. Other formats might render a solid background color.
• Text Wrapping: The --wrap option works best when --width is specified, as it helps determine the maximum line length for wrapping.

This command is primarily used by GRUB theme designers or scripts that automate theme creation. It allows for the dynamic generation of graphical text labels for boot menu entries, which can then be overlaid onto background images or used as standalone menu items, enhancing the visual appeal and customization options of the bootloader interface.

The TEXT argument can be a simple string. If the text contains spaces or special characters, it should be enclosed in quotes to be treated as a single argument. Newlines (\n) within the input text can be used to render multi-line labels, especially when combined with the --wrap option.

The grub-render-label command emerged as part of GRUB's evolution towards more sophisticated and customizable graphical boot menus, particularly with the advent of GRUB 2. As GRUB themes became more prevalent, there was a need for utilities to dynamically generate graphical elements like menu labels from plain text. This command facilitates the creation of visually integrated boot screens by allowing theme designers to render text directly into image formats that can then be used within a GRUB theme's visual assets, simplifying the process of updating text content without manual image editing.

grub-mkfont(1), grub-mkimage(1), grub-install(8), grub-mkrescue(1)