Struct tesserae::Graphic

pub struct Graphic<T> { /* fields omitted */ }

A Graphic is an image composed of many Tiles in a rectangle.

The type parameter T determines whether the Graphic maintains an SDL Texture for drawing the graphic to screen. A Graphic<()> is a dummy graphic with no texture, useful only for graphics that don't get drawn to the screen.

A Graphic<Texture> contains a cached SDL texture and features additional methods for refreshing the texture cache and drawing the texture to screen. Which tiles have been drawn to the texture are stored in a special cache. Whenever update_texture is called, the tiles that have been changed relative to that cache are redrawn to the texture. The cache can be entirely invalidated by calling mark_dirty.

Methods

impl Graphic<()>

pub fn load_file<P: AsRef<Path>>(path: P) -> Result<Graphic<()>>

Load a graphic from a file given its path. Sugar for using load_from with a freshly-opened File:

Graphic::load_file(path)
// same as
Graphic::load_from(File::open(path)?) 

pub fn load_from<R: Read>(input: R) -> Result<Graphic<()>>

Load a graphic from any instance of the Read trait. Commonly used for loading files statically bundled into the binary with include_bytes!.

let g = Graphic::load_from(Cursor::new(&include_bytes!("file")[..]))

pub fn solid(width: u32, height: u32, tile: Tile) -> Graphic<()>

Create a graphic comprised of the given tile repeated width times height times.

pub fn blank(width: u32, height: u32) -> Graphic<()>

Create a blank graphic of the given size, with the tile index 0, fully transparent colors.

Graphic::blank(8,12)
// same as
Graphic::solid(8,12,Default::default())

pub fn textured<'r, T>(
    &self,
    texture_creator: &'r TextureCreator<T>
) -> Graphic<Texture<'r>>

A method to attach an SDL texture, converting the graphic from an unrenderable one to a renderable one. Commonly used straight after creation, like so:

let g = Graphics::load_file("path")?.textured(texture_creator);

Note that the texture has not rendered yet, so typically you would want to call update_texture and provide a tileset before drawing to screen.

pub fn tile_cache_textured<'r, T>(
    &self,
    texture_creator: &'r TextureCreator<T>
) -> Graphic<TileCache<'r, T>>

A method to attach a hash table of individual tile textures, converting the graphic from an unrenderable one to a renderable one. Commonly used straight after creation, like so:

let g = Graphics::load_file("path")?.tile_cache_textured(texture_creator);

Note that the texture has not rendered yet, so typically you would want to call update_texture and provide a tileset before drawing to screen.

impl<T> Graphic<T>

pub fn save<W: Write>(&self, file: &mut W) -> Result<()>

Save a graphic to some instance of Write (such as a file), using the same file format used in load_from.

pub fn width(&self) -> u32

The width of the graphic in tiles.

pub fn height(&self) -> u32

The height of the graphic in tiles.

pub fn get_tile(&self, x: u32, y: u32) -> Tile

Return the tile at the given location in the graphic. Equivalent to indexing, but returns a blank tile if out of bounds instead of a panic.

pub fn set_tile(&mut self, x: u32, y: u32, tile: Tile)

Change the tile at position (x,y) in the graphic. Equivalent to assigning to an index, but does nothing if the tile is out of bounds rather than panic.

pub fn color_tile(&mut self, x: u32, y: u32, fg: Color, bg: Color)

Set the colors of the given tile in the graphic but leave the tile index unchanged.

pub fn draw_rect(&mut self, x: u32, y: u32, width: u32, height: u32, tile: Tile)

Draw a filled rectangle starting at (x,y) in the top-left of dimensions width times height, consisting of the tile tile.

pub fn color_rect(
    &mut self,
    x: u32,
    y: u32,
    width: u32,
    height: u32,
    fg: Color,
    bg: Color
)

Change the foreground and background colors of all tiles in the rectangle starting at (x,y) in the top-left of dimensions width times height, but leaving the tile index unchanged.

pub fn draw_text(
    &mut self,
    string: &str,
    tile_set: &TileSet,
    x: u32,
    y: u32,
    fg: Color,
    bg: Color
)

Draw text using one tile per character moving leftward, starting at (x,y), according to the character map built-in to the tile set. If it overflows the end of the graphic, the text is truncated.

pub fn copy_tiles_from<U>(
    &mut self,
    other: &Graphic<U>,
    src_x: u32,
    src_y: u32,
    src_w: u32,
    src_h: u32,
    dest_x: u32,
    dest_y: u32
)

Copy tiles from another Graphic to this one. Every tile in the other graphic in the rectangle of size src_w times src_height starting at (src_x,src_y) in the top-left is copied to this graphic starting at (dest_x, dest_y).

pub fn copy_all_tiles_from<U>(
    &mut self,
    other: &Graphic<U>,
    dest_x: u32,
    dest_y: u32
)

Copy all tiles from another Graphic to this one. Every tile in the other graphic is copied to this graphic starting at (dest_x, dest_y).

impl<'r> Graphic<Texture<'r>>

pub fn load_file_textured<P: AsRef<Path>, T>(
    path: P,
    texture_creator: &'r TextureCreator<T>
) -> Result<Graphic<Texture<'r>>>

A shortcut to load a file and associate a texture in one step. Equivalent to using load_file and then textured.

pub fn mark_dirty(&mut self)

Instructs the next invocation of update_texture to redraw all tiles, regardless of whether it thinks they need redrawing.

pub fn update_texture(&mut self, tile_set: &TileSet) -> u32

Draw each tile that needs redrawing in the graphic to the internal texture using the provided tile set. Returns number of tiles redrawn.

pub fn draw<P: Into<Point>, T: RenderTarget>(
    &self,
    canvas: &mut Canvas<T>,
    position: P
)

Draw the graphic to the screen at the provided position. Note that you may wish to call update_texture and provide a tile set first, as this simply draws the cached texture.

pub fn texture(&self) -> &Texture

Get the SDL texture associated with this graphic.

impl<'r, C> Graphic<TileCache<'r, C>>

pub fn update_texture(&mut self, tile_set: &TileSet) -> u32

Draw each tile that needs redrawing in the graphic to the internal texture cache using the provided tile set. Returns number of tiles redrawn.

pub fn draw<P: Into<Point>, T: RenderTarget>(
    &self,
    canvas: &mut Canvas<T>,
    position: P
)

Draw the graphic to the screen at the provided position. Note that you may wish to call update_texture and provide a tile set first, as this simply draws the cached textures.

Trait Implementations

impl<T: Clone> Clone for Graphic<T>

fn clone(&self) -> Graphic<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Index<(u32, u32)> for Graphic<T>

type Output = Tile

The returned type after indexing.

fn index(&self, index: (u32, u32)) -> &Tile

Performs the indexing (container[index]) operation.

impl<T> IndexMut<(u32, u32)> for Graphic<T>

fn index_mut(&mut self, index: (u32, u32)) -> &mut Tile

Performs the mutable indexing (container[index]) operation.