Background Images & Thumbnails

/Backgrounds/
├── wallpaper1.png          # Full-size background image
├── wallpaper1_thumb.png    # Auto-generated thumbnail (128×128)
├── abstract2.jpg           # Full-size JPEG background
├── abstract2_thumb.png     # Auto-generated thumbnail
├── nature3.bmp             # Full-size BMP background
├── nature3_thumb.png       # Auto-generated thumbnail
├── custom.jpeg             # Full-size JPEG background
    └── custom_thumb.png    # Auto-generated thumbnail

File extensions are case-insensitive. .PNG, .png, .JPG, and .jpg are all recognized. Thumbnail files can use any case for the suffix (_thumb.png or _thumb.PNG).

// Landscape image (width > height)
if (width > height) {
    thumbHeight = (height × 128) / width
    thumbWidth = 128
}

// Portrait image (height > width)
else if (height > width) {
    thumbWidth = (width × 128) / height
    thumbHeight = 128
}

// Square image (width == height)
else {
    thumbWidth = 128
    thumbHeight = 128
}

# Windows
copy mybackground.png Ramdisk\Backgrounds\
copy another.jpg Ramdisk\Backgrounds\

# Linux/Mac
cp mybackground.png Ramdisk/Backgrounds/
cp another.jpg Ramdisk/Backgrounds/

# Using ImageMagick
convert mybackground.png -resize 128x128 mybackground_thumb.png

# Using Python/PIL
from PIL import Image
img = Image.open('mybackground.png')
img.thumbnail((128, 128))
img.save('mybackground_thumb.png')

# Windows
ForceRebuildISO.bat

# Linux/Mac
./rebuild.sh

guideXOS uses an in-memory ramdisk. Images selected at runtime are not persistent and will be lost on reboot. To make backgrounds permanent, add them to the ramdisk and rebuild the ISO.

<code>internal class DisplayOptions : Window {
    // Background thumbnail system
    private List<string> _backgroundPaths;  // Full paths to images
    private List<Image> _thumbnails;        // Cached thumbnail images
    private int _thumbSize = 128;           // Thumbnail dimensions
    private bool _thumbnailsLoaded = false; // Load state flag
    private int _bgScroll = 0;              // Gallery scroll position
    
    // Gallery UI
    private int _padding = 16;
    private int _btnW = 180;
    private int _btnH = 38;
}</code>

<code>private void LoadBackgrounds() {
    if (_thumbnailsLoaded) return;
    _thumbnailsLoaded = true;

    var files = File.GetFiles("Backgrounds/");
    foreach (var fi in files) {
        // Skip directories and thumbnail files
        if (fi.Attribute == Directory) continue;
        if (fi.Name.EndsWith("_thumb.png")) continue;
        
        // Check for supported formats
        bool isSupported = fi.Name.EndsWith(".png") ||
                          fi.Name.EndsWith(".jpg") ||
                          fi.Name.EndsWith(".jpeg") ||
                          fi.Name.EndsWith(".bmp");
        
        if (isSupported) {
            string path = "Backgrounds/" + fi.Name;
            string thumbPath = GetThumbnailPath(fi.Name);
            
            // Try to load cached thumbnail
            Image thumb = TryLoadThumbnail(thumbPath);
            
            // Generate if not found
            if (thumb == null) {
                thumb = GenerateThumbnail(path);
            }
            
            _backgroundPaths.Add(path);
            _thumbnails.Add(thumb);
        }
    }
}</code>

<code>public override void Dispose() {
    // Clean up thumbnails
    if (_thumbnails != null) {
        for (int i = 0; i < _thumbnails.Count; i++) {
            if (_thumbnails[i] != null) {
                _thumbnails[i].Dispose();
            }
        }
        _thumbnails.Clear();
    }
    
    base.Dispose();
}</code>

Possible Causes:

• /Backgrounds directory is empty
• No supported image formats (.png, .jpg, .jpeg, .bmp)
• All files are thumbnails (*_thumb.png)
• Directory doesn't exist in ramdisk

Solutions:

1. Verify Ramdisk/Backgrounds/ contains image files
2. Check file extensions are supported formats
3. Rebuild ISO after adding images
4. Use "Select Background" button to browse manually

Meaning:

The "?" indicator means the thumbnail generation failed for that image.

Common Causes:

• Corrupted image file
• Unsupported PNG/JPG/BMP variant
• File read error
• Insufficient memory for image processing

Solutions:

• Try re-exporting the image in a standard format
• Use PNG or JPG instead of BMP for better compatibility
• Reduce image file size
• Check console output for error messages

Troubleshooting Steps:

1. Check if error notification appears
2. Verify Display Options window closes after click
3. Try clicking a different thumbnail
4. Check available RAM (may be out of memory)
5. Use "Select Background" button as alternative

Causes:

• Many images without cached thumbnails
• Large source images require more processing
• First-time load generates all thumbnails

Solutions:

• Pre-generate thumbnails manually before building ISO
• Reduce number of background images
• Use smaller source images (< 1MB)
• Subsequent opens will be faster (thumbnails cached)

Explanation:

Background images are resized to match the screen resolution. If the aspect ratio differs from the screen, the image will be stretched.

Solutions:

• Use images that match your screen's aspect ratio
• For 16:9 screens: Use 1920×1080, 1280×720, etc.
• For 4:3 screens: Use 1024×768, 800×600, etc.
• Pre-crop images to desired aspect ratio

Enable console output by running guideXOS with -serial stdio in QEMU to see detailed error messages about image loading failures.