Native map C API v1

SqsMap native map sessions, memory ownership, threads, and events.

Development native sessions now support common nonzero planar pitch. See native pitched maps for the complete script, capability scope and actual pixel acceptance. Browser and desktop adapters now connect the same scene; see desktop pitched maps.

This page describes development source for high-level map ABI v1. Updated DLL/SO packages have not been released. A local Linux library passed an independent C host on NVIDIA GeForce RTX 4060 / Vulkan; Windows, Android, iOS, and OHOS devices remain unverified. ABI and product versions are separate.

Download the public header, complete C example, and source revision and SHA-256 manifest. A host needs only the header and matching native library; no desktop workbench or internal initialization key is required.

Shared cameras use the Camera API; projection and host-specific scope are documented in the Globe API.

Available scope

Create an empty WGS84 offscreen map, display convenience GeoJSON layers, inspect layer and native view state, resize, change native bearing, capture RGBA pixels, poll events, and destroy the map. Applications implement windows and controls. The default library excludes the interpreter. Enable the optional script feature for one-shot scripts and explicit retained sessions; see native scripting.

The convenience GeoJSON entry uses default drawing and automatic framing. For shared sources, style layers and scripts, use the connected interfaces in Source API, Layer API and native scripting. Check each guide and runtime capabilities for supported types. Shared cameras, globe projection and native style resources have their own entry points. Native scale must not be interpreted as MapLibre zoom.

Functions

This table lists basic entries and selected capability bits, omitting the common sqsm_map_ prefix. See the header and complete ABI reference for all current declarations and flags.

Function	Behavior
`api_version()`	High-level ABI version, currently 1
`runtime_flags()`	Bit 0 indicates a panic-unwind build; bit 1 (SQSM_MAP_SCRIPT) indicates scripts; bit 2 (SQSM_MAP_SCRIPT_SESSIONS) indicates retained sessions; bit 3 (SQSM_MAP_COMMAND_BARRIERS) indicates confirmation; bit 4 (SQSM_MAP_PLANAR_CAMERA) indicates shared planar cameras; bit 5 (SQSM_MAP_HOST_RESOURCES) indicates host resource APIs
`script_api_version()`	Script module version: 0 without the module, 1 when enabled
`script_run_json(map, source, len, out)`	Run a one-shot JavaScript module on the map creation thread and return JSON; disabled builds return CAPABILITY_UNAVAILABLE
`script_session_api_version()`	Retained-session version: 0 without interpreter, 1 when enabled
`script_session_start / pump_json / state_json / stop / release`	Independent bounded subscriptions, owner-thread pumping and terminal cleanup; see native scripting
`last_error()`	Most recent operation error for the calling thread
`create(width, height, out)`	Creates a map with a non-reused 64-bit handle
`destroy(map)`	Synchronously destroys the map on its creation thread
`resize(map, width, height)`	Physical pixel dimensions, each 1–4096
`set_native_bearing(map, bearing)`	Native degrees normalized to 0–360, not the complete shared camera API
`add_geojson(map, data, len, out_layer)`	Parses UTF-8 WGS84 GeoJSON and returns an identity local to that map
`remove_layer(map, layer)`	Removes a convenience layer; missing layers return NOT_FOUND
`set_style_json(map, json, len)`	Set an HTTP(S) style or clear it; see native resources
`resource_requests_json(map, limit, out)`	Retrieve bounded resource requests without consuming them on allocation failure
`resource_response(map, metadata, metadata_len, bytes, len, accepted)`	Return bytes or errors with generation and byte-budget validation
`state_json(map, out)`	UTF-8 state snapshot
`render_rgba(map, out)`	Synchronous GPU readback, tightly packed RGBA8, width × height × 4 bytes
`poll_events_json(map, out)`	Nonblocking event array; an empty queue returns `[]`
`bytes_free(allocation)`	Releases an output allocation identity; 0 is a no-op

Minimal host

#include "sqs_map.h"

int main(void) {
    sqsm_map_t map = 0;
    sqsm_map_bytes_t frame = {0};
    if (sqsm_map_create(256, 256, &map) != SQSM_MAP_OK) return 1;
    int32_t status = sqsm_map_render_rgba(map, &frame);
    if (status == SQSM_MAP_OK) {
        /* Copy frame.len bytes from frame.data into the host display. */
        sqsm_map_bytes_free(frame.allocation);
    }
    sqsm_map_destroy(map);
    return status == SQSM_MAP_OK ? 0 : 1;
}

Build the Linux library and complete example from the core repository:

cargo build --locked -p sqs-map-capi --profile release-capi
cc -std=c11 -Wall -Wextra -Werror \
  crates/sqs-map-capi/examples/map_lifecycle.c \
  -I crates/sqs-map-capi/include -L target/release-capi \
  -lsqs_map -pthread -o map_lifecycle
LD_LIBRARY_PATH=target/release-capi SQS_REQUIRE_GPU=1 ./map_lifecycle

release-capi uses Rust unwinding so ordinary Rust panics become ENGINE_ERROR. The regular abort-based release profile cannot create high-level maps. Invalid C pointers, allocation failure, and process termination are outside recoverable API errors. Existing low-level calling conventions remain available.

Memory, threads, and limits

Map operations run only on the creation thread. Wrong-thread calls return CONFLICT; C function-pointer callbacks and reentrancy are not provided; optional JS listeners are delivered by explicit pump. Destroyed map handles return STALE_HANDLE. Exiting the creation thread releases its maps.
sqsm_map_bytes_t contains a pointer, a 64-bit byte length, and a 64-bit allocation identity. JSON is not null-terminated. Input parsing finishes before return. Callers provide valid aligned pointers that remain alive until return.
Output structures must be unused or previously freed. Failure clears them. Outputs are independent allocations and survive resizing and map destruction. Free each once using allocation, never free(data). Cross-thread reading/freeing requires application synchronization; never read after freeing.
The library owns the thread-local error pointer. Copy it before the next operation and do not free it.
Process limits: 16 maps, 128 outstanding outputs, 256 MiB outstanding output bytes. Each map permits 128 convenience layers. GeoJSON input totals at most 64 MiB; each input permits 16 MiB, 50000 features, and 500000 two-dimensional coordinates within valid WGS84 longitude/latitude ranges.
Map operations are synchronous; optional retained scripts support stop/release but do not preempt native calls. Future asynchronous requests follow the shared contract. Destruction discards unpolled map events without waiting for the host; independently returned buffers remain owned by the host.

State and events

State includes mapInstanceId, increasing sequence, width, height, nativeView, layerCount, layers, software, feedPending, and resources. Native view includes focus, native scale, bearing, and crs. Layer entries include id, name, visible, and featureCount. feedPending is a renderer hint, not a shared resource-ready or idle acknowledgment.

Events contain type and state, ordered by state.sequence, with a historical state snapshot. Alongside basic changes, current notifications cover cameras, resources, attribution and lifecycle events such as render / idle. Relevant events also carry historical payloads such as cameraState, sourceEvent or attributionEvent. See event names for C-to-script name mappings and map lifecycle for readiness semantics.

The queue holds 128 events. When full, the next event-producing operation returns RESOURCE_LIMIT until the host polls. Discrete events are not silently dropped. Polling consumes events only after successfully allocating the output. Rendering can finish before output allocation fails because of the buffer budget; a failed call does not universally imply unchanged map state.

Status	Meaning
0 OK	Success
1 INVALID_ARGUMENT	Invalid arguments, dimensions, UTF-8, or GeoJSON
2 STALE_HANDLE	Expired map, source, layer or output identity
3 CONFLICT	Wrong thread, reentrancy or duplicate resource
4 RESOURCE_LIMIT	Map, data, event, or output budget exceeded
5 ENGINE_ERROR	GPU, rendering, or recoverable internal failure
6 NOT_FOUND	Requested source or layer is absent from this map
7 CAPABILITY_UNAVAILABLE	Module disabled or requested capability not connected
8 CANCELLED	Cancelled script request or typed cancellation exception; inspect retained session state for stop semantics

Status returns use fixed-width integers, independent of compiler enum layout. The v1 structure layout is fixed; extensions require new functions or versioned types. See map script design for shared semantics and subsequent scripting work.

Command barriers and receipts · Current ABI signatures

Attribution queries: runtime flag SQSM_MAP_ATTRIBUTION_QUERIES (8192). Read-only sqsm_map_attributions_json returns complete JSON within64KiB, clearing output on failure. Owned output survives map destruction. See map attribution and the complete C example. Change events are described below.

Attribution event capability bit16384 adds attributionEvent.attributions to the existing event pump. See attribution for changes, budget failures and stop/destruction rules. Retained scripts support the same event; one-shot listeners remain unsupported.