ink_rs/lib.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5//! Rust bindings for [Google Ink](https://github.com/google/ink), the freehand
6//! stroke library behind Android Jetpack Ink.
7//!
8//! Give it sampled pointer events and a brush; get back smoothed, modelled
9//! triangle meshes to draw.
10//!
11//! # How the bindings are put together
12//!
13//! Ink's public API is built on `absl::StatusOr`, `absl::Span` and templates,
14//! none of which cross an FFI boundary directly. So this crate is two layers:
15//!
16//! 1. A small C++ facade (`crates/ink-rs/cc/ink_ffi.h`) that restates the parts
17//! of Ink we use in plain structs, enums and pointers, with C linkage.
18//! 2. This crate, which wraps the generated declarations in owned types with
19//! `Drop`, turns status codes into [`Result`], and swaps Ink's sentinel
20//! values for [`Option`].
21//!
22//! The declarations in between are generated from the header by bindgen and
23//! checked in, so building needs neither bindgen nor libclang.
24//!
25//! Adding to the bindings means adding to the facade first. See
26//! `docs/ink-bindings.md`.
27//!
28//! # Threading
29//!
30//! Ink's types are not thread-safe, and neither are these. [`Brush`],
31//! [`Stroke`] and friends are deliberately neither `Send` nor `Sync`: build and
32//! read a stroke on one thread, and move the plain [`Mesh`] data if another
33//! thread needs it.
34//!
35//! # Example
36//!
37//! ```no_run
38//! use std::time::Duration;
39//!
40//! use ink_rs::{Brush, Color, InProgressStroke, Point, StockBrush, StrokeInput, StrokeInputBatch, ToolType};
41//!
42//! # fn main() -> ink_rs::Result<()> {
43//! let family = StockBrush::PressurePen.family();
44//! let brush = Brush::new(&family, Color::from_packed_rgba(0x1a1a1aff), 4.0, 0.1)?;
45//!
46//! let mut stroke = InProgressStroke::new();
47//! stroke.start(&brush);
48//!
49//! // Feed in pointer events as they arrive.
50//! let inputs = StrokeInputBatch::new(&[
51//! StrokeInput::new(ToolType::Stylus, Point::new(10.0, 10.0), Duration::ZERO)
52//! .with_pressure(0.4),
53//! StrokeInput::new(ToolType::Stylus, Point::new(22.0, 18.0), Duration::from_millis(16))
54//! .with_pressure(0.7),
55//! ])?;
56//! stroke.enqueue_inputs(&inputs, None)?;
57//! stroke.update_shape(Duration::from_millis(16))?;
58//!
59//! // Draw it.
60//! for coat in 0..stroke.coat_count() {
61//! let mesh = stroke.coat_mesh(coat);
62//! println!("{} triangles", mesh.triangle_count());
63//! }
64//!
65//! // Keep it once the pen lifts.
66//! stroke.finish_inputs();
67//! stroke.update_shape(Duration::from_millis(32))?;
68//! let finished = stroke.to_stroke();
69//! # let _ = finished;
70//! # Ok(())
71//! # }
72//! ```
73
74mod brush;
75mod color;
76mod error;
77mod ffi;
78mod geometry;
79mod input;
80mod stroke;
81
82pub use brush::{Brush, BrushFamily, StockBrush};
83pub use color::{Color, ColorFormat, ColorSpace};
84pub use error::{Error, ErrorKind, Result};
85pub use geometry::{Mesh, Point, Rect, Vec2};
86pub use input::{StrokeInput, StrokeInputBatch, ToolType};
87pub use stroke::{InProgressStroke, Stroke};