Crate maplibre_native_ffi

Expand description

Safe Rust binding for the MapLibre Native C API.

Each handle type is the one owner of its native handle: it can’t be cloned, a consuming call such as release takes it and hands it back when native refuses, and Drop disposes it. Native keeps a parent alive while its children need it, so a child owner holds no reference to its parent’s. Handles are any-thread; native rejects a graphics call from the wrong thread with Status::WrongThread.

Values that native lends until a call ends borrow what lends them. An acquired frame’s backend textures borrow its AcquiredFrameView, which keeps them valid until it drops, and a callback’s response borrows the callback. Inputs borrow the caller’s text and bytes for the call.

Native registrations retain their callback closures until they are cleared or their owner retires. A callback that shares an owner with the host, through an Arc, should capture a std::sync::Weak reference to it. Capturing a strong Arc creates a reference cycle that requires an explicit clear or release.

The binding contains callback errors and panics and returns a failure value to native. Failures that no caller can receive go to the reporter that set_reporter installs, as Report::CallbackError, or to standard error when none is installed. A completion conversion panic resolves its future with an error. A panic also reaches the standard panic hook as usual.

The metal, opengl, vulkan, and webgpu features pick the one render backend the native library is built with, so they don’t combine. Only the final binary enables one; a library that depends on this crate leaves them off.

In the browser, RuntimeHandle::create returns Status::WrongThread on the main thread, and NativeFuture::wait blocks, so a host runs the binding on a worker, such as the one Emscripten’s -sPROXY_TO_PTHREAD provides.

Re-exports§

pub use maplibre_native_ffi_sys as sys;

Structs§

AcquiredFrameHandle: Owns one native handle.
AcquiredFrameView: A view scope of AcquiredFrameHandle, which ends when it drops. Its getters lend values that stay valid until then, and its owner can’t be consumed while it lives.
AnchoredMomentum: How a gesture’s zoom, bearing, or pitch keeps changing after release.
AndroidHardwareBufferFrame: The Android hardware buffer of an acquired frame.
AndroidHardwareBufferRingDescriptor: A ring of Android hardware buffers that the library allocates, for MapHandle::attach_android_hardware_buffer_ring().
AndroidSurfaceDescriptor: An Android window to present to, for MapHandle::attach_android_surface().
AndroidSurfaceReplacement: A new Android window for RenderSessionHandle::set_android_surface_target().
AnimationOptions: How a camera change animates.
BoundOptions: Limits on the camera, for MapHandle::set_bounds().
Camera: A map’s whole camera.
CameraBounds: All the limits on a map’s camera.
CameraDelta: A change to the camera from where it is now, for gestures.
CameraFitOptions: Options for finding the camera that fits an area.
CameraFitUpdate: A camera change that fits an area, for MapHandle::fit_camera_to_lat_lng_bounds() and the other fit commands.
CameraOptions: A camera, with only the members that fields selects.
CameraQueryResult: A map’s camera, with the snapshot generation that it matches.
CameraTransitionEnd: The end of a camera change.
CameraTransitionHandler: A callback for the end of a camera change, for AnimationOptions.
CameraUpdate: A camera change for MapHandle::update_camera().
CameraVelocity: How fast each part of a camera change moves.
CanonicalTileId: A tile’s zoom level z, column x, and row y, with row 0 at the north.
CommandCompletion: The generations that a committed command published, which are zero unless it is a map command.
CustomGeometrySourceOptions: The callbacks and options of a custom geometry source.
CustomVectorSourceOptions: The callbacks and options of a custom vector source.
DmaBufFormat: A DRM format and modifier that you can import.
DmaBufFrame: The dmabuf of an acquired frame.
DmaBufPlane: Where one plane of a dmabuf keeps its data.
DmaBufRingDescriptor: A ring of dmabufs that the library allocates, for MapHandle::attach_dma_buf_ring().
DxgiSharedTextureFrame: The DXGI shared texture of an acquired frame.
DxgiSharedTextureRingDescriptor: A ring of DXGI shared textures that the library allocates, for MapHandle::attach_dxgi_shared_texture_ring().
EdgeInsets: Distances in logical pixels from each edge of the map.
EglContextDescriptor: The EGL objects that a render session makes its OpenGL context from.
FeatureStateSelector: The features whose state to set, read, or remove.
FrameDemand: A demand for one frame.
FrameDemandFlag: How a frame demand behaves.
FramePacerHandle: Owns one native handle.
FramePacerOptions: Options for creating a frame pacer.
FreeCamera: A map camera’s whole position and orientation in three dimensions.
FreeCameraOptions: The camera’s position and orientation in three dimensions.
GeoJsonSourceOptions: Options for a GeoJSON [source](https://maplibre.org/maplibre-style-spec/sources/#geojson).
GestureMomentum: How a gesture keeps moving the camera after the user lets go.
GpuSync: A point in GPU work that the other side waits for before using a texture.
GpuSyncKindFlag: A GPU sync kind, as a bit in a set.
HttpHeader: An HTTP header.
HttpHeaderRule: Headers to add to the HTTP requests whose URL matches a pattern.
HttpHeaderTransform: Headers to add to HTTP requests, for RuntimeHandle::set_http_header_transform().
HttpHeaderTransformResponse: A native response borrowed only for one host callback.
ImageContent: The area of an image, in image pixels, that text fits inside.
ImageStretch: A range of image pixels, from from to to, that stretches to fit text.
IoSurfaceFrame: The IOSurface of an acquired frame.
IoSurfaceRingDescriptor: A ring of IOSurfaces that the library allocates, for MapHandle::attach_io_surface_ring().
LatLng: A geographic coordinate, in degrees.
LatLngBounds: A rectangle of coordinates, from its southwest to its northeast corner.
Lent: A value that a view getter lends, valid until its view drops.
LogHandler: A log callback, for set_log_callback().
LogSeverityFlag: A log severity, as a bit in a set.
LogicalExtent: A size in logical pixels, and the physical pixels in each logical pixel.
LogicalSize: A size in logical pixels, which the map’s scale factor turns into pixels.
MapDebugFlag: A debug overlay that the map draws.
MapHandle: Owns one native handle.
MapHandleDiscarding: Submits MapHandle commands without a completion. Each call returns the same acceptance status as its completing form, and native logs a command that later fails as a warning through the log handler.
MapOptions: Options for RuntimeHandle::create_map().
MapProjectionCameraResult: A projection’s camera, as MapProjectionHandle::get_camera() reports it.
MapProjectionHandle: Owns one native handle.
MapSnapshot: A map’s state, as MapHandle::get_snapshot() reads it.
MapTileOptions: How the map picks the tiles to load.
MapTileSettings: All the settings for how a map picks the tiles to load.
MapView: One view of a map: its camera, size, and projection.
MapViewport: A map’s whole viewport.
MapViewportOptions: How the map orients and constrains its view.
MetalBorrowedTexture: A Metal texture of a borrowed ring.
MetalBorrowedTextureDescriptor: A ring of your Metal textures, for MapHandle::attach_metal_borrowed_texture().
MetalBorrowedTextureReplacement: New Metal textures for a borrowed ring, for RenderSessionHandle::set_metal_borrowed_texture_target().
MetalContextDescriptor: The Metal device that a render session uses.
MetalSurfaceDescriptor: A Metal layer to render to, for MapHandle::attach_metal_surface().
MetalSurfaceReplacement: A new Metal layer for RenderSessionHandle::set_metal_surface_target().
MetalTextureFrame: The Metal texture of an acquired frame.
MomentumDecay: How one part of a gesture’s momentum slows from its release speed.
MomentumSnap: Where a part settles after a gesture that changed it.
NativeFuture: A one-shot native completion exposed as a Rust future.
NativeHandleLeak: A native handle a destructor attempted to destroy and could not. The handle stays live.
OfflineGeometryRegionDefinition: An offline region that covers a GeoJSON geometry.
OfflineRegionInfo: An offline region in the runtime’s cache file.
OfflineRegionStatus: The download progress of an offline region.
OfflineTilePyramidRegionDefinition: An offline region that covers a rectangle of the map.
OffscreenDescriptor: The image that MapHandle::attach_offscreen() renders. The session renders it at the map’s scale factor.
OffscreenDeviceHandle: Owns one native handle.
OffscreenDeviceOptions: Options for OffscreenDeviceHandle::create().
OhosSurfaceDescriptor: An OpenHarmony window to present to, for MapHandle::attach_ohos_surface().
OhosSurfaceReplacement: A new OpenHarmony window for RenderSessionHandle::set_ohos_surface_target().
OpenGlBorrowedTexture: An OpenGL texture of a borrowed ring.
OpenGlBorrowedTextureDescriptor: A ring of your OpenGL textures, for MapHandle::attach_open_gl_borrowed_texture().
OpenGlBorrowedTextureReplacement: New OpenGL textures for a borrowed ring, for RenderSessionHandle::set_open_gl_borrowed_texture_target().
OpenGlContextDescriptor: How a render session gets the OpenGL context that it renders with.
OpenGlContextProviderFlag: An OpenGL context platform, as a bit in a set.
OpenGlSurfaceDescriptor: An OpenGL surface to present to, for MapHandle::attach_open_gl_surface().
OpenGlSurfaceReplacement: A new OpenGL surface for RenderSessionHandle::set_open_gl_surface_target().
OpenGlTextureFrame: The OpenGL texture of an acquired frame.
PanMomentum: How a gesture’s pan keeps moving the map’s content after release.
PremultipliedRgba8Image: An image of 8-bit RGBA pixels whose colors are multiplied by their alpha.
ProjectedMeters: A point in the Web Mercator projection, in meters.
ProjectionMode: A map’s whole projection mode.
ProjectionModeOptions: Settings that skew the map or draw it without perspective.
Quaternion: A rotation, as a quaternion.
QueueLock: Your lock on a Vulkan queue that you and a render session both submit to.
ReleaseError: A consuming call that native refused, such as a release while a child handle is still live. It hands the handle back, so the caller can retry or drop it.
RenderAbandonResult: The outcome of RenderSessionHandle::abandon().
RenderBackendFlag: A render backend, as a bit in a set.
RenderFrameResult: How one frame demand finished.
RenderSessionAttachOptions: Options for attaching a render session to a map.
RenderSessionCapabilities: What an attached render session supports.
RenderSessionCapabilityFlag: Something that a render session can do.
RenderSessionHandle: Owns one native handle.
RenderSessionHandleDiscarding: Submits RenderSessionHandle commands without a completion. Each call returns the same acceptance status as its completing form, and native logs a command that later fails as a warning through the log handler.
RenderSessionSnapshot: The state of a render session at one moment.
RenderedFeature: A feature that a rendered feature query found.
RenderedFeatureQueryOptions: Options for a rendered feature query.
RenderingStats: Statistics about the frames that a map renders.
ResourceKindFlag: A resource kind, as a bit in a set.
ResourceProvider: A resource provider, for RuntimeHandle::set_resource_provider().
ResourceRange: The bytes from start to end of a resource, both included.
ResourceRequestCancelHandler: A cancel callback, for ResourceRequestHandle::set_cancel_callback().
ResourceRequestHandle: Owns one native handle.
ResourceRequestInfo: A request that a resource provider serves.
ResourceResponse: The answer to a resource request.
ResourceRoute: The requests that a resource provider serves.
ResourceTransform: How to rewrite request URLs, for RuntimeHandle::set_resource_transform().
ResourceTransformError: Why a resource transform fails a request.
ResourceTransformRequestHandle: Owns one native handle.
ResourceTransformRule: Query parameters to add to the URLs of requests that match a pattern.
RetiringRenderSession: What a release of RenderSessionHandle leaves while native retires the handle. Its functions stay callable until the handle retires, and fail with Status::InvalidState afterwards. It owns nothing, so dropping it changes nothing.
RuntimeEvent: An event that a runtime or one of its maps raised.
RuntimeEventCameraChange: The details of RuntimeEventType::MapCameraWillChange and RuntimeEventType::MapCameraDidChange.
RuntimeEventFlag: An event type, as a bit in a set.
RuntimeEventGlyphs: The details of a glyph event.
RuntimeEventHandler: An event callback, for RuntimeHandle::set_event_handler().
RuntimeEventLoadingFailed: The details of RuntimeEventType::MapLoadingFailed.
RuntimeEventOfflineRegionResponseError: The details of RuntimeEventType::OfflineRegionResponseError.
RuntimeEventOfflineRegionStatus: The details of RuntimeEventType::OfflineRegionStatusChanged.
RuntimeEventOfflineRegionTileCountLimit: The details of RuntimeEventType::OfflineRegionTileCountLimitExceeded.
RuntimeEventRenderFrame: The details of RuntimeEventType::MapRenderFrameFinished.
RuntimeEventSourceChanged: The details of RuntimeEventType::MapSourceChanged.
RuntimeEventSprite: The details of a sprite event.
RuntimeEventStyleImage: The details of RuntimeEventType::MapStyleImageMissing.
RuntimeEventTileAction: The details of RuntimeEventType::MapTileAction.
RuntimeHandle: Owns one native handle.
RuntimeHandleDiscarding: Submits RuntimeHandle commands without a completion. Each call returns the same acceptance status as its completing form, and native logs a command that later fails as a warning through the log handler.
RuntimeOptions: Options for RuntimeHandle::create().
ScreenBox: A rectangle of the screen, from its min corner to its max corner.
ScreenLineString: A line through points on the screen.
ScreenPoint: A point on the screen, in logical pixels from the map’s top-left corner.
SourceFeature: A feature that a source feature query found.
SourceFeatureQueryOptions: Options for a source feature query.
StyleExpressionHandle: Owns one native handle.
StyleExpressionInfo: What a style expression’s result depends on.
StyleExpressionInputs: The inputs that a style expression reads while it evaluates.
StyleExpressionOptions: Options for parsing a style expression.
StyleExpressionType: The type of a style expression’s result.
StyleImageInfo: An image in the map’s style.
StyleImageOptions: Options for a style image, as the [sprite](https://maplibre.org/maplibre-style-spec/sprite/) spec describes them.
StyleLayerInfo: A layer in the map’s style.
StyleSourceInfo: A source in the map’s style.
StyleSourceTileInfo: The tiles of a source, as the style lists them.
StyleTransitionOptions: The default [transition](https://maplibre.org/maplibre-style-spec/transition/) for changes to a style’s paint properties.
TextureImageInfo: The layout of the pixels that RenderSessionHandle::read_texture() reads.
TextureReadbackResult: The pixels that RenderSessionHandle::read_texture() reads.
TileId: The ID of a tile.
UnitBezier: A timing curve from (0, 0) to (1, 1), with the control points (x1, y1) and (x2, y2).
UrlMatchFlag: How a URL pattern matches a request’s URL.
UrlQueryParameter: A query parameter that a resource transform rule adds to a URL.
Vec3: A vector in three dimensions.
VulkanBorrowedTexture: A Vulkan image of a borrowed ring.
VulkanBorrowedTextureDescriptor: A ring of your Vulkan images, for MapHandle::attach_vulkan_borrowed_texture().
VulkanBorrowedTextureReplacement: New Vulkan images for a borrowed ring, for RenderSessionHandle::set_vulkan_borrowed_texture_target().
VulkanContextDescriptor: The Vulkan device and queue that a render session uses.
VulkanDeviceContextResult: A Vulkan device’s context, as VulkanDeviceHandle::get_context() reports it.
VulkanDeviceHandle: Owns one native handle.
VulkanDeviceOptions: Options for VulkanDeviceHandle::create().
VulkanSurfaceDescriptor: A Vulkan surface to present to, for MapHandle::attach_vulkan_surface().
VulkanSurfaceReplacement: A new Vulkan surface for RenderSessionHandle::set_vulkan_surface_target().
VulkanTextureFrame: The Vulkan image of an acquired frame.
Wake: A callback that tells the caller when work is ready.
WaylandSurfaceDescriptor: A Wayland surface to present to, for MapHandle::attach_wayland_surface().
WaylandSurfaceReplacement: A new Wayland surface for RenderSessionHandle::set_wayland_surface_target().
WebGlContextDescriptor: The WebGL context or canvas that a render session uses.
WebGpuBorrowedTexture: A WebGPU texture of a borrowed ring.
WebGpuBorrowedTextureDescriptor: A ring of your WebGPU textures, for MapHandle::attach_web_gpu_borrowed_texture().
WebGpuBorrowedTextureReplacement: New WebGPU textures for a borrowed ring, for RenderSessionHandle::set_web_gpu_borrowed_texture_target().
WebGpuContextDescriptor: The WebGPU device that a render session uses.
WebGpuSurfaceDescriptor: A WebGPU surface to present to, for MapHandle::attach_web_gpu_surface().
WebGpuSurfaceReplacement: A new WebGPU surface for RenderSessionHandle::set_web_gpu_surface_target().
WebGpuTextureFrame: The WebGPU texture of an acquired frame.
WglContextDescriptor: The WGL objects that a render session makes its OpenGL context from.
Win32WindowDescriptor: A Win32 window to present to, for MapHandle::attach_win32_window().
Win32WindowReplacement: A new Win32 window for RenderSessionHandle::set_win32_window_target().

Enums§

CacheDatabaseOperation: A maintenance action on a runtime’s cache database.
CameraChangeMode: Whether a camera change jumps or animates.
CameraChangeSource: What moved the camera.
CameraTransitionOutcome: How a camera change ended.
CameraUpdateMode: How a camera command moves the camera.
ConstrainMode: How the map keeps the camera within the world or within its bounds.
Error: A failure that native or this binding reports.
FeatureId: The ID of a feature in a source, as the source’s data gives it.
GesturePhase: Where a camera change falls in a gesture that the user makes.
GpuSyncKind: How one side waits for the other’s GPU work on a shared texture.
LogEvent: The part of the library that logged a message.
LogSeverity: The severity of a log message.
MapLoadError: Why a map failed to load a style.
MapMode: When a map renders.
MomentumDecayModel: How a part of a gesture’s momentum slows from its release speed.
NetworkStatus: Whether the library may use the network.
NorthOrientation: The screen direction that north points to when the bearing is 0.
OfflineRegionDefinition: The area, zoom range, and style that an offline region covers.
OfflineRegionDownloadState: Whether an offline region is downloading.
OpenGlClientApi: The OpenGL API that a context renders with.
OpenGlContextDescriptorData: The WGL, EGL, or WebGL part of an OpenGL context descriptor.
OpenGlContextOwnership: Whether a render session’s OpenGL context shares objects with yours.
RenderAbandonDisposition: What RenderSessionHandle::abandon() did with a session’s graphics objects.
RenderDriverKind: The thread that runs a render session’s graphics work.
RenderMode: Whether a frame drew the map complete, or lacked resources that are still loading.
RenderResult: How a frame demand finished.
RenderSessionState: Where a render session is in its life.
RenderedQueryGeometry: The screen area that a rendered feature query covers.
Report: A failure that the binding contained because no caller could receive it.
ResourceErrorReason: Why a resource request failed.
ResourceKind: The kind of a resource that the library loads.
ResourceLoadingMethod: Where a request may load its resource from.
ResourcePriority: The priority of a resource request.
ResourceResponseStatus: The outcome of a resource request.
ResourceStoragePolicy: Whether the library keeps a loaded resource in its cache.
ResourceUsage: Whether a request loads a resource for a map or an offline region.
RuntimeEventPayload: The details of an event, in the member that its payload_type names.
RuntimeEventSourceType: The kind of handle that raised an event.
RuntimeEventType: The kind of an event.
Status: The result of a call or of asynchronous work.
StyleExpressionTypeKind: The type of a style expression’s result, or of the items of an array result.
StyleImageTextFit: How an image stretches to fit text along one axis.
StyleLayerVisibility: Whether a layer shows.
StyleRasterDemEncoding: How a raster DEM tile encodes elevation in its colors.
StyleSourceType: The type of a style source.
StyleTileScheme: Whether a tileset counts tile rows from the north (XYZ) or the south (TMS).
StyleVectorTileEncoding: The format of vector tiles.
TileLodMode: How the map picks the level of detail of its tiles.
TileOperation: A step in loading a tile.
ViewportMode: The vertical direction of the image that the map renders.
VulkanImageOwner: The queue family that a borrowed image goes to after each frame.
WebGlContextKind: How a render session gets its WebGL context.

Constants§

DIAGNOSTIC_MESSAGE_CAPACITY: The size of a diagnostic message in bytes, with its terminator.
FRAME_DEMAND_TOKEN_STILL_IMAGE: The token of the frame results that a session adds when it renders an image for MapHandle::request_still_image(). Your own demands can’t use it.
TEXTURE_RING_MAX_DEPTH: The most textures that a render session’s texture ring can have.
VULKAN_NON_DISPATCHABLE_HANDLE_NULL: The null Vulkan non-dispatchable handle.

Functions§

c_version: Returns the API epoch of the library.
camera_for_tile: Computes the camera that shows exactly one tile on a square map.
clear_log_callback: Sends log messages to the platform’s log again, instead of a callback.
get_network_status: Reads whether the library may use the network.
get_plugin_register_function_v1: Returns the function that registers a plugin’s style layer types.
lat_lng_for_projected_meters: Converts meters in the Web Mercator projection to a coordinate.
logical_extent_physical_size: Computes the size in pixels of a target with a logical size and scale factor.
open_gl_supported_context_provider_mask: Reports the OpenGL context platforms that this build of the library has.
projected_meters_for_lat_lng: Converts a coordinate to meters in the Web Mercator projection.
set_log_async_severity_mask: Selects the severities that the library logs on a background thread.
set_log_callback: Sends the log messages of every runtime in the process to a callback.
set_network_status: Tells the library whether it may use the network.
set_reporter: Installs the process-wide reporter, replacing any previous one, and returns whether one was installed. With no reporter, each report goes to standard error.
supported_render_backend_mask: Returns the render backends that this build of the library draws with.

Type Aliases§

Reporter: Receives each Report.
Result