encounter/rust-sdl2
0
0
Fork 0
mirror of https://github.com/encounter/rust-sdl2.git synced 2026-07-10 21:18:41 -07:00
Code Issues Packages Projects Releases Wiki Activity

Update the documentation a little

Browse Source
This commit is contained in:
Machtan
2016-01-25 16:51:34 +01:00
parent 3272caa00e
commit f9508ff814
5 changed files with 72 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+2
View File
@@ -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```
src/sdl2_ttf/common.rs
-55
View File
@@ -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<T> = Result<T, SdlTtfError>;
/// 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)
},
}
}
}
src/sdl2_ttf/context.rs
+7 -6
View File
@@ -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<Font> {
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<Font> {
@@ -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<Sdl2TtfContext, InitError> {
unsafe {
if ffi::TTF_WasInit() == 1 {
@@ -134,7 +135,7 @@ pub fn init() -> Result<Sdl2TtfContext, InitError> {
}
}
/// 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
src/sdl2_ttf/font.rs
+62 -49
View File
@@ -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<Surface<'a>> {
}
}
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<Surface<'b>> where T: Into<Color> {
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<Surface<'b>> where T: Into<Color> {
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<Surface<'b>> where T: Into<Color> {
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<Surface<'b>> where T: Into<Color> {
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<Font> {
unsafe {
let cstring = CString::new(path.to_str().unwrap()).unwrap();
@@ -262,11 +274,13 @@ pub fn internal_load_font(path: &Path, ptsize: u16) -> SdlResult<Font> {
}
}
/// 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<Font> {
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)
}
}
src/sdl2_ttf/lib.rs
+1 -1
View File
@@ -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,
};