Native library quick start

Choose the right interface

This guide is for developers embedding sqs-map in their own applications. The library supplies map rendering and interaction; it does not automatically provide broad local GIS processing, accounts, or an application workbench. To run scripts inside SqsMap, use the Script API.

Prepare matching files

Use the public header, a native library for your target platform, and any linker files required by your toolchain from the same version. Check the revision and SHA-256 manifest and ABI signature reference. The current public attachments are marked as development source, not evidence of a released binary package.

On Windows, the runtime must locate a DLL with the matching architecture, and linker files must match the toolchain. On Linux, the dynamic loader must locate the shared library. Successful header compilation does not establish correct library, GPU driver, or runtime deployment.

Minimal program

Save this as hello_map.c. It creates a blank 256×256 offscreen map, synchronously reads RGBA8 pixels, and releases the allocation and map on one thread. It does not create a window or automatically load an online basemap.

#include "sqs_map.h"
#include <stdio.h>

int main(void) {
    if (sqsm_map_api_version() != 1 ||
        !(sqsm_map_runtime_flags() & SQSM_MAP_UNWIND_SESSION)) {
        fprintf(stderr, "A matching ABI v1 release-capi library is required.\n");
        return 1;
    }
    sqsm_map_t map = 0;
    int32_t status = sqsm_map_create(256, 256, &map);
    if (status != SQSM_MAP_OK) {
        fprintf(stderr, "create: %s\n", sqsm_map_last_error());
        return 1;
    }
    sqsm_map_bytes_t frame = {0};
    status = sqsm_map_render_rgba(map, &frame);
    int failed = status != SQSM_MAP_OK;
    if (failed) {
        fprintf(stderr, "render: %s\n", sqsm_map_last_error());
    } else {
        printf("RGBA bytes: %llu\n", (unsigned long long)frame.len);
        /* Copy frame.data[0..frame.len) before releasing it. */
    }
    if (sqsm_map_bytes_free(frame.allocation) != SQSM_MAP_OK) {
        fprintf(stderr, "free: %s\n", sqsm_map_last_error());
        failed = 1;
    }
    if (sqsm_map_destroy(map) != SQSM_MAP_OK) {
        fprintf(stderr, "destroy: %s\n", sqsm_map_last_error());
        failed = 1;
    }
    return failed;
}

Success produces 262144 bytes (256×256×4). To display the image, copy the bytes into host-owned image or texture storage before releasing the allocation. Do not retain frame.data after release.

Linux source build

Run the following in the matching sqs-map core repository, with hello_map.c in its root:

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

High-level maps require the unwind-preserving release-capi profile; an abort-based build is not a substitute. If GPU initialization fails, inspect the error, device, and driver. Validate execution separately on each target platform.

Complete examples

• map_lifecycle.c: validates isolated maps, GeoJSON loading, pixel readback, events, thread ownership, and allocation lifetime.
• map_resources.c: demonstrates resource requests and responses using an offline style; you supply the real HTTP client.

The lifecycle program intentionally triggers errors and assertions; it is not an application main loop. Link it with -pthread on Linux. Without a usable GPU it normally returns 77; setting SQS_REQUIRE_GPU=1 turns this into failure. A skipped run is not GPU acceptance.

Continue with Host loop and resource management, then add style resources, pointer input, and display density as needed.