TinyTGA

Documentation

A small TGA parser designed for use with embedded-graphics targeting no-std environments but usable anywhere. Beyond parsing the image header, no other allocations are made.

tinytga provides two methods of accessing the pixel data inside a TGA file. The most convenient way is to use a color type provided by embedded-graphics to define the format stored inside the TGA file. But it is also possible to directly access the raw pixel representation instead.

Examples

Using `Tga` to draw an image

This example demonstrates how a TGA image can be drawn to a embedded-graphics draw target.

use embedded_graphics::{image::Image, pixelcolor::Rgb888, prelude::*};
use tinytga::Tga;

// Include an image from a local path as bytes
let data = include_bytes!("../tests/chessboard_4px_rle.tga");

let tga: Tga<Rgb888> = Tga::from_slice(data).unwrap();

let image = Image::new(&tga, Point::zero());

image.draw(&mut display)?;

Accessing pixels using an embedded-graphics color type

If embedded-graphics is not used to draw the TGA image, the color types provided by embedded-graphics can still be used to access the pixel data using the pixels method.

use embedded_graphics::{prelude::*, pixelcolor::Rgb888};
use tinytga::Tga;

// Include an image from a local path as bytes
let data = include_bytes!("../tests/chessboard_4px_rle.tga");

// Create a TGA instance from a byte slice.
// The color type is set by defining the type of the `img` variable.
let img: Tga<Rgb888> = Tga::from_slice(data).unwrap();

// Check the size of the image.
assert_eq!(img.size(), Size::new(4, 4));

// Collect pixels into a vector.
let pixels: Vec<_> = img.pixels().collect();

Accessing raw pixel data

If embedded-graphics is not used in the target application, the raw image data can be accessed with the pixels method on RawTga. The returned iterator produces a u32 for each pixel value.

use embedded_graphics::{prelude::*, pixelcolor::Rgb888};
use tinytga::{Bpp, Compression, DataType, ImageOrigin, RawPixel, RawTga, TgaHeader};

// Include an image from a local path as bytes.
let data = include_bytes!("../tests/chessboard_4px_rle.tga");

// Create a TGA instance from a byte slice.
let img = RawTga::from_slice(data).unwrap();

// Take a look at the raw image header.
assert_eq!(
    img.header(),
    TgaHeader {
        id_len: 0,
        has_color_map: false,
        data_type: DataType::TrueColor,
        compression: Compression::Rle,
        color_map_start: 0,
        color_map_len: 0,
        color_map_depth: None,
        x_origin: 0,
        y_origin: 4,
        width: 4,
        height: 4,
        pixel_depth: Bpp::Bits24,
        image_origin: ImageOrigin::TopLeft,
        alpha_channel_depth: 0,
    }
);

// Collect raw pixels into a vector.
let pixels: Vec<_> = img.pixels().collect();

Embedded-graphics drawing performance

tinytga uses different code paths to draw images with different ImageOrigins. The performance difference between the origins will depend on the display driver, but using images with the origin at the top left corner will generally result in the best performance.

Minimum supported Rust version

The minimum supported Rust version for tinytga is 1.61 or greater. Ensure you have the correct version of Rust installed, preferably through https://rustup.rs.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

embedded-graphics/tinytga