Struct tetra::graphics::ImageData

source · [−]

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

source

pub fn new(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.

source

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.

source

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.

source

pub fn width(&self) -> i32

Returns the width of the image.

source

pub fn height(&self) -> i32

Returns the height of the image.

source

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

Returns the size of the image.

source

pub fn format(&self) -> TextureFormat

Returns the format of the data contained within the image.

source

pub fn as_bytes(&self) -> &[u8 ]ⓘNotable traits for &'_ [u8 ]`impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]`

Returns the image’s data, as a slice of raw bytes.

source

pub fn into_bytes(self) -> Vec<u8>

Returns the image’s underlying buffer.

source

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.

source

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.

source

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.

source

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.

source

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.

source