Table of Contents

Class MaplibreNative

Namespace
Maplibre.NativeFfi
Assembly
Maplibre.NativeFfi.dll

Process-global MapLibre Native FFI entry points.

public static class MaplibreNative
Inheritance
MaplibreNative
Inherited Members

Remarks

A handle that the collector reclaims before it is released or disposed is reported as a leak through TraceWarning(string), or on standard error when the host has added no trace listener.

Fields

DiagnosticMessageCapacity

The size of a diagnostic message in bytes, with its terminator.

public const uint DiagnosticMessageCapacity = 4096

Field Value

uint

Remarks

See MLN_DIAGNOSTIC_MESSAGE_CAPACITY in the C API reference.

FrameDemandTokenStillImage

The token of the frame results that a session adds when it renders an image for MapHandle.RequestStillImageAsync(). Your own demands can't use it.

public const ulong FrameDemandTokenStillImage = 18446744073709551615

Field Value

ulong

Remarks

See MLN_FRAME_DEMAND_TOKEN_STILL_IMAGE in the C API reference.

TextureRingMaxDepth

The most textures that a render session's texture ring can have.

public const uint TextureRingMaxDepth = 8

Field Value

uint

Remarks

See MLN_TEXTURE_RING_MAX_DEPTH in the C API reference.

VulkanNonDispatchableHandleNull

The null Vulkan non-dispatchable handle.

public const ulong VulkanNonDispatchableHandleNull = 0

Field Value

ulong

Remarks

See MLN_VULKAN_NON_DISPATCHABLE_HANDLE_NULL in the C API reference.

Methods

AndroidFramePacerCreate(FramePacerOptions?)

Creates a frame pacer that follows the display through the calling thread's AChoreographer.

public static FramePacerHandle AndroidFramePacerCreate(FramePacerOptions? options = null)

Parameters

options FramePacerOptions

Returns

FramePacerHandle

Remarks

Call it on a thread with an ALooper, such as the app's main thread, and keep that thread running its looper while sessions use the pacer.

See mln_android_frame_pacer_create in the C API reference.

Errors:

  • Status.InvalidState when the calling thread has no ALooper.

AppleFramePacerCreate(FramePacerOptions?)

Creates a frame pacer that follows the display through a CADisplayLink.

public static FramePacerHandle AppleFramePacerCreate(FramePacerOptions? options = null)

Parameters

options FramePacerOptions

Returns

FramePacerHandle

Remarks

You can call it on any thread. The pacer needs no run loop of yours. On macOS, it follows the main display, the one with the menu bar.

With FramePacerOptions.MaximumFramesPerSecond, the pacer also asks the system for that refresh rate. On iPhone, a rate above 60 needs CADisableMinimumFrameDurationOnPhone in the app's Info.plist.

See mln_apple_frame_pacer_create in the C API reference.

Errors:

  • Status.NativeError when the system has no display to follow.

CVersion()

Returns the API epoch of the library.

public static uint CVersion()

Returns

uint

Remarks

Headers and a library with different epochs aren't compatible.

See mln_c_version in the C API reference.

CameraForTile(CanonicalTileId, LogicalSize)

Computes the camera that shows exactly one tile on a square map.

public static CameraOptions CameraForTile(CanonicalTileId tile, LogicalSize logicalSize)

Parameters

tile CanonicalTileId
logicalSize LogicalSize

Returns

CameraOptions

Remarks

Jump a map in MapMode.Tile to the camera to render tile, where logicalSize is the map's size. The camera centers the tile, zooms until the tile fills the map, and looks straight down with north up and no padding. The map keeps its camera within its zoom limits, so for a deep tile, raise the maximum zoom past the camera's with MapHandle.SetBoundsAsync().

See mln_camera_for_tile in the C API reference.

Errors:

  • Status.InvalidArgument when logicalSize isn't square, or is wider than 512 pixels. For denser tiles, raise the map's scale factor instead.
  • Status.InvalidArgument when tile.x or tile.y isn't less than 2 to the power tile.z, or when the tile can't fill the map at a zoom from 0 to 25.5, as for tile 0/0/0 on a 256-pixel map.

ClearLogCallback()

Sends log messages to the platform's log again, instead of a callback.

public static void ClearLogCallback()

Remarks

See mln_log_clear_callback in the C API reference.

GetNetworkStatus()

Reads whether the library may use the network.

public static NetworkStatus GetNetworkStatus()

Returns

NetworkStatus

Remarks

See mln_network_get_status in the C API reference.

GetPluginRegisterFunctionV1()

Returns the function that registers a plugin's style layer types.

public static NativePointer GetPluginRegisterFunctionV1()

Returns

NativePointer

Remarks

Pass the function to the plugin's registration entry point before loading a style that uses the plugin's layer types. Plugin callbacks run on library threads and can keep running while the process exits, so they must not use state that the process destroys at exit.

See mln_plugin_get_register_function_v1 in the C API reference.

InitAndroid(NativePointer, NativePointer)

Gives the library the Java VM and the app context that it needs on Android.

public static void InitAndroid(NativePointer jniEnv, NativePointer context)

Parameters

jniEnv NativePointer
context NativePointer

Remarks

Call it before creating a runtime. jniEnv is the calling thread's JNIEnv*, and context is an Android Context, such as the application.

See mln_android_init in the C API reference.

LatLngForProjectedMeters(ProjectedMeters)

Converts meters in the Web Mercator projection to a coordinate.

public static LatLng LatLngForProjectedMeters(ProjectedMeters meters)

Parameters

meters ProjectedMeters

Returns

LatLng

Remarks

See mln_lat_lng_for_projected_meters in the C API reference.

LoadNativeLibrary()

Loads the native library and checks its C ABI version. The library is the one that .NET's native library probing finds, such as a runtime package's.

public static void LoadNativeLibrary()

LoadNativeLibrary(string)

Loads the native library from an exact file path. Call it before any other native call, which otherwise loads the library through LoadNativeLibrary().

public static void LoadNativeLibrary(string libraryPath)

Parameters

libraryPath string

LogicalExtentPhysicalSize(LogicalExtent)

Computes the size in pixels of a target with a logical size and scale factor.

public static (uint Width, uint Height) LogicalExtentPhysicalSize(LogicalExtent extent)

Parameters

extent LogicalExtent

Returns

(uint Width, uint Height)

Remarks

See mln_logical_extent_physical_size in the C API reference.

OpenGlSupportedContextProviderMask()

Reports the OpenGL context platforms that this build of the library has.

public static OpenGlContextProviderFlag OpenGlSupportedContextProviderMask()

Returns

OpenGlContextProviderFlag

Remarks

See mln_open_gl_supported_context_provider_mask in the C API reference.

ProjectedMetersForLatLng(LatLng)

Converts a coordinate to meters in the Web Mercator projection.

public static ProjectedMeters ProjectedMetersForLatLng(LatLng coordinate)

Parameters

coordinate LatLng

Returns

ProjectedMeters

Remarks

See mln_projected_meters_for_lat_lng in the C API reference.

SetLogAsyncSeverityMask(LogSeverityFlag)

Selects the severities that the library logs on a background thread.

public static void SetLogAsyncSeverityMask(LogSeverityFlag mask)

Parameters

mask LogSeverityFlag

Remarks

The library logs other severities on the thread that logged them. mask applies to every runtime in the process.

See mln_log_set_async_severity_mask in the C API reference.

SetLogCallback(LogHandler)

Sends the log messages of every runtime in the process to a callback.

public static void SetLogCallback(LogHandler handler)

Parameters

handler LogHandler

Remarks

The callback replaces the one set before.

Runs on the thread that logged the message, or on a background thread for the severities that MaplibreNative.SetLogAsyncSeverityMask() selects. The callback can't call the library.

See mln_log_set_callback in the C API reference.

SetNetworkStatus(NetworkStatus)

Tells the library whether it may use the network.

public static void SetNetworkStatus(NetworkStatus status)

Parameters

status NetworkStatus

Remarks

While the status is NetworkStatus.Offline, the library starts no network requests. The requests that wait start when the status returns to NetworkStatus.Online. The status starts as online and applies to every runtime in the process.

See mln_network_set_status in the C API reference.

SupportedRenderBackendMask()

Returns the render backends that this build of the library draws with.

public static RenderBackendFlag SupportedRenderBackendMask()

Returns

RenderBackendFlag

Remarks

See mln_supported_render_backend_mask in the C API reference.

Events

CallbackException

Raised when a native callback throws, or when the binding cannot convert a callback's arguments. Native cannot receive the exception, so it receives the callback's failure value instead. With no handler, the binding writes the exception to standard error.

public static event EventHandler<CallbackExceptionEventArgs>? CallbackException

Event Type

EventHandler<CallbackExceptionEventArgs>

Remarks

A handler runs on the native thread that called the callback, before native continues, so it should return quickly. The binding refuses every native call that a handler makes with InvalidOperationException. An exception that a handler throws is discarded.