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 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
[src]
impl Texture
[src]pub fn new<P>(ctx: &mut Context, path: P) -> Result<Texture> where
P: AsRef<Path>,
[src]
pub fn new<P>(ctx: &mut Context, path: P) -> Result<Texture> where
P: AsRef<Path>,
[src]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>
[src]
pub fn from_file_data(ctx: &mut Context, data: &[u8]) -> Result<Texture>
[src]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_image_data(ctx: &mut Context, data: &ImageData) -> Result<Texture>
[src]
pub fn from_image_data(ctx: &mut Context, data: &ImageData) -> Result<Texture>
[src]Creates a new texture from an ImageData
.
Errors
TetraError::PlatformError
will be returned if the underlying graphics API encounters an error.
pub fn from_rgba(
ctx: &mut Context,
width: i32,
height: i32,
data: &[u8]
) -> Result<Texture>
[src]
pub fn from_rgba(
ctx: &mut Context,
width: i32,
height: i32,
data: &[u8]
) -> Result<Texture>
[src]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.
pub fn draw<P>(&self, ctx: &mut Context, params: P) where
P: Into<DrawParams>,
[src]
pub fn draw<P>(&self, ctx: &mut Context, params: P) where
P: Into<DrawParams>,
[src]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>,
[src]
pub fn draw_region<P>(&self, ctx: &mut Context, region: Rectangle, params: P) where
P: Into<DrawParams>,
[src]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>,
[src]
pub fn draw_nine_slice<P>(
&self,
ctx: &mut Context,
config: &NineSlice,
width: f32,
height: f32,
params: P
) where
P: Into<DrawParams>,
[src]Draws a region of the texture by splitting it into nine slices, allowing it to be stretched or squashed without distorting the borders.
pub fn filter_mode(&self) -> FilterMode
[src]
pub fn filter_mode(&self) -> FilterMode
[src]Returns the filter mode being used by the texture.
pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
[src]
pub fn set_filter_mode(&mut self, ctx: &mut Context, filter_mode: FilterMode)
[src]Sets the filter mode that should be used by the texture.
pub fn get_data(&self, ctx: &mut Context) -> ImageData
[src]
pub fn get_data(&self, ctx: &mut Context) -> ImageData
[src]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!
pub fn set_data(
&self,
ctx: &mut Context,
x: i32,
y: i32,
width: i32,
height: i32,
data: &[u8]
) -> Result
[src]
pub fn set_data(
&self,
ctx: &mut Context,
x: i32,
y: i32,
width: i32,
height: i32,
data: &[u8]
) -> Result
[src]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
[src]
pub fn replace_data(&self, ctx: &mut Context, data: &[u8]) -> Result
[src]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 StructuralPartialEq for Texture
[src]
impl UniformValue for Texture
[src]
Can be accessed via a sampler2D
in your shader.
Auto Trait Implementations
impl !RefUnwindSafe for Texture
impl !Send for Texture
impl !Sync for Texture
impl Unpin for Texture
impl !UnwindSafe for Texture
Blanket Implementations
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]pub fn borrow_mut(&mut self) -> &mut T
[src]
pub fn borrow_mut(&mut self) -> &mut T
[src]Mutably borrows from an owned value. Read more
impl<T> ToOwned for T where
T: Clone,
[src]
impl<T> ToOwned for T where
T: Clone,
[src]type Owned = T
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn to_owned(&self) -> T
[src]Creates owned data from borrowed data, usually by cloning. Read more
pub fn clone_into(&self, target: &mut T)
[src]
pub fn clone_into(&self, target: &mut T)
[src]🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more