takumi 2.0.0-beta.2

Render UI component trees to images.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

#![doc(
  html_logo_url = "https://raw.githubusercontent.com/kane50613/takumi/master/assets/images/takumi.svg",
  html_favicon_url = "https://raw.githubusercontent.com/kane50613/takumi/master/assets/images/takumi.svg"
)]
#![deny(missing_docs)]
//! Takumi renders UI component trees to images. This crate is the facade users
//! depend on: entry-point **functions** live at the crate root and the _curated,
//! stable_ data structures live in [`prelude`]. Glob the prelude for the types
//! and call the functions from the crate root.
//!
//! The backend crates expose a much larger surface than is meant for general use
//! — layout-engine glue, paint internals, and other cross-crate plumbing are
//! `pub` only because sibling crates need them. Those internals are deliberately
//! _not_ re-exported here. If you need them, enable the `unstable` feature and
//! reach them through [`unstable`]; nothing under that module is covered by
//! semver.
//!
//! # Example
//!
//! ```rust
//! use takumi::prelude::*;
//! use takumi::render;
//!
//! let node = Node::container([Node::text("Hello, world!").with_style(
//!   Style::default().with(StyleDeclaration::font_size(Length::Px(32.0).into())),
//! )]);
//!
//! // Create a font context. Reuse it across renders to share the decode cache.
//! let mut fonts = Fonts::default();
//!
//! // Load fonts
//! fonts
//!   .register(FontResource::new(include_bytes!(
//!     "../../assets/fonts/geist/Geist[wght].woff2"
//!   )))
//!   .unwrap();
//!
//! let viewport = Viewport::new((1200, 630));
//!
//! let options = RenderOptions::builder()
//!   .viewport(viewport)
//!   .node(node)
//!   .fonts(&fonts)
//!   .build();
//!
//! let image = render(options).unwrap();
//! ```
//!
//! # Feature Flags
//!
//! - `raster-backend` (default): Enable the raster rendering backend.
//! - `svg` (default): Enable SVG image-source support in the core and raster
//!   backend.
//! - `svg-backend`: Enable the vector/SVG output backend ([`render_svg`]). Opt-in.
//! - `woff2`: Enable WOFF2 font support.
//! - `woff`: Enable WOFF font support.
//! - `rayon`: Enable rayon-based parallelism in the raster backend, when
//!   `raster-backend` is also enabled.
//! - `unstable`: Re-export the backend crates wholesale under [`unstable`]. No
//!   semver guarantee. Opt-in.

/// The curated, stable data structures for building a node tree and configuring a
/// render.
///
/// A glob import (`use takumi::prelude::*;`) brings the types into scope; call the
/// entry-point functions (e.g. [`render`], [`write_image`]) from the crate root.
/// The glob pulls in common names like `Error`, `Result`, `Style`, and `Color`;
/// that breadth is intentional for a prelude.
pub mod prelude {
  pub use takumi_core::{
    Error, Fonts, Result,
    layout::{
      Viewport,
      node::{ImageData, ImageSourceInput, Node, NodeKind, TextData},
      style::*,
    },
    resources::{
      font::{FontError, FontResource, RegisteredFamily},
      image::{ImageCacheMode, ImageSource},
    },
  };

  #[cfg(feature = "raster-backend")]
  pub use takumi_raster::{
    AnimatedGifOptions, AnimatedPngOptions, AnimatedWebpOptions, AnimationFrame, Bitmap,
    DitheringAlgorithm, MeasuredNode, MeasuredTextRun, OutputFormat, Quality, RenderOptions,
    SequentialScene,
  };

  #[cfg(feature = "svg-backend")]
  pub use takumi_svg::SvgOptions;
}

#[cfg(feature = "raster-backend")]
pub use takumi_raster::{
  encode_animated_gif, encode_animated_png, encode_animated_webp, measure, render,
  render_animation, write_image,
};

#[cfg(feature = "svg-backend")]
pub use takumi_svg::render as render_svg;

/// Unstable, semver-exempt access to the backend crates in full.
///
/// Everything here is implementation surface that may change or disappear in any
/// release. Prefer the curated [`prelude`] and crate-root functions.
#[cfg(feature = "unstable")]
pub mod unstable {
  pub use takumi_core as base;

  #[cfg(feature = "raster-backend")]
  pub use takumi_raster as raster;

  #[cfg(feature = "svg-backend")]
  pub use takumi_svg as svg;
}