pub struct Texture { /* private fields */ }Expand description
A texture, held in GPU memory.
The data can be stored in a variety of formats, as represented by the
TextureFormat enum.
Supported File Formats
Images can be decoded from various common file formats via the new
and from_encoded constructors. Individual
decoders can be enabled or disabled via Cargo feature flags.
| 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 quite an expensive operation, as it involves ‘uploading’ the texture data to the GPU. Try to reuse textures, rather than recreating them every frame.
You can clone a texture cheaply, as it is a reference-counted handle to a GPU resource. However, this does mean that modifying a texture (e.g. setting the filter mode) will also affect any clones that exist of it.
Examples
The texture
example demonstrates how to draw a simple texture.
Implementations§
source§impl Texture
impl Texture
sourcepub fn new<P>(ctx: &mut Context, path: P) -> Result<Texture>where
P: AsRef<Path>,
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::PlatformErrorwill be returned if the underlying graphics API encounters an error.TetraError::FailedToLoadAssetwill be returned if the file could not be loaded.TetraError::InvalidTexturewill be returned if the texture data was invalid.
sourcepub fn from_data(
ctx: &mut Context,
width: i32,
height: i32,
format: TextureFormat,
data: &[u8]
) -> Result<Texture>
pub fn from_data( ctx: &mut Context, width: i32, height: i32, format: TextureFormat, data: &[u8] ) -> Result<Texture>
Creates a new texture from a slice of 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::PlatformErrorwill be returned if the underlying graphics API encounters an error.TetraError::NotEnoughDatawill 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.
sourcepub fn from_encoded(ctx: &mut Context, data: &[u8]) -> Result<Texture>
pub fn from_encoded(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::PlatformErrorwill be returned if the underlying graphics API encounters an error.TetraError::InvalidTexturewill be returned if the texture data was invalid.
sourcepub fn from_image_data(ctx: &mut Context, data: &ImageData) -> Result<Texture>
pub fn from_image_data(ctx: &mut Context, data: &ImageData) -> Result<Texture>
Creates a new texture from an ImageData.
Errors
TetraError::PlatformErrorwill be returned if the underlying graphics API encounters an error.
sourcepub fn draw<P>(&self, ctx: &mut Context, params: P)where
P: Into<DrawParams>,
pub fn draw<P>(&self, ctx: &mut Context, params: P)where P: Into<DrawParams>,
Draws the texture to the screen (or to a canvas, if one is enabled).
sourcepub fn draw_region<P>(&self, ctx: &mut Context, region: Rectangle, params: P)where
P: Into<DrawParams>,
pub fn draw_region<P>(&self, ctx: &mut Context, region: Rectangle, params: P)where P: Into<DrawParams>,
Draws a region of the texture to the screen (or to a canvas, if one is enabled).
sourcepub fn draw_nine_slice<P>(
&self,
ctx: &mut Context,
config: &NineSlice,
width: f32,
height: f32,
params: P
)where
P: Into<DrawParams>,
pub fn draw_nine_slice<P>( &self, ctx: &mut Context, config: &NineSlice, width: f32, height: f32, params: P )where P: Into<DrawParams>,
Draws a region of the texture by splitting it into nine slices, allowing it to be stretched or squashed without distorting the borders.
sourcepub fn format(&self) -> TextureFormat
pub fn format(&self) -> TextureFormat
Returns the data format of the texture.
sourcepub fn filter_mode(&self) -> FilterMode
pub fn filter_mode(&self) -> FilterMode
Returns the filter mode being used by the texture.
sourcepub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
Sets the filter mode that should be used by the texture.
sourcepub fn get_data(&self, ctx: &mut Context) -> ImageData
pub fn get_data(&self, ctx: &mut Context) -> ImageData
Gets the texture’s data from the GPU.
This can be useful if you need to do some image processing on the CPU, or if you want to output the image data somewhere. This is a fairly slow operation, so avoid doing it too often!
The returned ImageData will have the same format as the texture itself.
sourcepub fn set_data(
&self,
ctx: &mut Context,
x: i32,
y: i32,
width: i32,
height: i32,
data: &[u8]
) -> Result
pub fn set_data( &self, ctx: &mut Context, x: i32, y: i32, width: i32, height: i32, data: &[u8] ) -> Result
Writes pixel data to a specified region of the texture.
The data will be interpreted based on the TextureFormat 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::NotEnoughDatawill 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.
sourcepub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result
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::NotEnoughDatawill 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§
source§impl PartialEq<Texture> for Texture
impl PartialEq<Texture> for Texture
impl StructuralPartialEq for Texture
impl UniformValue for Texture
Can be accessed via a sampler2D in your shader.