1// font-kit/src/lib.rs
2//
3// Copyright © 2018 The Pathfinder Project Developers.
4//
5// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8// option. This file may not be copied, modified, or distributed
9// except according to those terms.
10
11//! `font-kit` provides a common interface to the various system font libraries and provides
12//! services such as finding fonts on the system, performing nearest-font matching, and rasterizing
13//! glyphs.
14//!
15//! ## Synopsis
16//!
17//! # extern crate font_kit;
18//! # extern crate pathfinder_geometry;
19//! #
20//! use font_kit::canvas::{Canvas, Format, RasterizationOptions};
21//! use font_kit::family_name::FamilyName;
22//! use font_kit::hinting::HintingOptions;
23//! use font_kit::properties::Properties;
24//! use font_kit::source::SystemSource;
25//! use pathfinder_geometry::transform2d::Transform2F;
26//! use pathfinder_geometry::vector::{Vector2F, Vector2I};
27//!
28//! let font = SystemSource::new().select_best_match(&[FamilyName::SansSerif],
29//! &Properties::new())
30//! .unwrap()
31//! .load()
32//! .unwrap();
33//! let glyph_id = font.glyph_for_char('A').unwrap();
34//! let mut canvas = Canvas::new(Vector2I::splat(32), Format::A8);
35//! font.rasterize_glyph(&mut canvas,
36//! glyph_id,
37//! 32.0,
38//! Transform2F::from_translation(Vector2F::new(0.0, 32.0)),
39//! HintingOptions::None,
40//! RasterizationOptions::GrayscaleAa)
41//! .unwrap();
42//!
43//! ## Backends
44//!
45//! `font-kit` delegates to system libraries to perform tasks. It has two types of backends: a
46//! *source* and a *loader*. Sources are platform font databases; they allow lookup of installed
47//! fonts by name or attributes. Loaders are font loading libraries; they allow font files (TTF,
48//! OTF, etc.) to be loaded from a file on disk or from bytes in memory. Sources and loaders can be
49//! freely intermixed at runtime; fonts can be looked up via DirectWrite and rendered via FreeType,
50//! for example.
51//!
52//! Available loaders:
53//!
54//! * Core Text (macOS): The system font loader on macOS. Does not do hinting except when bilevel
55//! rendering is in use.
56//!
57//! * DirectWrite (Windows): The newer system framework for text rendering on Windows. Does
58//! vertical hinting but not full hinting.
59//!
60//! * FreeType (cross-platform): A full-featured font rendering framework.
61//!
62//! Available sources:
63//!
64//! * Core Text (macOS): The system font database on macOS.
65//!
66//! * DirectWrite (Windows): The newer API to query the system font database on Windows.
67//!
68//! * Fontconfig (cross-platform): A technically platform-neutral, but in practice Unix-specific,
69//! API to query and match fonts.
70//!
71//! * Filesystem (cross-platform): A simple source that reads fonts from a path on disk. This is
72//! the default on Android and OpenHarmony.
73//!
74//! * Memory (cross-platform): A source that reads from a fixed set of fonts in memory.
75//!
76//! * Multi (cross-platform): A source that allows multiple sources to be queried at once.
77//!
78//! On Windows and macOS, the FreeType loader and the Fontconfig source are not built by default.
79//! To build them, use the `loader-freetype` and `source-fontconfig` Cargo features respectively.
80//! If you want them to be the default, instead use the `loader-freetype-default` and
81//! `source-fontconfig-default` Cargo features respectively. Beware that
82//! `source-fontconfig-default` is rarely what you want on those two platforms!
83//!
84//! ## Features
85//!
86//! `font-kit` is capable of doing the following:
87//!
88//! * Loading fonts from files or memory.
89//!
90//! * Determining whether files on disk or in memory represent fonts.
91//!
92//! * Interoperating with native font APIs.
93//!
94//! * Querying various metadata about fonts.
95//!
96//! * Doing simple glyph-to-character mapping. (For more complex use cases, a shaper is required;
97//! proper shaping is beyond the scope of `font-kit`.)
98//!
99//! * Reading unhinted or hinted vector outlines from glyphs.
100//!
101//! * Calculating glyph and font metrics.
102//!
103//! * Looking up glyph advances and origins.
104//!
105//! * Rasterizing glyphs using the native rasterizer, optionally using hinting. (Custom
106//! rasterizers, such as Pathfinder, can be used in conjunction with the outline API.)
107//!
108//! * Looking up all fonts on the system.
109//!
110//! * Searching for specific fonts by family or PostScript name.
111//!
112//! * Performing font matching according to the [CSS Fonts Module Level 3] specification.
113//!
114//! ## License
115//!
116//! `font-kit` is licensed under the same terms as Rust itself.
117//!
118//! [CSS Fonts Module Level 3]: https://drafts.csswg.org/css-fonts-3/#font-matching-algorithm
119
120#![warn(missing_docs)]
121#![warn(missing_debug_implementations)]
122#![warn(missing_copy_implementations)]
123
124#[macro_use]
125extern crate bitflags;
126
127pub mod canvas;
128pub mod error;
129pub mod family;
130pub mod family_handle;
131pub mod family_name;
132pub mod file_type;
133pub mod font;
134pub mod handle;
135pub mod hinting;
136pub mod loader;
137pub mod loaders;
138pub mod metrics;
139pub mod outline;
140pub mod properties;
141
142#[cfg(feature = "source")]
143pub mod source;
144#[cfg(feature = "source")]
145pub mod sources;
146
147mod matching;
148mod utils;
149