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:
| Value | Meaning |
|---|---|
BrowserWebAssembly | .NET runs in the browser: everything is local, and the probe's answers are this browser's. |
BrowserServer | Interactive 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. |
Prerendering | No browser yet: the managed set is reported instead of an error. Probe again once interactive. |
Server | A 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.