From 482b7bee0ce5c1b5121a82eeb2113152ded6258b Mon Sep 17 00:00:00 2001 From: Erin Date: Wed, 16 Aug 2017 13:37:27 -0500 Subject: [PATCH] textium: documentation --- textium/src/error.rs | 3 +-- textium/src/geometry.rs | 2 ++ textium/src/lib.rs | 11 ++++++++++- textium/src/packer/mod.rs | 19 +++++++++++++++++++ textium/src/packer/skyline.rs | 1 + textium/src/rasterizer.rs | 6 ++++++ textium/src/texture.rs | 9 +++++++-- 7 files changed, 46 insertions(+), 5 deletions(-) diff --git a/textium/src/error.rs b/textium/src/error.rs index e32c0d7..83fbb9a 100644 --- a/textium/src/error.rs +++ b/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 for Error { diff --git a/textium/src/geometry.rs b/textium/src/geometry.rs index c77741b..aac77d4 100644 --- a/textium/src/geometry.rs +++ b/textium/src/geometry.rs @@ -1,3 +1,5 @@ +//! Some generic geometry routines used in atlas packing. + use std::ops::{Add, Sub, Mul}; diff --git a/textium/src/lib.rs b/textium/src/lib.rs index 8398ad9..ecb0461 100644 --- a/textium/src/lib.rs +++ b/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 } +/// A GPU-backed font texture, plus a [`FontAtlas`]. +/// +/// [`FontAtlas`]: struct.FontAtlas.html pub struct FontTexture { /// The GPU texture of packed glyphs. pub texture: Texture2d, diff --git a/textium/src/packer/mod.rs b/textium/src/packer/mod.rs index 4600468..0836f7d 100644 --- a/textium/src/packer/mod.rs +++ b/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(&mut self, buf: &O) -> Option> where O: 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(&mut self, buf: &O, resize_fn: F) -> Rect where O: Buffer2d::Buffer as Buffer2d>::Pixel>, diff --git a/textium/src/packer/skyline.rs b/textium/src/packer/skyline.rs index 1da62be..04b2233 100644 --- a/textium/src/packer/skyline.rs +++ b/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 where B: Buffer2d { buf: B, width: usize, diff --git a/textium/src/rasterizer.rs b/textium/src/rasterizer.rs index 83529fc..7e9d461 100644 --- a/textium/src/rasterizer.rs +++ b/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)> { diff --git a/textium/src/texture.rs b/textium/src/texture.rs index b5f0f1f..f3febf6 100644 --- a/textium/src/texture.rs +++ b/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. pub struct Bitmap { pub data: Vec, pub width: usize, @@ -126,6 +130,7 @@ impl<'a, P> Texture2dDataSource<'a> for &'a Bitmap

} } +/// 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