swash/
lib.rs

Help
1/*!
2Font introspection, complex text shaping and glyph rendering.
3
4For a comprehensive list of features provided by this crate, please check out
5the [readme](https://github.com/dfrg/swash/blob/main/README.md) on GitHub.
6
7# Note
8
9This is a low level library focusing on implementations of OpenType and
10various related Unicode specifications for building high quality, high performance
11text layout and rendering components with minimal overhead.
12
13If you're looking for something higher level, please stay tuned-- work is in
14progress.
15
16# Usage
17
18The primary currency in this crate is the [`FontRef`] struct so you'll want to
19start there to learn how to construct and use fonts.
20
21Documentation for [shaping](shape) and [scaling](scale) is provided in
22the respective modules.
23*/
24
25#![allow(clippy::float_cmp)]
26#![allow(clippy::many_single_char_names)]
27#![allow(clippy::needless_lifetimes)]
28#![allow(clippy::redundant_static_lifetimes)]
29#![allow(clippy::too_many_arguments)]
30#![cfg_attr(docsrs, feature(doc_auto_cfg))]
31#![cfg_attr(not(any(test, feature = "std")), no_std)]
32extern crate alloc;
33
34#[cfg(feature = "scale")]
35pub use zeno;
36
37#[macro_use]
38mod macros;
39
40mod attributes;
41mod cache;
42mod charmap;
43mod feature;
44mod font;
45mod internal;
46mod metrics;
47mod palette;
48mod setting;
49mod strike;
50mod string;
51mod tag;
52mod variation;
53
54#[cfg(feature = "scale")]
55pub mod scale;
56
57pub mod shape;
58pub mod text;
59
60pub use attributes::*;
61pub use cache::CacheKey;
62pub use charmap::Charmap;
63pub use feature::{Action, Feature, WritingSystem};
64pub use font::{FontDataRef, FontRef, TableProvider};
65pub use metrics::{GlyphMetrics, Metrics};
66pub use palette::{ColorPalette, Usability};
67pub use setting::Setting;
68pub use strike::BitmapStrike;
69pub use string::{LocalizedString, StringId};
70pub use tag::{tag_from_bytes, tag_from_str_lossy, Tag};
71pub use variation::{Instance, Variation};
72
73/// Collection of various iterators over metadata contained in a font.
74pub mod iter {
75    pub use super::feature::{Features, WritingSystems};
76    pub use super::font::Fonts;
77    pub use super::palette::ColorPalettes;
78    pub use super::strike::BitmapStrikes;
79    pub use super::string::{Chars, LocalizedStrings};
80    pub use super::variation::{Instances, Variations};
81}
82
83/// Proxies used to efficiently rematerialize metadata.
84pub mod proxy {
85    pub use super::charmap::CharmapProxy;
86    pub use super::metrics::MetricsProxy;
87    pub use super::strike::BitmapStrikesProxy;
88    pub use super::variation::VariationsProxy;
89}
90
91use iter::*;
92use proxy::BitmapStrikesProxy;
93
94/// Glyph identifier.
95pub type GlyphId = u16;
96
97/// Normalized variation coordinate in 2.14 fixed point format.
98pub type NormalizedCoord = i16;
99
100impl<'a> FontRef<'a> {
101    /// Returns the primary attributes for the font.
102    pub fn attributes(&self) -> Attributes {
103        Attributes::from_font(self)
104    }
105
106    /// Returns an iterator over the localized strings for the font.
107    pub fn localized_strings(&self) -> LocalizedStrings<'a> {
108        LocalizedStrings::from_font(self)
109    }
110
111    /// Returns an iterator over the variations for the font.
112    pub fn variations(&self) -> Variations<'a> {
113        Variations::from_font(self)
114    }
115
116    /// Returns an iterator over the named instances for the font.
117    pub fn instances(&self) -> Instances<'a> {
118        Instances::from_font(self)
119    }
120
121    /// Returns an iterator over writing systems supported by the font.
122    pub fn writing_systems(&self) -> WritingSystems<'a> {
123        WritingSystems::from_font(self)
124    }
125
126    /// Returns an iterator over the features supported by a font.
127    pub fn features(&self) -> Features<'a> {
128        Features::from_font(self)
129    }
130
131    /// Returns metrics for the font and the specified normalized variation
132    /// coordinates.
133    pub fn metrics(&self, coords: &'a [NormalizedCoord]) -> Metrics {
134        Metrics::from_font(self, coords)
135    }
136
137    /// Returns glyph metrics for the font and the specified normalized
138    /// variation coordinates.
139    pub fn glyph_metrics(&self, coords: &'a [NormalizedCoord]) -> GlyphMetrics<'a> {
140        GlyphMetrics::from_font(self, coords)
141    }
142
143    /// Returns the character map for the font.
144    pub fn charmap(&self) -> Charmap<'a> {
145        Charmap::from_font(self)
146    }
147
148    /// Returns an iterator over the color palettes for the font.
149    pub fn color_palettes(&self) -> ColorPalettes<'a> {
150        ColorPalettes::from_font(self)
151    }
152
153    /// Returns an iterator over the alpha bitmap strikes for the font.
154    pub fn alpha_strikes(&self) -> BitmapStrikes<'a> {
155        BitmapStrikesProxy::from_font(self).materialize_alpha(self)
156    }
157
158    /// Returns an iterator over the color bitmap strikes for the font.
159    pub fn color_strikes(&self) -> BitmapStrikes<'a> {
160        BitmapStrikesProxy::from_font(self).materialize_color(self)
161    }
162
163    /// Returns the table data for the specified tag.
164    pub fn table(&self, tag: Tag) -> Option<&'a [u8]> {
165        use internal::RawFont;
166        let range = self.table_range(tag)?;
167        self.data.get(range.0 as usize..range.1 as usize)
168    }
169
170    /// Returns the name for the specified glyph identifier. This is an internal
171    /// function used for testing and stability is not guaranteed.
172    #[doc(hidden)]
173    pub fn glyph_name(&self, glyph_id: GlyphId) -> Option<&'a str> {
174        use internal::head::Post;
175        Post::from_font(self)?.name(glyph_id)
176    }
177}
swash/lib.rs

swash/
lib.rs
