Struct tetra::graphics::Texture [−][src]
pub struct Texture { /* fields omitted */ }
Expand description
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 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
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.
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.
Creates a new texture from an ImageData
.
Errors
TetraError::PlatformError
will be returned if the underlying graphics API encounters an error.
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::PlatformError
will be returned if the underlying graphics API encounters an error.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.
Draws the texture to the screen (or to a canvas, if one is enabled).
pub 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).
pub 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.
Returns the filter mode being used by the texture.
Sets the filter mode that should be used by the texture.
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!
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.
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
Can be accessed via a sampler2D
in your shader.
Auto Trait Implementations
impl !RefUnwindSafe for Texture
impl !UnwindSafe for Texture
Blanket Implementations
Mutably borrows from an owned value. Read more