Skip to main content

pltrs_render/raster/
bitmap.rs

1//! A glyph rendered alone into a bitmap, as `FreeType` renders it for
2//! matplotlib's `FT2Font._render_glyph` (and the bitmaps of its
3//! `draw_glyph_to_bitmap` and mathtext's raster output).
4
5use pltrs_core::Point;
6use pltrs_font::ScanOutline;
7use pltrs_raster::{GrayBitmap, RasterError};
8
9use super::glyph::{GlyphTransform, freetype_contours, is_axis_aligned};
10use super::mono::{self, MonoBitmap};
11
12/// A glyph's tagged outline (26.6, origin at the pen) as `FreeType` hands
13/// it to a rasterizer.
14#[derive(Clone, Debug, PartialEq)]
15pub enum GlyphShape {
16    /// For anti-aliased text.
17    Smooth(ScanOutline),
18    /// For text without anti-aliasing.
19    Mono(ScanOutline),
20}
21
22/// A rendered glyph: `FreeType`'s `FT_Bitmap` and where it goes.
23#[derive(Clone, Debug, PartialEq, Eq)]
24pub struct GlyphBitmap {
25    /// The display column of the leftmost pixels (`bitmap_left`).
26    pub left: i32,
27    /// The display row above the topmost pixels, y up (`bitmap_top`).
28    pub top: i32,
29    /// Pixels per row.
30    pub width: u32,
31    /// Number of rows.
32    pub rows: u32,
33    /// Row-major from the top row: coverage `0..=255`, or `0`/`1` for a
34    /// monochrome glyph (as matplotlib's `PositionedBitmap` unpacks it).
35    pub buffer: Vec<u8>,
36}
37
38impl From<GrayBitmap> for GlyphBitmap {
39    fn from(bitmap: GrayBitmap) -> Self {
40        Self {
41            left: bitmap.left,
42            top: bitmap.top,
43            width: bitmap.coverage.width(),
44            rows: bitmap.coverage.height(),
45            buffer: bitmap.coverage.into_vec(),
46        }
47    }
48}
49
50impl From<MonoBitmap> for GlyphBitmap {
51    fn from(bitmap: MonoBitmap) -> Self {
52        let (left, top) = bitmap.origin();
53        let (width, rows) = bitmap.size();
54        Self {
55            left,
56            top,
57            width,
58            rows,
59            buffer: bitmap.pixels().map(u8::from).collect(),
60        }
61    }
62}
63
64/// The anti-aliased bitmap of a tagged glyph `outline` placed by
65/// `transform`, as `FT_Render_Glyph` renders it; `None` for an outline
66/// without area or a malformed one.
67pub(super) fn smooth_bitmap(
68    outline: &ScanOutline,
69    transform: &GlyphTransform,
70) -> Result<Option<GrayBitmap>, RasterError> {
71    match freetype_contours(outline, transform) {
72        Some(contours) => pltrs_raster::render_glyph(&contours, false),
73        None => Ok(None),
74    }
75}
76
77/// Whether `FreeType` sees the glyph matrix matplotlib sets for `angle`
78/// degrees as a quarter turn: the only transforms it autohints glyphs
79/// under.
80pub fn glyph_axis_aligned(angle: f64) -> bool {
81    is_axis_aligned(angle)
82}
83
84/// Renders a glyph outline rotated by `angle` degrees with its origin at
85/// `pen` (display pixels, y up, quantized to 1/64 pixel) — matplotlib's
86/// `_set_transform` and `_render_glyph`: anti-aliased for a smooth
87/// outline, monochrome for a scan outline. `None` for a glyph without
88/// ink.
89///
90/// # Errors
91///
92/// When the glyph is too large to render.
93pub fn render_glyph(
94    shape: &GlyphShape,
95    angle: f64,
96    pen: Point,
97) -> Result<Option<GlyphBitmap>, RasterError> {
98    let transform = GlyphTransform::new(angle, pen);
99    Ok(match shape {
100        GlyphShape::Smooth(outline) => smooth_bitmap(outline, &transform)?.map(GlyphBitmap::from),
101        GlyphShape::Mono(outline) => mono::render(outline, &transform).map(GlyphBitmap::from),
102    })
103}