Struct tetra::graphics::ImageData

pub struct ImageData { /* fields omitted */ }

Raw image data.

Currently, the image data is always internally represented as RGBA8. This may change, however, so this API intentionally does not expose the internal representation at the moment. Lower level access to the raw pixel data may be added in a future version.

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 or cloning an ImageData is a relatively expensive operation. If you can, store them in your State struct rather than recreating them each frame.

Implementations

impl ImageData

pub fn from_file<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.

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

pub fn from_rgba<D>(width: i32, height: i32, data: D) -> Result<ImageData> where
    D: Into<Vec<u8>>, 

Creates an ImageData from raw RGBA 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.

pub fn width(&self) -> i32

Returns the width of the image.

pub fn height(&self) -> i32

Returns the height of the image.

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

Returns the size of the image.

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!

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.

pub fn get_pixel_color(&self, position: Vec2<i32>) -> Color

Gets the color of the pixel at the specified location.

Panics

Panics if the location is outside the bounds of the image.

pub fn set_pixel_color(&mut self, position: Vec2<i32>, color: Color)

Sets the color of the pixel at the specified location.

Panics

Panics if the location is outside the bounds of the image.

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.

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.

Trait Implementations

impl Clone for ImageData

fn clone(&self) -> ImageData

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImageData

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.