d2phap/ImageGlass · error · NotSupportedException

Bitmap's dimension is too large. Max is {WEBP_MAX_DIMENSION}

Error message

Bitmap's dimension is too large. Max is {WEBP_MAX_DIMENSION}x{WEBP_MAX_DIMENSION} pixels.

What it means

Thrown by EncodeLossy(Bitmap, int) when the source bitmap's width or height exceeds WEBP_MAX_DIMENSION (16383 pixels), the maximum dimension the libwebp encoder accepts. This is a hard limit enforced by the WebP format itself (the bitstream stores dimensions in 14 bits). The check runs before any native call so it fails fast.

Source

Thrown at v9/Components/ImageGlass.WebP/WebPWrapper.cs:388

        // Encode in webP format
        var rawWebP = EncodeLossy(bmp, quality);

        // Write webP file
        File.WriteAllBytes(pathFileName, rawWebP);
    }

    /// <summary>Lossy encoding bitmap to WebP (Simple encoding API)</summary>
    /// <param name="bmp">Bitmap with the image</param>
    /// <param name="quality">Between 0 (lower quality, lowest file size) and 100 (highest quality, higher file size)</param>
    /// <returns>Compressed data</returns>
    public byte[] EncodeLossy(Bitmap bmp, int quality = 75)
    {
        // test bmp
        if (bmp.Width == 0 || bmp.Height == 0)
            throw new ArgumentException("Bitmap contains no data.", nameof(bmp));

        if (bmp.Width > WEBP_MAX_DIMENSION || bmp.Height > WEBP_MAX_DIMENSION)
            throw new NotSupportedException($"Bitmap's dimension is too large. Max is {WEBP_MAX_DIMENSION}x{WEBP_MAX_DIMENSION} pixels.");

        if (bmp.PixelFormat != PixelFormat.Format24bppRgb && bmp.PixelFormat != PixelFormat.Format32bppArgb)
            throw new NotSupportedException("Only support Format24bppRgb and Format32bppArgb pixelFormat.");

        BitmapData? bmpData = null;
        var unmanagedData = IntPtr.Zero;

        try
        {
            int size;

            // Get bmp data
            bmpData = bmp.LockBits(new Rectangle(0, 0, bmp.Width, bmp.Height), ImageLockMode.ReadOnly, bmp.PixelFormat);

            // Compress the bmp data
            if (bmp.PixelFormat == PixelFormat.Format24bppRgb)
            {
                size = LibWebp.WebPEncodeBGR(bmpData.Scan0, bmp.Width, bmp.Height, bmpData.Stride, quality, out unmanagedData);

View on GitHub (pinned to 4a3c4fecef)

Solutions

Downscale the bitmap so neither dimension exceeds 16383 before calling EncodeLossy (e.g. clone into a smaller Bitmap).
Use the AdvancedEncode path with use_scaling, or pre-resize with Graphics.DrawImage.
Split oversized images into tiles and encode each separately.

Example fix

// before
var bytes = webp.EncodeLossy(hugeBmp, 80);

// after
const int Max = 16383;
int w = hugeBmp.Width, h = hugeBmp.Height;
double scale = Math.Min(1.0, (double)Max / Math.Max(w, h));
using var resized = new Bitmap((int)(w * scale), (int)(h * scale), hugeBmp.PixelFormat);
using (var g = Graphics.FromImage(resized)) { g.DrawImage(hugeBmp, 0, 0, resized.Width, resized.Height); }
var bytes = webp.EncodeLossy(resized, 80);

Defensive patterns

Strategy: validation

Validate before calling

const int WEBP_MAX_DIMENSION = 16383;
if (bmp.Width > WEBP_MAX_DIMENSION || bmp.Height > WEBP_MAX_DIMENSION)
    throw new ArgumentOutOfRangeException(nameof(bmp),
        $"Bitmap {bmp.Width}x{bmp.Height} exceeds WebP max {WEBP_MAX_DIMENSION}x{WEBP_MAX_DIMENSION}.");

Type guard

static bool IsWithinWebPDimensions(Bitmap bmp) =>
    bmp.Width > 0 && bmp.Height > 0 &&
    bmp.Width <= 16383 && bmp.Height <= 16383;

Try / catch

try { var bytes = webp.EncodeLossy(bmp, quality); }
catch (NotSupportedException ex) when (ex.Message.Contains("dimension is too large"))
{ /* downscale and retry, or report */ }

Prevention

Pre-validate every bitmap's dimensions against 16383 before any WebP encode.
Centralize a 'prepare for WebP' helper that resizes and converts pixel format.
Treat dimension/pixel-format validation as a pipeline stage, not an afterthought.

When it happens

Trigger: Calling EncodeLossy(bmp, quality) or Save(bmp, path, quality) with a Bitmap whose Width or Height is greater than 16383. Most often a very large panorama, a tiled image, or an image loaded at a DPI-scaled resolution.

Common situations: Stitching photos into one huge canvas; loading a high-DPI scan; passing a 20000x10000 Bitmap; forgetting that System.Drawing can load bitmaps far larger than WebP can encode.

Related errors

AI-assisted analysis of d2phap/ImageGlass@4a3c4fecef (2026-08-13). Data as JSON: /api/errors/ff63bb3eab992e74. Report an issue: GitHub.