pub struct ImageData { /* private fields */ }
Expand description
Raw image data.
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 |
Implementations§
source§impl ImageData
impl ImageData
sourcepub fn new<P>(path: P) -> Result<ImageData>where
P: AsRef<Path>,
pub fn new<P>(path: P) -> Result<ImageData>where P: AsRef<Path>,
Loads image data from the given file.
The format will be determined based on the file extension.
Errors
TetraError::FailedToLoadAsset
will be returned if the file could not be loaded.TetraError::InvalidTexture
will be returned if the image data was invalid.
sourcepub fn from_data<D>(
width: i32,
height: i32,
format: TextureFormat,
data: D
) -> Result<ImageData>where
D: Into<Vec<u8>>,
pub fn from_data<D>( width: i32, height: i32, format: TextureFormat, data: D ) -> Result<ImageData>where D: Into<Vec<u8>>,
Creates an ImageData
from raw pixel data.
This function takes Into<Vec<u8>>
. If you pass a Vec<u8>
, that Vec
will
be reused for the created ImageData
without reallocating. Otherwise, the data
will be copied.
This function requires you to provide enough data to fill the image’s bounds. 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 image.
sourcepub fn from_encoded(data: &[u8]) -> Result<ImageData>
pub fn from_encoded(data: &[u8]) -> Result<ImageData>
Decodes image data that is 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 image data directly in the binary.
The format will be determined based on the ‘magic bytes’ at the beginning of the data. Note that TGA files do not have recognizable magic bytes, so this function will not recognize them.
Errors
TetraError::InvalidTexture
will be returned if the image data was invalid.
sourcepub fn format(&self) -> TextureFormat
pub fn format(&self) -> TextureFormat
Returns the format of the data contained within the image.
sourcepub fn into_bytes(self) -> Vec<u8>
pub fn into_bytes(self) -> Vec<u8>
Returns the image’s underlying buffer.
sourcepub fn region(&self, region: Rectangle<i32>) -> ImageData
pub fn region(&self, region: Rectangle<i32>) -> ImageData
Creates a new ImageData
from a region.
This will copy the data into a new buffer - as such, calling this function can be expensive!
Panics
This function will panic if you try to read outside of the image’s bounds.
sourcepub fn to_texture(&self, ctx: &mut Context) -> Result<Texture>
pub fn to_texture(&self, ctx: &mut Context) -> Result<Texture>
Creates a new Texture
from the stored data.
Errors
TetraError::PlatformError
will be returned if the underlying graphics API encounters an error.
sourcepub fn get_pixel_color(&self, position: Vec2<i32>) -> Color
pub fn get_pixel_color(&self, position: Vec2<i32>) -> Color
Gets the color of the pixel at the specified location.
If the image’s TextureFormat
does not contain one of the three color channels,
the returned color will have that channel set to zero. Similarly, if the format
does not have an alpha channel, the returned color will have an alpha value of
one.
Panics
Panics if the location is outside the bounds of the image.
sourcepub fn set_pixel_color(&mut self, position: Vec2<i32>, color: Color)
pub fn set_pixel_color(&mut self, position: Vec2<i32>, color: Color)
Sets the color of the pixel at the specified location.
Any channels of the color that are not supported by the image’s TextureFormat
will be ignored. For example, if the image has TextureFormat::R8
, only the
red channel of the color will be stored.
Panics
Panics if the location is outside the bounds of the image.
sourcepub fn transform<F>(&mut self, func: F)where
F: FnMut(Vec2<i32>, Color) -> Color,
pub fn transform<F>(&mut self, func: F)where F: FnMut(Vec2<i32>, Color) -> Color,
Transforms the image data by applying a function to each pixel.
If the image’s TextureFormat
does not contain one of the three color channels,
the colors provided to the closure will have that channel set to zero. Similarly,
if the format does not have an alpha channel, the returned color will have an
alpha value of one. The unsupported channels will be ignored when writing
back to the image buffer.
sourcepub fn premultiply(&mut self)
pub fn premultiply(&mut self)
Multiplies the RGB components of each pixel by the alpha component.
This can be useful when working with premultiplied alpha blending.
If the image’s data format does not have an alpha component, this function will have no effect.