Native styles and resource hosts

Load styles through the C ABI or built-in scripts while the host supplies resource bytes.

Native libraries and browsers share SqsMap style compilation, TileJSON, vector-tile and glyph decoding, and basemap rendering. The native library does not implement HTTP. The host supplies networking, caching, timeouts, retries, and authorization. This page describes development source; updated binary packages have not been released.

Download the complete C host, native script, header, and revision manifest. The C example uses an owned offline background fixture and demonstrates requests, responses, and real RGBA readback. Applications supply actual HTTP.

Set a style

Check SQSM_MAP_HOST_RESOURCES (32) in sqsm_map_runtime_flags(). The ABI remains version 1, retaining existing symbols and layouts.

const char *request = "{\"style\":\"https://tiles.openfreemap.org/styles/bright\",\"options\":{\"diff\":false}}";
int32_t status = sqsm_map_set_style_json(map, (const uint8_t *)request,
                                        strlen(request));

Include <string.h>. style is an HTTP(S) URL of at most 4096 bytes, without user information, or null to clear the basemap. options is optional and currently supports only diff:false. Inline styles and diff:true explicitly report capability unavailable. Input JSON is limited to 64 KiB.

Loading a style switches display to Mercator; clearing it restores WGS84 display. Center, zoom, bearing, padding, and existing convenience GeoJSON are retained. The basemap renders below business layers. Invalid parameters preserve current state. Download or compilation failure retains the previously published basemap. Native scale is not MapLibre zoom.

Download and respond

Call sqsm_map_resource_requests_json(map, limit, &out) on the map creation thread, with limit from 1 to 32. Copy successful JSON output and release it with sqsm_map_bytes_free(out.allocation). Output allocation failure does not consume requests.

[{"id":0,"generation":"1","url":"https://example.com/style.json",
  "resource":{"resourceType":"Style","maxBytes":4194304,
              "coreGeneration":"1","viewEpoch":"0","source":null}}]

Respond with the outer generation and id. The inner descriptor generation belongs to the basemap session and must not replace the outer map identity. Use the actual resource type and byte budget. Enforce the budget while streaming the download.

uint32_t accepted = 0;
const char *metadata = "{\"generation\":\"1\",\"id\":0}";
int32_t status = sqsm_map_resource_response(map,
    (const uint8_t *)metadata, strlen(metadata), bytes, byte_count, &accepted);

Supply downloaded bytes on success. On failure, use metadata such as {"generation":"1","id":0,"error":"HTTP 503"} and an empty body. Error text must be nonempty and at most 1024 bytes. Identity and size are validated before body copying: the global maximum is64MiB, and individual requests enforce smaller budgets (GeoJSON8MiB,images4MiB,ordinary MP4/H.264 video64MiB). Oversized bodies report a resource-limit error; the same request can subsequently receive a failure response. Unknown, duplicate, and obsolete callbacks return success with accepted=0, without copying bytes. Accepted responses set accepted=1. Destroyed handles report a stale-handle error.

Downloads may run on worker threads, but map calls and responses must return to the creation thread. Cancel matching I/O after style replacement or destruction. Rejecting old callbacks does not cancel host network operations. Send credentials only to explicitly allowed final origins. Each basemap retains at most 32 download or completed-response slots; eventually answer delivered requests with success or failure to avoid exhausting the queue.

Progress and state

render_rgba advances decoding and basemap rendering. The first style request is available without rendering first. Read resources in state_json: generation, pending, styleUrl, attribution, message, and repaintAfterMs. Follow repaint hints and display the actual source attribution. The host must follow network-provider terms.

Setting a style emits sqs.resourceschange. Retained script subscriptions are independent of host event polling. Observe download progress through state and rendering. Complete style.load, sourcedata, and idle events remain under development; a command barrier does not mean all resources are ready.

Optional native script

import { map } from 'sqsmap';
map.setStyle('https://tiles.openfreemap.org/styles/bright', { diff: false });
await map.sqs.flush();
export default (await map.sqs.state()).resources;

With the script feature enabled, one-shot and retained entries use the same syntax. Script completion does not destroy the map-owned basemap. The C host still supplies downloads. This is the standalone native script module; application web and desktop facades support the same URL/clear syntax; see style scripts. The mobile host remains under development.

Linux RTX 4060 / Vulkan verification covers basemap/business-layer composition, TileJSON/MVT/glyph loading, text pixels, rollback, obsolete callbacks, output budgets, and both QuickJS entries. It does not verify external HTTP, Windows/macOS, mobile devices, or complete 3D styles.

For bounded retries, fallback URLs and captured request plans, see native resource policies. Hosts still execute networking.