rename CustomGlyphInput and CustomGlyphOutput, add some docs

examples/custom-glyphs.rs

@@ -1,5 +1,5 @@
 use glyphon::{
-    Attrs, Buffer, Cache, Color, ContentType, CustomGlyph, CustomGlyphInput, CustomGlyphOutput,
+    Attrs, Buffer, Cache, Color, ContentType, CustomGlyph, RasterizationRequest, RasterizedCustomGlyph,
     Family, FontSystem, Metrics, Resolution, Shaping, SwashCache, TextArea, TextAtlas, TextBounds,
     TextRenderer, Viewport,
 };
@@ -36,7 +36,7 @@ struct WindowState {
     text_renderer: glyphon::TextRenderer,
     text_buffer: glyphon::Buffer,
 
-    rasterize_svg: Box<dyn Fn(CustomGlyphInput) -> Option<CustomGlyphOutput>>,
+    rasterize_svg: Box<dyn Fn(RasterizationRequest) -> Option<RasterizedCustomGlyph>>,
 
     // Make sure that the winit window is last in the struct so that
     // it is dropped after the wgpu surface is dropped, otherwise the
@@ -106,7 +106,7 @@ impl WindowState {
         let svg_0 = resvg::usvg::Tree::from_data(LION_SVG, &Default::default()).unwrap();
         let svg_1 = resvg::usvg::Tree::from_data(EAGLE_SVG, &Default::default()).unwrap();
 
-        let rasterize_svg = move |input: CustomGlyphInput| -> Option<CustomGlyphOutput> {
+        let rasterize_svg = move |input: RasterizationRequest| -> Option<RasterizedCustomGlyph> {
             // Select the svg data based on the custom glyph ID.
             let (svg, content_type) = match input.id {
                 0 => (&svg_0, ContentType::Mask),
@@ -143,7 +143,7 @@ impl WindowState {
                 pixmap.data().to_vec()
             };
 
-            Some(CustomGlyphOutput { data, content_type })
+            Some(RasterizedCustomGlyph { data, content_type })
         };
 
         Self {

src/custom_glyph.rs

@@ -22,17 +22,17 @@ pub struct CustomGlyph {
     /// Set to `None` to use [`TextArea::default_color`].
     pub color: Option<Color>,
     /// If `true`, then this glyph will be snapped to the nearest whole physical
-    /// pixel and the resulting `SubpixelBin`'s in `CustomGlyphInput` will always
+    /// pixel and the resulting `SubpixelBin`'s in `RasterizationRequest` will always
     /// be `Zero` (useful for images and other large glyphs).
     pub snap_to_physical_pixel: bool,
     /// Additional metadata about the glyph
     pub metadata: usize,
 }
 
+/// A request to rasterize a custom glyph
 #[derive(Debug, Clone, Copy, PartialEq)]
-/// The input data to render a custom glyph
-pub struct CustomGlyphInput {
-    /// The unique identifier of the glyph.
+pub struct RasterizationRequest {
+    /// The unique identifier of the glyph
     pub id: CustomGlyphId,
     /// The width of the glyph in physical pixels
     pub width: u16,
@@ -53,15 +53,17 @@ pub struct CustomGlyphInput {
     pub scale: f32,
 }
 
+/// A rasterized custom glyph
 #[derive(Debug, Clone)]
-/// The output of a rendered custom glyph
-pub struct CustomGlyphOutput {
+pub struct RasterizedCustomGlyph {
+    /// The raw image data
     pub data: Vec<u8>,
+    /// The type of image data contained in `data`
     pub content_type: ContentType,
 }
 
-impl CustomGlyphOutput {
-    pub(crate) fn validate(&self, input: &CustomGlyphInput, expected_type: Option<ContentType>) {
+impl RasterizedCustomGlyph {
+    pub(crate) fn validate(&self, input: &RasterizationRequest, expected_type: Option<ContentType>) {
         if let Some(expected_type) = expected_type {
             assert_eq!(self.content_type, expected_type, "Custom glyph rasterizer must always produce the same content type for a given input. Expected {:?}, got {:?}. Input: {:?}", expected_type, self.content_type, input);
         }
@@ -91,13 +93,17 @@ pub struct CustomGlyphCacheKey {
     pub y_bin: SubpixelBin,
 }
 
+/// The type of image data contained in a rasterized glyph
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum ContentType {
+    /// Each pixel contains 32 bits of rgba data
     Color,
+    /// Each pixel contains a single 8 bit channel
     Mask,
 }
 
 impl ContentType {
+    /// The number of bytes per pixel for this content type
     pub fn bytes_per_pixel(&self) -> usize {
         match self {
             Self::Color => 4,

src/lib.rs

@@ -13,7 +13,7 @@ mod viewport;
 
 pub use cache::Cache;
 pub use custom_glyph::{
-    ContentType, CustomGlyph, CustomGlyphId, CustomGlyphInput, CustomGlyphOutput,
+    ContentType, CustomGlyph, CustomGlyphId, RasterizationRequest, RasterizedCustomGlyph,
 };
 pub use error::{PrepareError, RenderError};
 pub use text_atlas::{ColorMode, TextAtlas};

src/text_atlas.rs

@@ -1,5 +1,5 @@
 use crate::{
-    text_render::GlyphonCacheKey, Cache, ContentType, CustomGlyphInput, CustomGlyphOutput,
+    text_render::GlyphonCacheKey, Cache, ContentType, RasterizationRequest, RasterizedCustomGlyph,
     FontSystem, GlyphDetails, GpuCacheStatus, SwashCache,
 };
 use etagere::{size2, Allocation, BucketedAtlasAllocator};
@@ -124,7 +124,7 @@ impl InnerAtlas {
         font_system: &mut FontSystem,
         cache: &mut SwashCache,
         scale_factor: f32,
-        mut rasterize_custom_glyph: impl FnMut(CustomGlyphInput) -> Option<CustomGlyphOutput>,
+        mut rasterize_custom_glyph: impl FnMut(RasterizationRequest) -> Option<RasterizedCustomGlyph>,
     ) -> bool {
         if self.size >= self.max_texture_dimension_2d {
             return false;
@@ -169,7 +169,7 @@ impl InnerAtlas {
                     (image.data, width, height)
                 }
                 GlyphonCacheKey::Custom(cache_key) => {
-                    let input = CustomGlyphInput {
+                    let input = RasterizationRequest {
                         id: cache_key.glyph_id,
                         width: cache_key.width,
                         height: cache_key.height,
@@ -352,7 +352,7 @@ impl TextAtlas {
         cache: &mut SwashCache,
         content_type: ContentType,
         scale_factor: f32,
-        rasterize_custom_glyph: impl FnMut(CustomGlyphInput) -> Option<CustomGlyphOutput>,
+        rasterize_custom_glyph: impl FnMut(RasterizationRequest) -> Option<RasterizedCustomGlyph>,
     ) -> bool {
         let did_grow = match content_type {
             ContentType::Mask => self.mask_atlas.grow(

src/text_render.rs

@@ -1,5 +1,5 @@
 use crate::{
-    custom_glyph::CustomGlyphCacheKey, ColorMode, ContentType, CustomGlyphInput, CustomGlyphOutput,
+    custom_glyph::CustomGlyphCacheKey, ColorMode, ContentType, RasterizationRequest, RasterizedCustomGlyph,
     FontSystem, GlyphDetails, GlyphToRender, GpuCacheStatus, PrepareError, RenderError, SwashCache,
     SwashContent, TextArea, TextAtlas, Viewport,
 };
@@ -104,7 +104,7 @@ impl TextRenderer {
         viewport: &Viewport,
         text_areas: impl IntoIterator<Item = TextArea<'a>>,
         cache: &mut SwashCache,
-        rasterize_custom_glyph: impl FnMut(CustomGlyphInput) -> Option<CustomGlyphOutput>,
+        rasterize_custom_glyph: impl FnMut(RasterizationRequest) -> Option<RasterizedCustomGlyph>,
     ) -> Result<(), PrepareError> {
         self.prepare_with_depth_and_custom(
             device,
@@ -130,7 +130,7 @@ impl TextRenderer {
         text_areas: impl IntoIterator<Item = TextArea<'a>>,
         cache: &mut SwashCache,
         mut metadata_to_depth: impl FnMut(usize) -> f32,
-        mut rasterize_custom_glyph: impl FnMut(CustomGlyphInput) -> Option<CustomGlyphOutput>,
+        mut rasterize_custom_glyph: impl FnMut(RasterizationRequest) -> Option<RasterizedCustomGlyph>,
     ) -> Result<(), PrepareError> {
         self.glyph_vertices.clear();
 
@@ -193,7 +193,7 @@ impl TextRenderer {
                             return None;
                         }
 
-                        let input = CustomGlyphInput {
+                        let input = RasterizationRequest {
                             id: glyph.id,
                             width,
                             height,
@@ -429,7 +429,7 @@ fn prepare_glyph<R>(
     mut rasterize_custom_glyph: R,
 ) -> Result<Option<GlyphToRender>, PrepareError>
 where
-    R: FnMut(CustomGlyphInput) -> Option<CustomGlyphOutput>,
+    R: FnMut(RasterizationRequest) -> Option<RasterizedCustomGlyph>,
 {
     if atlas.mask_atlas.glyph_cache.contains(&cache_key) {
         atlas.mask_atlas.promote(cache_key);