textium: documentation

textium/src/error.rs

@@ -2,9 +2,8 @@ use glium;
 
 #[derive(Debug)]
 pub enum Error {
+    /// Error caused during creation of a Glium GPU-resident texture.
     TextureCreationError(glium::texture::TextureCreationError),
-    PackingError,
-    NotAGlyph(char),
 }
 
 impl From<glium::texture::TextureCreationError> for Error {

textium/src/geometry.rs

@@ -1,3 +1,5 @@
+//! Some generic geometry routines used in atlas packing.
+
 use std::ops::{Add, Sub, Mul};
 
 

textium/src/lib.rs

@@ -1,4 +1,9 @@
-//! Textium is a small library that wires Rusttype up to Glium.
+//! Textium is a small library that wires Rusttype up to OpenGL.
+//!
+//! Textium provides a glyph atlas, atlas packers, a glyph rasterizer, and the necessary
+//! shaders and infrastructure to easily connect to (at the moment) Glium.
+//!
+//! A future goal is making rendering backends generic.
 
 extern crate rusttype;
 #[macro_use]
@@ -37,10 +42,14 @@ pub struct GlyphMetadata {
     left_bearing: f32,
 }
 
+/// Maps glyphs to their size, location, and rendering properties in a glyph atlas.
 pub struct FontAtlas {
     pub glyph_data: HashMap<char, GlyphMetadata>
 }
 
+/// A GPU-backed font texture, plus a [`FontAtlas`].
+///
+/// [`FontAtlas`]: struct.FontAtlas.html
 pub struct FontTexture {
     /// The GPU texture of packed glyphs.
     pub texture: Texture2d,

textium/src/packer/mod.rs

@@ -1,3 +1,5 @@
+//! Strategies for rect-packing a glyph atlas.
+
 mod skyline;
 
 use ::texture::{Buffer2d, ResizeableBuffer2d};
@@ -5,23 +7,40 @@ use ::geometry::Rect;
 
 pub use self::skyline::SkylinePacker;
 
+/// A trait describing a generic atlas packer.
 pub trait Packer {
+    /// The type of the bitmap used to store the packed glyph bitmaps.
     type Buffer: Buffer2d;
 
+    /// Create a new Packer, given a buffer to pack into.
     fn new(b: Self::Buffer) -> Self;
+
+    /// Pack a glyph bitmap into the atlas, returning the location it was packed to.
     fn pack<O>(&mut self, buf: &O) -> Option<Rect<usize>>
         where O: Buffer2d<Pixel=<Self::Buffer as Buffer2d>::Pixel>; // buffer with same pixel type as this atlas
 
+
+    /// Set the size of the margin enforced between glyphs in the atlas.
     fn set_margin(&mut self, margin: usize);
+    /// Return a reference to the buffer we're packing glyphs into.
     fn buf(&self) -> &Self::Buffer;
+    /// Return a mutable reference to the buffer we're packing glyphs into.
     fn buf_mut(&mut self) -> &mut Self::Buffer;
+    /// Convert this packer into the glyph-packed buffer.
     fn into_buf(self) -> Self::Buffer; // TODO: consider actually implementing Into?
 
+
+    /// Return the dimensions of this atlas.
     fn dimensions(&self) -> (usize, usize);
+    /// Resize this atlas.
     fn set_dimensions(&mut self, w: usize, h: usize);
 }
 
+/// A trait describing an atlas packer which can expand its buffer if necessary.
 pub trait GrowingPacker: Packer {
+    /// Pack a glyph bitmap into the atlas, resizing the atlas if necessary.
+    /// Returns the location it was packed to.
+    ///
     /// `resize_fn` should describe a strategy for growing the atlas buffer based on the current size.
     fn pack_resize<F, O>(&mut self, buf: &O, resize_fn: F) -> Rect<usize>
         where O: Buffer2d<Pixel=<<Self as Packer>::Buffer as Buffer2d>::Pixel>,

textium/src/packer/skyline.rs

@@ -10,6 +10,7 @@ struct Skyline {
     pub w: usize,
 }
 
+/// An atlas packer using the skyline rect-packing algorithm.
 pub struct SkylinePacker<B> where B: Buffer2d {
     buf: B,
     width: usize,

textium/src/rasterizer.rs

@@ -1,3 +1,5 @@
+//! Rasterization of glyphs and fonts.
+
 use rusttype;
 
 use std::collections::HashMap;
@@ -7,6 +9,7 @@ use ::geometry::Rect;
 use ::texture::{Buffer2d, Bitmap};
 use ::packer::{Packer, GrowingPacker, SkylinePacker};
 
+/// Wraps a rusttype font and provides atlas packing and rasterization functions.
 pub struct Font<'a> {
     font: rusttype::Font<'a>
 }
@@ -59,6 +62,9 @@ impl<'a> Font<'a> {
         (atlas, packer.into_buf(), line_height)
     }
 
+    /// Rasterize a single character to a bitmap.
+    ///
+    /// If the glyph is not found in the font, the result will be `None`.
     pub fn rasterize_char(&self, chr: char, scale: f32)
         -> Option<(GlyphMetadata, Bitmap<u8>)>
     {

textium/src/texture.rs

@@ -1,10 +1,12 @@
+//! A small, Glium-compatible texture buffer abstraction toolkit.
+
 use std::borrow::Cow;
 use std::slice::Chunks;
 
 use glium::texture::{RawImage2d, Texture2dDataSource};
-pub use glium::texture::PixelValue;
+use glium::texture::PixelValue;
 
-/// A CPU RAM-based 2d buffer.
+/// A generic 2D pixel buffer.
 pub trait Buffer2d: Sized {
     type Pixel;
 
@@ -48,10 +50,12 @@ pub trait Buffer2d: Sized {
     }
 }
 
+/// A generic 2D pixel buffer which can be resized.
 pub trait ResizeableBuffer2d: Buffer2d {
     fn resize(&mut self, width: usize, height: usize);
 }
 
+/// A type-parametrized bitmap, stored flat in a Vec<T>.
 pub struct Bitmap<T> {
     pub data: Vec<T>,
     pub width: usize,
@@ -126,6 +130,7 @@ impl<'a, P> Texture2dDataSource<'a> for &'a Bitmap<P>
     }
 }
 
+/// Find the next power of two.
 pub fn get_nearest_pow2(mut x: u32) -> u32 {
     // A nice, fast bit hack.
     // Taken from https://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2