runtime.h

Go to the documentation of this file.

 
#ifndef MAPLIBRE_NATIVE_C_RUNTIME_H
#define MAPLIBRE_NATIVE_C_RUNTIME_H
 
#ifndef __cplusplus
#include <stdbool.h>
#endif
 
#include <stddef.h>
#include <stdint.h>
 
#include "base.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum mln_network_status : uint32_t {
  MLN_NETWORK_STATUS_ONLINE = 1,
  MLN_NETWORK_STATUS_OFFLINE = 2,
} mln_network_status;
 
typedef enum mln_runtime_option_flag : uint32_t {
  MLN_RUNTIME_OPTION_MAXIMUM_CACHE_SIZE = 1U << 0U,
} mln_runtime_option_flag;
 
typedef enum mln_ambient_cache_operation : uint32_t {
  MLN_AMBIENT_CACHE_OPERATION_RESET_DATABASE = 1,
  MLN_AMBIENT_CACHE_OPERATION_PACK_DATABASE = 2,
  MLN_AMBIENT_CACHE_OPERATION_INVALIDATE = 3,
  MLN_AMBIENT_CACHE_OPERATION_CLEAR = 4,
} mln_ambient_cache_operation;
 
typedef int64_t mln_offline_region_id;
 
typedef enum mln_offline_region_definition_type : uint32_t {
  MLN_OFFLINE_REGION_DEFINITION_TILE_PYRAMID = 1,
  MLN_OFFLINE_REGION_DEFINITION_GEOMETRY = 2,
} mln_offline_region_definition_type;
 
typedef enum mln_offline_region_download_state : uint32_t {
  MLN_OFFLINE_REGION_DOWNLOAD_INACTIVE = 0,
  MLN_OFFLINE_REGION_DOWNLOAD_ACTIVE = 1,
} mln_offline_region_download_state;

typedef uint64_t mln_offline_operation_id;

typedef enum mln_offline_operation_kind : uint32_t {
  MLN_OFFLINE_OPERATION_AMBIENT_CACHE = 1,
  MLN_OFFLINE_OPERATION_REGION_CREATE = 2,
  MLN_OFFLINE_OPERATION_REGION_GET = 3,
  MLN_OFFLINE_OPERATION_REGIONS_LIST = 4,
  MLN_OFFLINE_OPERATION_REGIONS_MERGE_DATABASE = 5,
  MLN_OFFLINE_OPERATION_REGION_UPDATE_METADATA = 6,
  MLN_OFFLINE_OPERATION_REGION_GET_STATUS = 7,
  MLN_OFFLINE_OPERATION_REGION_SET_OBSERVED = 8,
  MLN_OFFLINE_OPERATION_REGION_SET_DOWNLOAD_STATE = 9,
  MLN_OFFLINE_OPERATION_REGION_INVALIDATE = 10,
  MLN_OFFLINE_OPERATION_REGION_DELETE = 11,
} mln_offline_operation_kind;

typedef enum mln_offline_operation_result_kind : uint32_t {
  MLN_OFFLINE_OPERATION_RESULT_NONE = 0,
  MLN_OFFLINE_OPERATION_RESULT_REGION = 1,
  MLN_OFFLINE_OPERATION_RESULT_OPTIONAL_REGION = 2,
  MLN_OFFLINE_OPERATION_RESULT_REGION_LIST = 3,
  MLN_OFFLINE_OPERATION_RESULT_REGION_STATUS = 4,
} mln_offline_operation_result_kind;

typedef struct mln_offline_region_status {
  uint32_t size;
  uint32_t download_state;
  uint64_t completed_resource_count;
  uint64_t completed_resource_size;
  uint64_t completed_tile_count;
  uint64_t required_tile_count;
  uint64_t completed_tile_size;
  uint64_t required_resource_count;
  bool required_resource_count_is_precise;
  bool complete;
} mln_offline_region_status;

typedef enum mln_runtime_event_type : uint32_t {
  MLN_RUNTIME_EVENT_MAP_CAMERA_WILL_CHANGE = 1,
  MLN_RUNTIME_EVENT_MAP_CAMERA_IS_CHANGING = 2,
  MLN_RUNTIME_EVENT_MAP_CAMERA_DID_CHANGE = 3,
  MLN_RUNTIME_EVENT_MAP_STYLE_LOADED = 4,
  MLN_RUNTIME_EVENT_MAP_LOADING_STARTED = 5,
  MLN_RUNTIME_EVENT_MAP_LOADING_FINISHED = 6,
  MLN_RUNTIME_EVENT_MAP_LOADING_FAILED = 7,
  MLN_RUNTIME_EVENT_MAP_IDLE = 8,
  MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE = 9,
  MLN_RUNTIME_EVENT_MAP_RENDER_ERROR = 10,
  MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED = 11,
  MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FAILED = 12,
  MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_STARTED = 13,
  MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED = 14,
  MLN_RUNTIME_EVENT_MAP_RENDER_MAP_STARTED = 15,
  MLN_RUNTIME_EVENT_MAP_RENDER_MAP_FINISHED = 16,
  MLN_RUNTIME_EVENT_MAP_STYLE_IMAGE_MISSING = 17,
  MLN_RUNTIME_EVENT_MAP_TILE_ACTION = 18,
  MLN_RUNTIME_EVENT_OFFLINE_REGION_STATUS_CHANGED = 19,
  MLN_RUNTIME_EVENT_OFFLINE_REGION_RESPONSE_ERROR = 20,
  MLN_RUNTIME_EVENT_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED = 21,
  MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED = 22,
  MLN_RUNTIME_EVENT_MAP_CAMERA_TRANSITION_FINISHED = 23,
} mln_runtime_event_type;

typedef enum mln_runtime_event_source_type : uint32_t {
  MLN_RUNTIME_EVENT_SOURCE_RUNTIME = 0,
  MLN_RUNTIME_EVENT_SOURCE_MAP = 1,
} mln_runtime_event_source_type;

typedef enum mln_runtime_event_payload_type : uint32_t {
  MLN_RUNTIME_EVENT_PAYLOAD_NONE = 0,
  MLN_RUNTIME_EVENT_PAYLOAD_RENDER_FRAME = 1,
  MLN_RUNTIME_EVENT_PAYLOAD_RENDER_MAP = 2,
  MLN_RUNTIME_EVENT_PAYLOAD_STYLE_IMAGE_MISSING = 3,
  MLN_RUNTIME_EVENT_PAYLOAD_TILE_ACTION = 4,
  MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_STATUS = 5,
  MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_RESPONSE_ERROR = 6,
  MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_TILE_COUNT_LIMIT = 7,
  MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_OPERATION_COMPLETED = 8,
  MLN_RUNTIME_EVENT_PAYLOAD_CAMERA_TRANSITION_FINISHED = 9,
} mln_runtime_event_payload_type;

typedef enum mln_camera_change_mode : uint32_t {
  MLN_CAMERA_CHANGE_MODE_IMMEDIATE = 0,
  MLN_CAMERA_CHANGE_MODE_ANIMATED = 1,
} mln_camera_change_mode;

typedef enum mln_render_mode : uint32_t {
  MLN_RENDER_MODE_PARTIAL = 0,
  MLN_RENDER_MODE_FULL = 1,
} mln_render_mode;

typedef enum mln_tile_operation : uint32_t {
  MLN_TILE_OPERATION_REQUESTED_FROM_CACHE = 0,
  MLN_TILE_OPERATION_REQUESTED_FROM_NETWORK = 1,
  MLN_TILE_OPERATION_LOAD_FROM_NETWORK = 2,
  MLN_TILE_OPERATION_LOAD_FROM_CACHE = 3,
  MLN_TILE_OPERATION_START_PARSE = 4,
  MLN_TILE_OPERATION_END_PARSE = 5,
  MLN_TILE_OPERATION_ERROR = 6,
  MLN_TILE_OPERATION_CANCELLED = 7,
  MLN_TILE_OPERATION_NULL = 8,
} mln_tile_operation;
 
typedef enum mln_resource_kind : uint32_t {
  MLN_RESOURCE_KIND_UNKNOWN = 0,
  MLN_RESOURCE_KIND_STYLE = 1,
  MLN_RESOURCE_KIND_SOURCE = 2,
  MLN_RESOURCE_KIND_TILE = 3,
  MLN_RESOURCE_KIND_GLYPHS = 4,
  MLN_RESOURCE_KIND_SPRITE_IMAGE = 5,
  MLN_RESOURCE_KIND_SPRITE_JSON = 6,
  MLN_RESOURCE_KIND_IMAGE = 7,
} mln_resource_kind;
 
typedef enum mln_resource_loading_method : uint32_t {
  MLN_RESOURCE_LOADING_METHOD_ALL = 0,
  MLN_RESOURCE_LOADING_METHOD_CACHE_ONLY = 1,
  MLN_RESOURCE_LOADING_METHOD_NETWORK_ONLY = 2,
} mln_resource_loading_method;
 
typedef enum mln_resource_priority : uint32_t {
  MLN_RESOURCE_PRIORITY_REGULAR = 0,
  MLN_RESOURCE_PRIORITY_LOW = 1,
} mln_resource_priority;
 
typedef enum mln_resource_usage : uint32_t {
  MLN_RESOURCE_USAGE_ONLINE = 0,
  MLN_RESOURCE_USAGE_OFFLINE = 1,
} mln_resource_usage;
 
typedef enum mln_resource_storage_policy : uint32_t {
  MLN_RESOURCE_STORAGE_POLICY_PERMANENT = 0,
  MLN_RESOURCE_STORAGE_POLICY_VOLATILE = 1,
} mln_resource_storage_policy;
 
typedef enum mln_resource_response_status : uint32_t {
  MLN_RESOURCE_RESPONSE_STATUS_OK = 0,
  MLN_RESOURCE_RESPONSE_STATUS_ERROR = 1,
  MLN_RESOURCE_RESPONSE_STATUS_NO_CONTENT = 2,
  MLN_RESOURCE_RESPONSE_STATUS_NOT_MODIFIED = 3,
} mln_resource_response_status;
 
typedef enum mln_resource_error_reason : uint32_t {
  MLN_RESOURCE_ERROR_REASON_NONE = 0,
  MLN_RESOURCE_ERROR_REASON_NOT_FOUND = 1,
  MLN_RESOURCE_ERROR_REASON_SERVER = 2,
  MLN_RESOURCE_ERROR_REASON_CONNECTION = 3,
  MLN_RESOURCE_ERROR_REASON_RATE_LIMIT = 4,
  MLN_RESOURCE_ERROR_REASON_OTHER = 5,
} mln_resource_error_reason;
 
typedef enum mln_resource_provider_decision : uint32_t {
  MLN_RESOURCE_PROVIDER_DECISION_PASS_THROUGH = 0,
  MLN_RESOURCE_PROVIDER_DECISION_HANDLE = 1,
} mln_resource_provider_decision;

MLN_API mln_status mln_network_status_get(uint32_t* out_status) MLN_NOEXCEPT;

MLN_API mln_status mln_network_status_set(uint32_t status) MLN_NOEXCEPT;
 
typedef struct mln_runtime_options {
  uint32_t size;
  uint32_t flags;
  const char* asset_path;
  const char* cache_path;
  uint64_t maximum_cache_size;
} mln_runtime_options;

typedef struct mln_rendering_stats {
  uint32_t size;
  double encoding_time;
  double rendering_time;
  int64_t frame_count;
  int64_t draw_call_count;
  int64_t total_draw_call_count;
} mln_rendering_stats;

typedef struct mln_runtime_event_render_frame {
  uint32_t size;
  uint32_t mode;
  bool needs_repaint;
  bool placement_changed;
  mln_rendering_stats stats;
} mln_runtime_event_render_frame;

typedef struct mln_runtime_event_render_map {
  uint32_t size;
  uint32_t mode;
} mln_runtime_event_render_map;

typedef struct mln_runtime_event_style_image_missing {
  uint32_t size;
  const char* image_id;
  size_t image_id_size;
} mln_runtime_event_style_image_missing;

typedef struct mln_tile_id {
  uint32_t overscaled_z;
  int32_t wrap;
  uint32_t canonical_z;
  uint32_t canonical_x;
  uint32_t canonical_y;
} mln_tile_id;

typedef struct mln_runtime_event_tile_action {
  uint32_t size;
  uint32_t operation;
  mln_tile_id tile_id;
  const char* source_id;
  size_t source_id_size;
} mln_runtime_event_tile_action;

typedef struct mln_runtime_event_camera_transition_finished {
  uint32_t size;
  uint64_t transition_id;
} mln_runtime_event_camera_transition_finished;

typedef struct mln_runtime_event_offline_region_status {
  uint32_t size;
  mln_offline_region_id region_id;
  mln_offline_region_status status;
} mln_runtime_event_offline_region_status;

typedef struct mln_runtime_event_offline_region_response_error {
  uint32_t size;
  mln_offline_region_id region_id;
  uint32_t reason;
} mln_runtime_event_offline_region_response_error;

typedef struct mln_runtime_event_offline_region_tile_count_limit {
  uint32_t size;
  mln_offline_region_id region_id;
  uint64_t limit;
} mln_runtime_event_offline_region_tile_count_limit;

typedef struct mln_runtime_event_offline_operation_completed {
  uint32_t size;
  mln_offline_operation_id operation_id;
  uint32_t operation_kind;
  uint32_t result_kind;
  int32_t result_status;
  bool found;
} mln_runtime_event_offline_operation_completed;

typedef struct mln_runtime_event {
  uint32_t size;
  uint32_t type;
  uint32_t source_type;
  void* source;
  int32_t code;
  uint32_t payload_type;
  const void* payload;
  size_t payload_size;
  const char* message;
  size_t message_size;
} mln_runtime_event;
 
typedef struct mln_resource_transform_response {
  uint32_t size;
  const char* url;
  void* context;
} mln_resource_transform_response;

MLN_API mln_status mln_resource_transform_response_set_url(
  mln_resource_transform_response* response, const char* url, size_t url_size
) MLN_NOEXCEPT;

typedef mln_status (*mln_resource_transform_callback)(
  void* user_data, uint32_t kind, const char* url,
  mln_resource_transform_response* out_response
);
 
typedef struct mln_resource_transform {
  uint32_t size;
  mln_resource_transform_callback callback;
  void* user_data;
} mln_resource_transform;
 
typedef struct mln_resource_request {
  uint32_t size;
  const char* url;
  uint32_t kind;
  uint32_t loading_method;
  uint32_t priority;
  uint32_t usage;
  uint32_t storage_policy;
  bool has_range;
  uint64_t range_start;
  uint64_t range_end;
  bool has_prior_modified;
  int64_t prior_modified_unix_ms;
  bool has_prior_expires;
  int64_t prior_expires_unix_ms;
  const char* prior_etag;
  const uint8_t* prior_data;
  size_t prior_data_size;
} mln_resource_request;
 
typedef struct mln_resource_response {
  uint32_t size;
  uint32_t status;
  uint32_t error_reason;
  const uint8_t* bytes;
  size_t byte_count;
  const char* error_message;
  bool must_revalidate;
  bool has_modified;
  int64_t modified_unix_ms;
  bool has_expires;
  int64_t expires_unix_ms;
  const char* etag;
  bool has_retry_after;
  int64_t retry_after_unix_ms;
} mln_resource_response;

typedef uint32_t (*mln_resource_provider_callback)(
  void* user_data, const mln_resource_request* request,
  mln_resource_request_handle* handle
);
 
typedef struct mln_resource_provider {
  uint32_t size;
  mln_resource_provider_callback callback;
  void* user_data;
} mln_resource_provider;

MLN_API mln_runtime_options mln_runtime_options_default(void) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_create(
  const mln_runtime_options* options, mln_runtime** out_runtime
) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_set_resource_provider(
  mln_runtime* runtime, const mln_resource_provider* provider
) MLN_NOEXCEPT;

MLN_API mln_status
mln_runtime_clear_resource_provider(mln_runtime* runtime) MLN_NOEXCEPT;

MLN_API mln_status mln_resource_request_complete(
  mln_resource_request_handle* handle, const mln_resource_response* response
) MLN_NOEXCEPT;

MLN_API mln_status mln_resource_request_cancelled(
  const mln_resource_request_handle* handle, bool* out_cancelled
) MLN_NOEXCEPT;

MLN_API void mln_resource_request_release(
  mln_resource_request_handle* handle
) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_set_resource_transform(
  mln_runtime* runtime, const mln_resource_transform* transform
) MLN_NOEXCEPT;

MLN_API mln_status
mln_runtime_clear_resource_transform(mln_runtime* runtime) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_run_ambient_cache_operation_start(
  mln_runtime* runtime, uint32_t operation,
  mln_offline_operation_id* out_operation_id
) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_offline_operation_discard(
  mln_runtime* runtime, mln_offline_operation_id operation_id
) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_destroy(mln_runtime* runtime) MLN_NOEXCEPT;

MLN_API mln_status
mln_runtime_pump(mln_runtime* runtime, int64_t timeout_ms) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_wake_source_acquire(
  mln_runtime* runtime, mln_wake_source** out_source
) MLN_NOEXCEPT;

MLN_API mln_status mln_wake_source_signal(mln_wake_source* source) MLN_NOEXCEPT;

MLN_API void mln_wake_source_destroy(mln_wake_source* source) MLN_NOEXCEPT;

MLN_API mln_status mln_runtime_poll_event(
  mln_runtime* runtime, mln_runtime_event* out_event, bool* out_has_event
) MLN_NOEXCEPT;
 
#ifdef __cplusplus
}
#endif
 
#endif  // MAPLIBRE_NATIVE_C_RUNTIME_H