TGA (AKA Truevision TGA, AKA TARGA) raster image file format: C++98/STL parsing library

TGA (AKA Truevision TGA, AKA TARGA), is a raster image file format created by Truevision. It supports up to 32 bits per pixel (three 8-bit RGB channels + 8-bit alpha channel), color mapping and optional lossless RLE compression.

File extension

["tga", "icb", "vda", "vst"]

KS implementation details

License: CC0-1.0

References

This page hosts a formal specification of TGA (AKA Truevision TGA, AKA TARGA) raster image file format using Kaitai Struct. This specification can be automatically translated into a variety of programming languages to get a parsing library.

Usage

Runtime library

All parsing code for C++98/STL generated by Kaitai Struct depends on the C++/STL runtime library. You have to install it before you can parse data.

For C++, the easiest way is to clone the runtime library sources and build them along with your project.

Code

Using Kaitai Struct in C++/STL usually consists of 3 steps.

  1. We need to create an STL input stream (std::istream). One can open local file for that, or use existing std::string or char* buffer.
    #include <fstream>
    
    std::ifstream is("path/to/local/file.tga", std::ifstream::binary);
    
    #include <sstream>
    
    std::istringstream is(str);
    
    #include <sstream>
    
    const char buf[] = { ... };
    std::string str(buf, sizeof buf);
    std::istringstream is(str);
    
  2. We need to wrap our input stream into Kaitai stream:
    #include "kaitai/kaitaistream.h"
    
    kaitai::kstream ks(&is);
    
  3. And finally, we can invoke the parsing:
    tga_t data(&ks);
    

After that, one can get various attributes from the structure by invoking getter methods like:

data.num_color_map() // => Number of entries in a color map

C++98/STL source code to parse TGA (AKA Truevision TGA, AKA TARGA) raster image file format

tga.h

#ifndef TGA_H_
#define TGA_H_

// This is a generated file! Please edit source .ksy file and use kaitai-struct-compiler to rebuild

#include "kaitai/kaitaistruct.h"
#include <stdint.h>
#include <vector>

#if KAITAI_STRUCT_VERSION < 9000L
#error "Incompatible Kaitai Struct C++/STL API: version 0.9 or later is required"
#endif

/**
 * TGA (AKA Truevision TGA, AKA TARGA), is a raster image file format created by Truevision. It supports up to 32 bits per pixel (three 8-bit RGB channels + 8-bit alpha channel), color mapping and optional lossless RLE compression.
 * \sa https://www.dca.fee.unicamp.br/~martino/disciplinas/ea978/tgaffs.pdf Source
 */

class tga_t : public kaitai::kstruct {

public:
    class tga_footer_t;
    class tga_ext_area_t;

    enum color_map_enum_t {
        COLOR_MAP_ENUM_NO_COLOR_MAP = 0,
        COLOR_MAP_ENUM_HAS_COLOR_MAP = 1
    };

    enum image_type_enum_t {
        IMAGE_TYPE_ENUM_NO_IMAGE_DATA = 0,
        IMAGE_TYPE_ENUM_UNCOMP_COLOR_MAPPED = 1,
        IMAGE_TYPE_ENUM_UNCOMP_TRUE_COLOR = 2,
        IMAGE_TYPE_ENUM_UNCOMP_BW = 3,
        IMAGE_TYPE_ENUM_RLE_COLOR_MAPPED = 9,
        IMAGE_TYPE_ENUM_RLE_TRUE_COLOR = 10,
        IMAGE_TYPE_ENUM_RLE_BW = 11
    };

    tga_t(kaitai::kstream* p__io, kaitai::kstruct* p__parent = 0, tga_t* p__root = 0);

private:
    void _read();
    void _clean_up();

public:
    ~tga_t();

    class tga_footer_t : public kaitai::kstruct {

    public:

        tga_footer_t(kaitai::kstream* p__io, tga_t* p__parent = 0, tga_t* p__root = 0);

    private:
        void _read();
        void _clean_up();

    public:
        ~tga_footer_t();

    private:
        bool f_is_valid;
        bool m_is_valid;

    public:
        bool is_valid();

    private:
        bool f_ext_area;
        tga_ext_area_t* m_ext_area;
        bool n_ext_area;

    public:
        bool _is_null_ext_area() { ext_area(); return n_ext_area; };

    private:

    public:
        tga_ext_area_t* ext_area();

    private:
        uint32_t m_ext_area_ofs;
        uint32_t m_dev_dir_ofs;
        std::string m_version_magic;
        tga_t* m__root;
        tga_t* m__parent;

    public:

        /**
         * Offset to extension area
         */
        uint32_t ext_area_ofs() const { return m_ext_area_ofs; }

        /**
         * Offset to developer directory
         */
        uint32_t dev_dir_ofs() const { return m_dev_dir_ofs; }
        std::string version_magic() const { return m_version_magic; }
        tga_t* _root() const { return m__root; }
        tga_t* _parent() const { return m__parent; }
    };

    class tga_ext_area_t : public kaitai::kstruct {

    public:

        tga_ext_area_t(kaitai::kstream* p__io, tga_t::tga_footer_t* p__parent = 0, tga_t* p__root = 0);

    private:
        void _read();
        void _clean_up();

    public:
        ~tga_ext_area_t();

    private:
        uint16_t m_ext_area_size;
        std::string m_author_name;
        std::vector<std::string>* m_comments;
        std::string m_timestamp;
        std::string m_job_id;
        std::string m_job_time;
        std::string m_software_id;
        std::string m_software_version;
        uint32_t m_key_color;
        uint32_t m_pixel_aspect_ratio;
        uint32_t m_gamma_value;
        uint32_t m_color_corr_ofs;
        uint32_t m_postage_stamp_ofs;
        uint32_t m_scan_line_ofs;
        uint8_t m_attributes;
        tga_t* m__root;
        tga_t::tga_footer_t* m__parent;

    public:

        /**
         * Extension area size in bytes (always 495)
         */
        uint16_t ext_area_size() const { return m_ext_area_size; }
        std::string author_name() const { return m_author_name; }

        /**
         * Comments, organized as four lines, each consisting of 80 characters plus a NULL
         */
        std::vector<std::string>* comments() const { return m_comments; }

        /**
         * Image creation date / time
         */
        std::string timestamp() const { return m_timestamp; }

        /**
         * Internal job ID, to be used in image workflow systems
         */
        std::string job_id() const { return m_job_id; }

        /**
         * Hours, minutes and seconds spent creating the file (for billing, etc.)
         */
        std::string job_time() const { return m_job_time; }

        /**
         * The application that created the file.
         */
        std::string software_id() const { return m_software_id; }
        std::string software_version() const { return m_software_version; }
        uint32_t key_color() const { return m_key_color; }
        uint32_t pixel_aspect_ratio() const { return m_pixel_aspect_ratio; }
        uint32_t gamma_value() const { return m_gamma_value; }

        /**
         * Number of bytes from the beginning of the file to the color correction table if present
         */
        uint32_t color_corr_ofs() const { return m_color_corr_ofs; }

        /**
         * Number of bytes from the beginning of the file to the postage stamp image if present
         */
        uint32_t postage_stamp_ofs() const { return m_postage_stamp_ofs; }

        /**
         * Number of bytes from the beginning of the file to the scan lines table if present
         */
        uint32_t scan_line_ofs() const { return m_scan_line_ofs; }

        /**
         * Specifies the alpha channel
         */
        uint8_t attributes() const { return m_attributes; }
        tga_t* _root() const { return m__root; }
        tga_t::tga_footer_t* _parent() const { return m__parent; }
    };

private:
    bool f_footer;
    tga_footer_t* m_footer;

public:
    tga_footer_t* footer();

private:
    uint8_t m_image_id_len;
    color_map_enum_t m_color_map_type;
    image_type_enum_t m_image_type;
    uint16_t m_color_map_ofs;
    uint16_t m_num_color_map;
    uint8_t m_color_map_depth;
    uint16_t m_x_offset;
    uint16_t m_y_offset;
    uint16_t m_width;
    uint16_t m_height;
    uint8_t m_image_depth;
    uint8_t m_img_descriptor;
    std::string m_image_id;
    std::vector<std::string>* m_color_map;
    bool n_color_map;

public:
    bool _is_null_color_map() { color_map(); return n_color_map; };

private:
    tga_t* m__root;
    kaitai::kstruct* m__parent;

public:
    uint8_t image_id_len() const { return m_image_id_len; }
    color_map_enum_t color_map_type() const { return m_color_map_type; }
    image_type_enum_t image_type() const { return m_image_type; }
    uint16_t color_map_ofs() const { return m_color_map_ofs; }

    /**
     * Number of entries in a color map
     */
    uint16_t num_color_map() const { return m_num_color_map; }

    /**
     * Number of bits in a each color maps entry
     */
    uint8_t color_map_depth() const { return m_color_map_depth; }
    uint16_t x_offset() const { return m_x_offset; }
    uint16_t y_offset() const { return m_y_offset; }

    /**
     * Width of the image, in pixels
     */
    uint16_t width() const { return m_width; }

    /**
     * Height of the image, in pixels
     */
    uint16_t height() const { return m_height; }
    uint8_t image_depth() const { return m_image_depth; }
    uint8_t img_descriptor() const { return m_img_descriptor; }

    /**
     * Arbitrary application-specific information that is used to
     * identify image. May contain text or some binary data.
     */
    std::string image_id() const { return m_image_id; }

    /**
     * Color map
     */
    std::vector<std::string>* color_map() const { return m_color_map; }
    tga_t* _root() const { return m__root; }
    kaitai::kstruct* _parent() const { return m__parent; }
};

#endif  // TGA_H_

tga.cpp

// This is a generated file! Please edit source .ksy file and use kaitai-struct-compiler to rebuild

#include "tga.h"

tga_t::tga_t(kaitai::kstream* p__io, kaitai::kstruct* p__parent, tga_t* p__root) : kaitai::kstruct(p__io) {
    m__parent = p__parent;
    m__root = this;
    m_color_map = 0;
    m_footer = 0;
    f_footer = false;

    try {
        _read();
    } catch(...) {
        _clean_up();
        throw;
    }
}

void tga_t::_read() {
    m_image_id_len = m__io->read_u1();
    m_color_map_type = static_cast<tga_t::color_map_enum_t>(m__io->read_u1());
    m_image_type = static_cast<tga_t::image_type_enum_t>(m__io->read_u1());
    m_color_map_ofs = m__io->read_u2le();
    m_num_color_map = m__io->read_u2le();
    m_color_map_depth = m__io->read_u1();
    m_x_offset = m__io->read_u2le();
    m_y_offset = m__io->read_u2le();
    m_width = m__io->read_u2le();
    m_height = m__io->read_u2le();
    m_image_depth = m__io->read_u1();
    m_img_descriptor = m__io->read_u1();
    m_image_id = m__io->read_bytes(image_id_len());
    n_color_map = true;
    if (color_map_type() == tga_t::COLOR_MAP_ENUM_HAS_COLOR_MAP) {
        n_color_map = false;
        m_color_map = new std::vector<std::string>();
        const int l_color_map = num_color_map();
        for (int i = 0; i < l_color_map; i++) {
            m_color_map->push_back(m__io->read_bytes(((color_map_depth() + 7) / 8)));
        }
    }
}

tga_t::~tga_t() {
    _clean_up();
}

void tga_t::_clean_up() {
    if (!n_color_map) {
        if (m_color_map) {
            delete m_color_map; m_color_map = 0;
        }
    }
    if (f_footer) {
        if (m_footer) {
            delete m_footer; m_footer = 0;
        }
    }
}

tga_t::tga_footer_t::tga_footer_t(kaitai::kstream* p__io, tga_t* p__parent, tga_t* p__root) : kaitai::kstruct(p__io) {
    m__parent = p__parent;
    m__root = p__root;
    m_ext_area = 0;
    f_is_valid = false;
    f_ext_area = false;

    try {
        _read();
    } catch(...) {
        _clean_up();
        throw;
    }
}

void tga_t::tga_footer_t::_read() {
    m_ext_area_ofs = m__io->read_u4le();
    m_dev_dir_ofs = m__io->read_u4le();
    m_version_magic = m__io->read_bytes(18);
}

tga_t::tga_footer_t::~tga_footer_t() {
    _clean_up();
}

void tga_t::tga_footer_t::_clean_up() {
    if (f_ext_area && !n_ext_area) {
        if (m_ext_area) {
            delete m_ext_area; m_ext_area = 0;
        }
    }
}

bool tga_t::tga_footer_t::is_valid() {
    if (f_is_valid)
        return m_is_valid;
    m_is_valid = version_magic() == std::string("\x54\x52\x55\x45\x56\x49\x53\x49\x4F\x4E\x2D\x58\x46\x49\x4C\x45\x2E\x00", 18);
    f_is_valid = true;
    return m_is_valid;
}

tga_t::tga_ext_area_t* tga_t::tga_footer_t::ext_area() {
    if (f_ext_area)
        return m_ext_area;
    n_ext_area = true;
    if (is_valid()) {
        n_ext_area = false;
        std::streampos _pos = m__io->pos();
        m__io->seek(ext_area_ofs());
        m_ext_area = new tga_ext_area_t(m__io, this, m__root);
        m__io->seek(_pos);
        f_ext_area = true;
    }
    return m_ext_area;
}

tga_t::tga_ext_area_t::tga_ext_area_t(kaitai::kstream* p__io, tga_t::tga_footer_t* p__parent, tga_t* p__root) : kaitai::kstruct(p__io) {
    m__parent = p__parent;
    m__root = p__root;
    m_comments = 0;

    try {
        _read();
    } catch(...) {
        _clean_up();
        throw;
    }
}

void tga_t::tga_ext_area_t::_read() {
    m_ext_area_size = m__io->read_u2le();
    m_author_name = kaitai::kstream::bytes_to_str(m__io->read_bytes(41), std::string("ASCII"));
    m_comments = new std::vector<std::string>();
    const int l_comments = 4;
    for (int i = 0; i < l_comments; i++) {
        m_comments->push_back(kaitai::kstream::bytes_to_str(m__io->read_bytes(81), std::string("ASCII")));
    }
    m_timestamp = m__io->read_bytes(12);
    m_job_id = kaitai::kstream::bytes_to_str(m__io->read_bytes(41), std::string("ASCII"));
    m_job_time = kaitai::kstream::bytes_to_str(m__io->read_bytes(6), std::string("ASCII"));
    m_software_id = kaitai::kstream::bytes_to_str(m__io->read_bytes(41), std::string("ASCII"));
    m_software_version = m__io->read_bytes(3);
    m_key_color = m__io->read_u4le();
    m_pixel_aspect_ratio = m__io->read_u4le();
    m_gamma_value = m__io->read_u4le();
    m_color_corr_ofs = m__io->read_u4le();
    m_postage_stamp_ofs = m__io->read_u4le();
    m_scan_line_ofs = m__io->read_u4le();
    m_attributes = m__io->read_u1();
}

tga_t::tga_ext_area_t::~tga_ext_area_t() {
    _clean_up();
}

void tga_t::tga_ext_area_t::_clean_up() {
    if (m_comments) {
        delete m_comments; m_comments = 0;
    }
}

tga_t::tga_footer_t* tga_t::footer() {
    if (f_footer)
        return m_footer;
    std::streampos _pos = m__io->pos();
    m__io->seek((_io()->size() - 26));
    m_footer = new tga_footer_t(m__io, this, m__root);
    m__io->seek(_pos);
    f_footer = true;
    return m_footer;
}