Skip to content

Browser capabilities

Every one of these is measured, not guessed. Format support is confirmed by actually encoding a pixel and checking what came back, and the canvas limit is found by allocating until the browser refuses.

This browser

Probing this browser…

Choosing a format from this

Never assume: ask for a preference order and take the best one this browser can actually write.

var caps = await capabilities.GetAsync();

// Never assume: pick the best format this browser can actually write.
var format = caps.ChooseEncodableFormat(
    [ImageFormat.Avif, ImageFormat.WebP, ImageFormat.Jpeg]);

if (!caps.CanRenderCanvas(width, height))
{
    // Work at caps.SuggestedMaxWorkingDimension instead of producing a blank image.
}

Why probe at all

Browsers lie in a specific way: asked to encode a format they cannot write, they silently hand back a PNG. A library that trusted the request would label that PNG as AVIF and corrupt whatever stored it. Bmage encodes a pixel in each candidate format and checks the bytes that came back, and ImageExporter refuses a substitution at export time too - it throws ImageCapabilityException rather than passing it on.

The canvas limit matters as much. Browsers do not expose it, and exceeding it produces a silently blank canvas rather than an error. The probe writes a pixel into progressively smaller canvases until one reads back correctly; CanRenderCanvas(width, height) and SuggestedMaxWorkingDimension are what to check before working at a size. The result is cached for the lifetime of the provider, because it cannot change without a reload.

More on formats, budgets and fallbacks is in Formats.

Where the code is running

Environment says which of the hosts on Hosting models the provider found, so one component can adapt to all of them:

ValueMeaning
BrowserWebAssembly.NET runs in the browser: everything is local, and the probe's answers are this browser's.
BrowserServerInteractive Server or Blazor Hybrid: .NET runs outside the browser and reaches its codecs over JavaScript interop - across the circuit, or the WebView's bridge inside a MAUI app - and pixels cross it.
PrerenderingNo browser yet: the managed set is reported instead of an error. Probe again once interactive.
ServerA headless host: PNG, JPEG, BMP and GIF from the managed codecs, no browser involved.

HardwareConcurrency is also what sizes the pool of Web Workers the browser codecs run in - one per spare core, at most four, unless BitBmageOptions.MaxCodecWorkers says otherwise.

An unhandled error has occurred. Reload 🗙