maplibre_native_ffi/
lib.rs

1//! Safe Rust binding for the MapLibre Native C API.
2//!
3//! Each handle type is the one owner of its native handle: it can't be
4//! cloned, a consuming call such as `release` takes it and hands it back when
5//! native refuses, and `Drop` disposes it. Native keeps a parent alive while
6//! its children need it, so a child owner holds no reference to its parent's.
7//! Handles are any-thread; native rejects a graphics call from the wrong
8//! thread with [`Status::WrongThread`].
9//!
10//! Values that native lends until a call ends borrow what lends them. An
11//! acquired frame's backend textures borrow its [`AcquiredFrameView`], which
12//! keeps them valid until it drops, and a callback's response borrows the
13//! callback. Inputs borrow the caller's text and bytes for the call.
14//!
15//! Native registrations retain their callback closures until they are cleared
16//! or their owner retires. A callback that shares an owner with the host,
17//! through an `Arc`, should capture a `std::sync::Weak` reference to it.
18//! Capturing a strong `Arc` creates a reference cycle that requires an
19//! explicit clear or release.
20//!
21//! The binding contains callback errors and panics and returns a failure value
22//! to native. Failures that no caller can receive go to the reporter that
23//! [`set_reporter`] installs, as [`Report::CallbackError`], or to standard error
24//! when none is installed. A completion conversion panic resolves its future
25//! with an error. A panic also reaches the standard panic hook as usual.
26//!
27//! The `metal`, `opengl`, `vulkan`, and `webgpu` features pick the one render
28//! backend the native library is built with, so they don't combine. Only the
29//! final binary enables one; a library that depends on this crate leaves them
30//! off.
31//!
32//! In the browser, [`RuntimeHandle::create`] returns [`Status::WrongThread`] on the
33//! main thread, and [`NativeFuture::wait`] blocks, so a host runs the binding
34//! on a worker, such as the one Emscripten's `-sPROXY_TO_PTHREAD` provides.
35
36#![deny(unsafe_op_in_unsafe_fn)]
37
38mod abi;
39mod call;
40mod callback;
41mod completion;
42mod convert;
43mod error;
44mod finalize;
45#[allow(clippy::all, dead_code, unused_imports)]
46mod generated;
47mod handle;
48mod ptr;
49mod report;
50mod status;
51mod string;
52
53pub use call::Lent;
54pub use completion::{CommandCompletion, NativeFuture};
55pub use error::{Error, ReleaseError, Result};
56pub use generated::*;
57pub use handle::NativeHandleLeak;
58/// The raw C declarations, which some calls take or return.
59pub use maplibre_native_ffi_sys as sys;
60pub use report::{Report, Reporter, set_reporter};
maplibre_native_ffi/lib.rs

maplibre_native_ffi/
lib.rs
