Struct tetra::graphics::Texture

pub struct Texture { /* fields omitted */ }

A texture, held in GPU memory.

Supported Formats

Various file formats are supported, and can be enabled or disabled via Cargo features:

Format	Cargo feature	Enabled by default?
PNG	texture_png	Yes
JPEG	texture_jpeg	Yes
GIF	texture_gif	Yes
BMP	texture_bmp	Yes
TIFF	texture_tiff	No
TGA	texture_tga	No
WebP	texture_webp	No
ICO	texture_ico	No
PNM	texture_pnm	No
DDS/DXT	texture_dds	No

Performance

Creating a Texture is a relatively expensive operation. If you can, store them in your State struct rather than recreating them each frame.

Cloning a Texture is a very cheap operation, as the underlying data is shared between the original instance and the clone via reference-counting. This does mean, however, that updating a Texture (for example, changing its filter mode) will also update any other clones of that Texture.

Examples

The texture example demonstrates how to draw a simple texture.

Implementations

impl Texture

pub fn new<P>(ctx: &mut Context, path: P) -> Result<Texture> where
    P: AsRef<Path>, 

Creates a new texture from the given file.

The format will be determined based on the file extension.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::FailedToLoadAsset will be returned if the file could not be loaded.
• TetraError::InvalidTexture will be returned if the texture data was invalid.

pub fn from_file_data(ctx: &mut Context, data: &[u8]) -> Result<Texture>

Creates a new texture from a slice of data, encoded in one of Tetra's supported file formats (except for TGA).

This is useful in combination with include_bytes, as it allows you to include your textures directly in the binary.

The format will be determined based on the 'magic bytes' at the beginning of the data. This should be reasonably reliable, but a from_data_with_format function might have to be added later. Note that TGA files do not have recognizable magic bytes, so this function will not recognize them.

Errors

• TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
• TetraError::InvalidTexture will be returned if the texture data was invalid.

pub fn from_rgba(
    ctx: &mut Context,
    width: i32,
    height: i32,
    data: &[u8]
) -> Result<Texture>

Creates a new texture from a slice of RGBA pixel data.

This is useful if you wish to create a texture at runtime.

This method requires you to provide enough data to fill the texture. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

Errors

• TetraError::NotEnoughData will be returned if not enough data is provided to fill the texture. This is to prevent the graphics API from trying to read uninitialized memory.

pub fn width(&self) -> i32

Returns the width of the texture.

pub fn height(&self) -> i32

Returns the height of the texture.

pub fn size(&self) -> (i32, i32)

Returns the size of the canvas.

pub fn filter_mode(&self) -> FilterMode

Returns the filter mode being used by the texture.

pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)

Sets the filter mode that should be used by the texture.

pub fn set_data(
    &self,
    ctx: &mut Context,
    x: i32,
    y: i32,
    width: i32,
    height: i32,
    data: &[u8]
) -> Result

Writes RGBA pixel data to a specified region of the texture.

This method requires you to provide enough data to fill the target rectangle. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

If you want to overwrite the entire texture, the replace_data method offers a more concise way of doing this.

Errors

• TetraError::NotEnoughData will be returned if not enough data is provided to fill the target rectangle. This is to prevent the graphics API from trying to read uninitialized memory.

Panics

Panics if any part of the target rectangle is outside the bounds of the texture.

pub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result

Overwrites the entire texture with new RGBA pixel data.

This method requires you to provide enough data to fill the texture. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

If you only want to write to a subsection of the texture, use the set_data method instead.

Errors

• TetraError::NotEnoughData will be returned if not enough data is provided to fill the texture. This is to prevent the graphics API from trying to read uninitialized memory.

Trait Implementations

impl Clone for Texture

pub fn clone(&self) -> Texture

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Texture

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drawable for Texture

pub fn draw<P>(&self, ctx: &mut Context, params: P) where
    P: Into<DrawParams>, 

Draws self to the screen (or a canvas, if one is enabled), using the specified parameters.

impl PartialEq<Texture> for Texture

pub fn eq(&self, other: &Texture) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Texture) -> bool

This method tests for !=.

impl StructuralPartialEq for Texture

impl UniformValue for Texture

pub fn set_uniform(&self, ctx: &mut Context, shader: &Shader, name: &str)