Struct swash::FontRef [−][src]
Expand description
Reference to a font.
This struct encapsulates the data required to access font resources and uniquely identify the font in various caches. Font files can be organized into collections of multiple fonts, so along with a reference to the actual content of the file, we also store a byte offset to the header of the selected font (although most fonts are not collections so this is almost always zero). Note that internal references in the font are stored relative to the base of the file, so the entire file must be kept in memory and it is an error to slice the data at the offset.
Getting started
As a primer, let’s write a function to read a font file, construct a font reference
and print the Attributes
and all of the associated
LocalizedString
s (including names, copyright information
and other metadata).
fn print_localized_strings(font_path: &str) -> Option<()> { use swash::FontRef; // Read the full font file let font_data = std::fs::read(font_path).ok()?; // Create a font reference for the first font in the file let font = FontRef::from_index(&font_data, 0)?; // Print the font attributes (stretch, weight and style) println!("{}", font.attributes()); // Iterate through the localized strings for string in font.localized_strings() { // Print the string identifier and the actual value println!("[{:?}] {}", string.id(), string.to_string()); } Some(()) }
Owning your fonts
The FontRef
struct is designed to be agnostic with regard to the font management
policy of higher level crates and applications, and as such, contains borrowed
data and is intended to be used as a transient resource. If you’re using this
library, you’ll likely want to create your own type to represent a font.
Regardless of the complexity of your management strategy, the basic pattern remains
the same, so we’ll build a simple Font
struct here that can load fonts from a
file using a basic Vec<u8>
as a backing store.
use swash::{Attributes, CacheKey, Charmap, FontRef}; pub struct Font { // Full content of the font file data: Vec<u8>, // Offset to the table directory offset: u32, // Cache key key: CacheKey, } impl Font { pub fn from_file(path: &str, index: usize) -> Option<Self> { // Read the full font file let data = std::fs::read(path).ok()?; // Create a temporary font reference for the first font in the file. // This will do some basic validation, compute the necessary offset // and generate a fresh cache key for us. let font = FontRef::from_index(&data, index)?; let (offset, key) = (font.offset, font.key); // Return our struct with the original file data and copies of the // offset and key from the font reference Some(Self { data, offset, key }) } // As a convenience, you may want to forward some methods. pub fn attributes(&self) -> Attributes { self.as_ref().attributes() } pub fn charmap(&self) -> Charmap { self.as_ref().charmap() } // Create the transient font reference for accessing this crate's // functionality. pub fn as_ref(&self) -> FontRef { // Note that you'll want to initialize the struct directly here as // using any of the FontRef constructors will generate a new key which, // while completely safe, will nullify the performance optimizations of // the caching mechanisms used in this crate. FontRef { data: &self.data, offset: self.offset, key: self.key } } }
In the example above, it’s trivial to replace the Vec<u8>
with an
Rc<Vec<u8>>
for a reference counted version or an Arc<Vec<u8>>
for fonts
that are shareable across threads. You may also consider memory mapping
your font data, particularly for larger fonts (hello Apple Color Emoji!).
Fields
data: &'a [u8]
Full content of a file containing the font.
offset: u32
Offset to the table directory of the font.
key: CacheKey
Key for identifying a font in various caches.
Implementations
Creates a new font from the specified font data and the index of the
desired font. Returns None
if the data does not represent a font file
or the index is out of bounds.
Returns the primary attributes for the font.
pub fn localized_strings(&self) -> LocalizedStrings<'a>ⓘNotable traits for LocalizedStrings<'a>impl<'a> Iterator for LocalizedStrings<'a> type Item = LocalizedString<'a>;
pub fn localized_strings(&self) -> LocalizedStrings<'a>ⓘNotable traits for LocalizedStrings<'a>impl<'a> Iterator for LocalizedStrings<'a> type Item = LocalizedString<'a>;
impl<'a> Iterator for LocalizedStrings<'a> type Item = LocalizedString<'a>;
Returns an iterator over the localized strings for the font.
pub fn variations(&self) -> Variations<'a>ⓘNotable traits for Variations<'a>impl<'a> Iterator for Variations<'a> type Item = Variation<'a>;
pub fn variations(&self) -> Variations<'a>ⓘNotable traits for Variations<'a>impl<'a> Iterator for Variations<'a> type Item = Variation<'a>;
impl<'a> Iterator for Variations<'a> type Item = Variation<'a>;
Returns an iterator over the variations for the font.
Returns an iterator over the named instances for the font.
pub fn writing_systems(&self) -> WritingSystems<'a>ⓘNotable traits for WritingSystems<'a>impl<'a> Iterator for WritingSystems<'a> type Item = WritingSystem<'a>;
pub fn writing_systems(&self) -> WritingSystems<'a>ⓘNotable traits for WritingSystems<'a>impl<'a> Iterator for WritingSystems<'a> type Item = WritingSystem<'a>;
impl<'a> Iterator for WritingSystems<'a> type Item = WritingSystem<'a>;
Returns an iterator over writing systems supported by the font.
Returns an iterator over the features supported by a font.
Returns metrics for the font and the specified normalized variation coordinates.
Returns glyph metrics for the font and the specified normalized variation coordinates.
pub fn color_palettes(&self) -> ColorPalettes<'a>ⓘNotable traits for ColorPalettes<'a>impl<'a> Iterator for ColorPalettes<'a> type Item = ColorPalette<'a>;
pub fn color_palettes(&self) -> ColorPalettes<'a>ⓘNotable traits for ColorPalettes<'a>impl<'a> Iterator for ColorPalettes<'a> type Item = ColorPalette<'a>;
impl<'a> Iterator for ColorPalettes<'a> type Item = ColorPalette<'a>;
Returns an iterator over the color palettes for the font.
pub fn alpha_strikes(&self) -> BitmapStrikes<'a>ⓘNotable traits for BitmapStrikes<'a>impl<'a> Iterator for BitmapStrikes<'a> type Item = BitmapStrike<'a>;
pub fn alpha_strikes(&self) -> BitmapStrikes<'a>ⓘNotable traits for BitmapStrikes<'a>impl<'a> Iterator for BitmapStrikes<'a> type Item = BitmapStrike<'a>;
impl<'a> Iterator for BitmapStrikes<'a> type Item = BitmapStrike<'a>;
Returns an iterator over the alpha bitmap strikes for the font.
pub fn color_strikes(&self) -> BitmapStrikes<'a>ⓘNotable traits for BitmapStrikes<'a>impl<'a> Iterator for BitmapStrikes<'a> type Item = BitmapStrike<'a>;
pub fn color_strikes(&self) -> BitmapStrikes<'a>ⓘNotable traits for BitmapStrikes<'a>impl<'a> Iterator for BitmapStrikes<'a> type Item = BitmapStrike<'a>;
impl<'a> Iterator for BitmapStrikes<'a> type Item = BitmapStrike<'a>;
Returns an iterator over the color bitmap strikes for the font.
Trait Implementations
Auto Trait Implementations
impl<'a> RefUnwindSafe for FontRef<'a>
impl<'a> UnwindSafe for FontRef<'a>
Blanket Implementations
Mutably borrows from an owned value. Read more