Skip to main content

Load images through custom protocols

The common standalone image entry accepts credential-free HTTP(S) or hierarchical custom URLs with a host. Capability customImageLoadURLs describes core validation and decoding; each host must supply its transport. The MapLibre-shaped call remains await map.loadImage(url), returning independent caller-owned RGBA8 pixels without registration.

const result=await map.loadImage('memory://assets/icon.png');
map.addImage('icon',result.data);
await map.sqs.flush();

Browser handlers return encoded PNG/JPEG/WebP bytes and use addProtocol in the map realm; register separately inside a Worker. Native C callers poll Image requests and return bytes using the original URI and generation/id. The desktop application's built-in downloader currently implements HTTP(S); this phase does not add native JavaScript callback registration or a desktop custom downloader.

The existing byte/pixel/eight-resident-result and cancellation/late-response limits remain in image loading. Shared protocol plans apply: custom URLs have no automatic HTTP retry/fallback and default to no-store. Script stop and map destruction cancel owned loads; handlers observe AbortSignal and C callers consume cancel notices. Missing handlers and corrupt files fail instead of yielding placeholder success.

The identical seven-check script and complete page include all handler and Worker registration code; run within the matching SDK directory. Real PNG decoding, repeated independent pixels, explicit registration and typed URL/decode failures run in native retained QuickJS and browser main-thread/Worker with actual rendered icon pixels. A model also checks cancellation and rejected old responses. Style/glyph, native JS registration, mobile GIS/iOS/devices and formal releases remain separate work.

Syntax follows MapLibre loadImage and addProtocol; implementation and decoding use SqsMap's independently developed core.