From f9508ff814fe187ebeaafbd9a5155f064bb61661 Mon Sep 17 00:00:00 2001 From: Machtan Date: Mon, 25 Jan 2016 16:51:34 +0100 Subject: [PATCH] Update the documentation a little --- CHANGELOG.md | 2 + src/sdl2_ttf/common.rs | 55 -------------------- src/sdl2_ttf/context.rs | 13 ++--- src/sdl2_ttf/font.rs | 111 ++++++++++++++++++++++------------------ src/sdl2_ttf/lib.rs | 2 +- 5 files changed, 72 insertions(+), 111 deletions(-) delete mode 100644 src/sdl2_ttf/common.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index d27b6ef8..8396211e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ # Changelog ## 0.14.0 +- Added a changelog - The ttf context is now needed to create fonts, which should make it more apparent that it needs to live - Changed all i32 indices to u16 - Moved font creation to the TTF context @@ -14,5 +15,6 @@ - ```Font.get_outline``` -> ```Font.get_outline_width``` - ```Font.set_outline``` -> ```Font.set_outline_width``` - ```Font.line_skip``` -> ```Font.recommended_line_spacing``` +- ```Font.faces``` -> ```Font.face_count``` - ```Font.index_of_char``` -> ```Font.find_glyph``` - ```Font.metrics_of_char``` -> ```Font.find_glyph_metrics``` diff --git a/src/sdl2_ttf/common.rs b/src/sdl2_ttf/common.rs deleted file mode 100644 index 66271c26..00000000 --- a/src/sdl2_ttf/common.rs +++ /dev/null @@ -1,55 +0,0 @@ -use std::error; -use std::error::Error; -use std::ffi::NulError; -use sdl2::ErrorMessage; -use std::fmt; - -/// The result of an SDL2_TTF font operation. -pub type SdlTtfResult = Result; - -/// A font-related error. -#[derive(Debug)] -pub enum SdlTtfError { - /// A Latin-1 encoded byte string is invalid. - InvalidLatin1Text(NulError), - /// A SDL2-related error occured. - SdlError(ErrorMessage), -} - -impl error::Error for SdlTtfError { - fn description(&self) -> &str { - match self { - &SdlTtfError::InvalidLatin1Text(ref error) => { - error.description() - }, - &SdlTtfError::SdlError(ref message) => { - message.description() - }, - } - } - - fn cause<'a>(&'a self) -> Option<&'a error::Error> { - match self { - &SdlTtfError::InvalidLatin1Text(ref error) => { - Some(error) - }, - &SdlTtfError::SdlError(_) => { - None - }, - } - } -} - -impl fmt::Display for SdlTtfError { - fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> { - match self { - &SdlTtfError::InvalidLatin1Text(ref err) => { - write!(f, "Invalid Latin-1 bytes: {}", err.description()) - }, - &SdlTtfError::SdlError(ref msg) => { - write!(f, "SDL2 error: {}", msg) - }, - } - - } -} \ No newline at end of file diff --git a/src/sdl2_ttf/context.rs b/src/sdl2_ttf/context.rs index cb226c47..0d150367 100644 --- a/src/sdl2_ttf/context.rs +++ b/src/sdl2_ttf/context.rs @@ -18,7 +18,7 @@ use font::{ use ffi; -/// A context manager for SDL2_TTF to manage C code init and quit +/// A context manager for SDL2_TTF to manage C code initialization and clean-up. #[must_use] pub struct Sdl2TtfContext; @@ -35,6 +35,8 @@ impl Sdl2TtfContext { internal_load_font(path, point_size) } + /// Loads the font at the given index of the file, with the given + /// size in points. pub fn load_font_at_index(&self, path: &Path, index: u32, point_size: u16) -> SdlResult { internal_load_font_at_index(path, index, point_size) @@ -54,7 +56,7 @@ impl Sdl2TtfContext { } } - /// Loads the font at the given index in the given SDL2 rwops object with + /// Loads the font at the given index of the SDL2 rwops object with /// the given size in points. pub fn load_font_at_index_from_rwops(&self, rwops: RWops, index: u32, point_size: u16) -> SdlResult { @@ -78,7 +80,7 @@ pub fn get_linked_version() -> Version { } /// An error for when sdl2_ttf is attempted initialized twice -// Necessary for context management, unless we find a way to have a singleton +/// Necessary for context management, unless we find a way to have a singleton #[derive(Debug)] pub enum InitError { InitializationError(io::Error), @@ -115,9 +117,8 @@ impl fmt::Display for InitError { } } -/// Initialize the truetype font API and returns a context manager which will +/// Initializes the truetype font API and returns a context manager which will /// clean up the library once it goes out of scope. -/// You can't really use it, but keep the reference alive. pub fn init() -> Result { unsafe { if ffi::TTF_WasInit() == 1 { @@ -134,7 +135,7 @@ pub fn init() -> Result { } } -/// Returns whether the underlying library has been initialized +/// Returns whether library has been initialized already. pub fn has_been_initialized() -> bool { unsafe { ffi::TTF_WasInit() == 1 diff --git a/src/sdl2_ttf/font.rs b/src/sdl2_ttf/font.rs index 6a9084ae..d5c472fc 100644 --- a/src/sdl2_ttf/font.rs +++ b/src/sdl2_ttf/font.rs @@ -15,6 +15,7 @@ use sdl2_sys::pixels::SDL_Color; use sdl2::SdlResult; use ffi; +/// Converts a rust-SDL2 color to its C ffi representation. #[inline] fn color_to_c_color(color: Color) -> SDL_Color { match color { @@ -23,8 +24,8 @@ fn color_to_c_color(color: Color) -> SDL_Color { } } -/// Font Style bitflags! { + /// The styling of a font. flags FontStyle : c_int { const STYLE_NORMAL = ffi::TTF_STYLE_NORMAL, const STYLE_BOLD = ffi::TTF_STYLE_BOLD, @@ -34,6 +35,8 @@ bitflags! { } } +/// Information about the hinting of a font. +/// See [wikipedia](https://en.wikipedia.org/wiki/Font_hinting) #[derive(Debug, PartialEq, Clone)] pub enum Hinting { Normal = ffi::TTF_HINTING_NORMAL as isize, @@ -42,7 +45,7 @@ pub enum Hinting { None = ffi::TTF_HINTING_NONE as isize } -/// Glyph Metrics +/// Information about a specific glyph (character) in a font face. #[derive(Debug, PartialEq, Clone)] pub struct GlyphMetrics { pub minx: i32, @@ -130,7 +133,7 @@ impl<'a> RenderableText<'a> { /// A builder for a font rendering. #[must_use] -pub struct PartialRender<'a> { +pub struct PartialRendering<'a> { text: RenderableText<'a>, font: &'a Font, } @@ -146,8 +149,10 @@ fn convert_to_surface<'a>(raw: *mut SDL_Surface) -> FontResult> { } } -impl<'a> PartialRender<'a> { - /// Renders the text using the given solid color. +impl<'a> PartialRendering<'a> { + /// Renders the text in *solid* mode. + /// See [the SDL2_TTF docs](https://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html#SEC42) + /// for an explanation. pub fn solid<'b, T>(self, color: T ) -> FontResult> where T: Into { let source = try!(self.text.convert()); @@ -167,7 +172,9 @@ impl<'a> PartialRender<'a> { convert_to_surface(raw) } - /// Renders the text. + /// Renders the text in *shaded* mode. + /// See [the SDL2_TTF docs](https://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html#SEC42) + /// for an explanation. pub fn shaded<'b, T>(self, color: T, background: T) -> FontResult> where T: Into { let source = try!(self.text.convert()); @@ -188,7 +195,9 @@ impl<'a> PartialRender<'a> { convert_to_surface(raw) } - /// Renders the text. + /// Renders the text in *blended* mode. + /// See [the SDL2_TTF docs](https://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html#SEC42) + /// for an explanation. pub fn blended<'b, T>(self, color: T) -> FontResult> where T: Into { let source = try!(self.text.convert()); @@ -208,8 +217,10 @@ impl<'a> PartialRender<'a> { convert_to_surface(raw) } - /// Renders the text blendedly but wrapping the words if the width exceeds - /// the given maximum width. + /// Renders the text in *blended* mode but wrapping the words if the width + /// exceeds the given maximum width. + /// See [the SDL2_TTF docs](https://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html#SEC42) + /// for an explanation of the mode. pub fn blended_wrapped<'b, T>(self, color: T, wrap_max_width: u32) -> FontResult> where T: Into { let source = try!(self.text.convert()); @@ -230,7 +241,7 @@ impl<'a> PartialRender<'a> { } } -/// The opaque holder of a loaded font. +/// A loaded TTF font. #[derive(PartialEq)] pub struct Font { raw: *const ffi::TTF_Font, @@ -250,6 +261,7 @@ impl Drop for Font { } } +/// Internally used to load a font (for internal visibility). pub fn internal_load_font(path: &Path, ptsize: u16) -> SdlResult { unsafe { let cstring = CString::new(path.to_str().unwrap()).unwrap(); @@ -262,11 +274,13 @@ pub fn internal_load_font(path: &Path, ptsize: u16) -> SdlResult { } } +/// Internally used to load a font (for internal visibility). pub fn internal_load_font_from_ll(raw: *const ffi::TTF_Font, owned: bool) -> Font { Font { raw: raw, owned: owned } } +/// Internally used to load a font (for internal visibility). pub fn internal_load_font_at_index(path: &Path, index: u32, ptsize: u16) -> SdlResult { unsafe { @@ -288,21 +302,53 @@ impl Font { self.raw } - /// Starts specifying a render of the given UTF-8 text. - pub fn render<'a>(&'a self, text: &'a str) -> PartialRender<'a> { - PartialRender { + /// Starts specifying a rendering of the given UTF-8-encoded text. + pub fn render<'a>(&'a self, text: &'a str) -> PartialRendering<'a> { + PartialRendering { text: RenderableText::Utf8(text), font: self, } } - /// Starts specifying of the given Latin-1 text. - pub fn render_latin1<'a>(&'a self, text: &'a [u8]) -> PartialRender<'a> { - PartialRender { + /// Starts specifying a rendering of the given Latin-1-encoded text. + pub fn render_latin1<'a>(&'a self, text: &'a [u8]) -> PartialRendering<'a> { + PartialRendering { text: RenderableText::Latin1(text), font: self, } } + + /// Returns the surface size of a c-style string when rendered using this + /// font. + #[allow(unused_mut)] + fn size_of_c_string(&self, text: &CString) -> FontResult<(u32, u32)> { + let (res, size) = unsafe { + let mut w = 0; // mutated by C code + let mut h = 0; // mutated by C code + let ret = ffi::TTF_SizeText(self.raw, text.as_ptr(), &w, &h); + (ret, (w as u32, h as u32)) + }; + if res != 0 { + Err(FontError::SdlError(get_error())) + } else { + Ok(size) + } + } + + /// Returns the width and height of the given text when rendered using this + /// font. + pub fn size_of(&self, text: &str) -> FontResult<(u32, u32)> { + let c_string = try!(RenderableText::Utf8(text).convert()); + self.size_of_c_string(&c_string) + } + + /// Returns the width and height of the given text when rendered using this + /// font. + pub fn size_of_latin1(&self, text: &[u8]) + -> FontResult<(u32, u32)> { + let c_string = try!(RenderableText::Latin1(text).convert()); + self.size_of_c_string(&c_string) + } /// Returns the font's style flags. pub fn get_style(&self) -> FontStyle { @@ -335,7 +381,6 @@ impl Font { /// Returns the font's freetype hints. pub fn get_hinting(&self) -> Hinting { - //! Get freetype hinter setting. unsafe { match ffi::TTF_GetFontHinting(self.raw) as c_int { ffi::TTF_HINTING_NORMAL => Hinting::Normal, @@ -468,36 +513,4 @@ impl Font { } ) } } - - /// Returns the surface size of a c-style string when rendered using this - /// font. - #[allow(unused_mut)] - fn size_of_c_string(&self, text: &CString) -> FontResult<(u32, u32)> { - let (res, size) = unsafe { - let mut w = 0; // mutated by C code - let mut h = 0; // mutated by C code - let ret = ffi::TTF_SizeText(self.raw, text.as_ptr(), &w, &h); - (ret, (w as u32, h as u32)) - }; - if res != 0 { - Err(FontError::SdlError(get_error())) - } else { - Ok(size) - } - } - - /// Returns the width and height of the given text when rendered using this - /// font. - pub fn size_of(&self, text: &str) -> FontResult<(u32, u32)> { - let c_string = try!(RenderableText::Utf8(text).convert()); - self.size_of_c_string(&c_string) - } - - /// Returns the width and height of the given text when rendered using this - /// font. - pub fn size_of_latin1(&self, text: &[u8]) - -> FontResult<(u32, u32)> { - let c_string = try!(RenderableText::Latin1(text).convert()); - self.size_of_c_string(&c_string) - } } \ No newline at end of file diff --git a/src/sdl2_ttf/lib.rs b/src/sdl2_ttf/lib.rs index 9507d4c6..4cacb51f 100644 --- a/src/sdl2_ttf/lib.rs +++ b/src/sdl2_ttf/lib.rs @@ -35,6 +35,6 @@ pub use context::{ init, has_been_initialized, get_linked_version, Sdl2TtfContext }; pub use font::{ - Font, FontStyle, Hinting, GlyphMetrics, PartialRender, FontError, + Font, FontStyle, Hinting, GlyphMetrics, PartialRendering, FontError, FontResult, };