TIM file¶

Pretty much everything else is some variation on Playstation TIM. Many files have TIM images embedded into them.

Layout¶

Offset (Bytes)	Size (Bytes)	Name	Description
0	8	m_tim_header	The header of the TIM file
8	12	m_tim_clut_header	The header of the CLUT in the TIM file
Varies	Varies	m_tim_clut_data	The data of the CLUT in the TIM file
Varies	12	m_tim_image_header	The header of the image data in the TIM file
Varies	Varies	m_tim_image_data	The actual image data of the TIM file

struct Tim¶

TIM, or PSX TIM, is an uncompressed raster image file format associated with the Sony PlayStation family of video game consoles. It supports 4- and 8-bit paletted images, and 15- and 24-bit full color images.

See also

https://github.com/myst6re/vincent-tim

See also

http://www.romhacking.net/documents/31/

Public Functions

Tim() = default¶: Default constructor.

inline explicit Tim(std::span<const char> buffer)¶

Construct a Tim object from a buffer.

Parameters:: buffer – A span containing TIM file data.

inline explicit Tim(TimHeader in_tim_header, TimClutHeader in_tim_clut_header, std::vector<Color16<ColorLayoutT::ABGR>> in_tim_clut_data, TimImageHeader in_tim_image_header, std::variant<std::vector<Bit4Values>, std::vector<std::uint8_t>, std::vector<Color16<ColorLayoutT::ABGR>>, std::vector<Color24<ColorLayoutT::BGR>>> in_tim_image_data)¶

Construct a Tim object with all its components.

Parameters:

in_tim_header – TIM header.
in_tim_clut_header – TIM CLUT header.
in_tim_clut_data – TIM CLUT data.
in_tim_image_header – TIM image header.
in_tim_image_data – TIM image data.

inline TimClutHeader get_tim_clut_header(std::span<const char> &buffer) const¶

Get the TIM CLUT header from the buffer.

Parameters:: buffer – A span containing TIM file data.
Returns:: The TIM CLUT header object.

inline std::vector<Color16<ColorLayoutT::ABGR>> get_tim_clut_data(std::span<const char> &buffer) const¶

Get the TIM CLUT data from the buffer.

Parameters:: buffer – A span containing TIM file data.
Returns:: A vector containing the TIM CLUT data.

inline TimImageHeader get_tim_image_header(std::span<const char> &buffer) const¶

Get the TIM image header from the buffer.

Parameters:: buffer – A span containing TIM file data.
Returns:: The TIM image header object.

inline decltype(m_tim_image_data) get_tim_image_data(std::span<const char> &buffer) const¶

Get the TIM image data from the buffer.

Check the validity of the TIM object.

Parameters:: buffer – A span containing TIM file data.
Returns:: A variant containing the TIM image data.
Returns:: A boolean indicating whether the TIM object is valid or not.

inline std::uint16_t width() const¶

Get the width of the TIM image.

Returns:: The width of the TIM image.

inline auto height() const¶

Get the height of the TIM image.

Returns:: The height of the TIM image.

inline std::size_t area() const¶

Get the area of the TIM image.

Returns:: The area of the TIM image.

inline auto x() const¶

Get the X coordinate of the TIM image header.

Returns:: The X coordinate of the TIM image header.

inline auto y() const¶

Get the Y coordinate of the TIM image header.

Returns:: The Y coordinate of the TIM image header.

inline auto clut_x() const¶

Get the X coordinate of the TIM color lookup table (CLUT) header.

Returns:: The X coordinate of the TIM CLUT header.

inline auto clut_y() const¶

Get the Y coordinate of the TIM color lookup table (CLUT) header.

Returns:: The Y coordinate of the TIM CLUT header.

inline auto size() const¶

Get the size of the TIM object in bytes.

Returns:: The size of the TIM object in bytes.

inline auto clut_rows() const¶

Get the number of rows in the color lookup table (CLUT).

Returns:: The number of rows in the CLUT.

inline auto clut_colors() const¶

Get the number of colors in the color lookup table (CLUT).

Returns:: The number of colors in the CLUT.

inline explicit operator bool() const¶

Check if the TIM object is valid.

Returns:: True if the TIM object is valid, false otherwise.

template<Color dstT = Tim> inline std::vector<dstT> get_colors([[maybe_unused]] const std::uint16_t row = 0U, decltype(m_tim_clut_header.rectangle().width_height()) clut_dims = {}) const¶

Get the color data of the TIM object.

Template Parameters:

dstT – The color type (default: Tim).

Parameters:

row – The row of the color lookup table (CLUT) to use (default: 0U).
clut_dims – The dimensions of the CLUT (default: {}).

Returns:

A vector of color data.

inline Tim force_tim_clut_dims(Point<std::uint16_t> width_height) const¶

Update the dimensions of the color lookup table (CLUT).

Parameters:: width_height – The new dimensions (width is the number of colors per palette, height is the number of palettes).
Returns:: A new TIM object with the updated CLUT dimensions.

inline Tim force_tim_clut_dims(std::uint16_t width, std::uint16_t height) const¶

Update the dimensions of the color lookup table (CLUT).

Parameters:

width – The new width (usually the number of colors per palette).
height – The new height (usually the number of palettes).

Returns:

A new TIM object with the updated CLUT dimensions.

inline void save(std::filesystem::path filename, decltype(m_tim_clut_header.rectangle().width_height()) clut_dims = {}, const int clut = -1) const¶

Save the TIM object to a file.

Parameters:

filename – The output file name.
clut_dims – The dimensions of the color lookup table (CLUT) (default: {}).
clut – The index of the CLUT to save (-1 for all, default: -1).

inline TimHeader tim_header() const noexcept¶

Get the TIM header.

Returns:: The TIM header.

inline TimClutHeader tim_clut_header() const noexcept¶

Get the TIM CLUT header.

Returns:: The TIM CLUT header.

inline std::vector<Color16<ColorLayoutT::ABGR>> tim_clut_data() const noexcept¶

Get the TIM CLUT data.

Returns:: A vector of TIM CLUT data.

inline TimImageHeader tim_image_header() const noexcept¶

Get the TIM image header.

Returns:: The TIM image header.

inline const std::variant<std::vector<Bit4Values>, std::vector<std::uint8_t>, std::vector<Color16<ColorLayoutT::ABGR>>, std::vector<Color24<ColorLayoutT::BGR>>> &tim_image_data() const noexcept¶

Get the TIM image data.

Returns:: A reference to the variant holding the TIM image data.

Public Static Functions

static inline TimHeader get_tim_header(std::span<const char> &buffer)¶

Get the TIM header from the buffer.

Parameters:: buffer – A span containing TIM file data.
Returns:: The TIM header object.

16-bit¶

All of these images use 15-bit high color with 1 bit for the STP flag.

1	5	5	5
STP/Alpha	Blue	Green	Red

Endianness could affect the order of the bits.

STP¶

STP stands for Special Transparency Processing. You might have to ignore the STP unless the image doesn’t look correct. The playstation has modes for how to blend things.

STP Bit	Black Color	Other Colors
Disabled (0)	Treated as a normal color (opaque)	Normal blending
Enabled (1)	Treated as transparent	Special blending

Blend Modes¶

Mode	Name	Formula	Description
0	Normal Blending	\(0.5 \times \text{Back} + 0.50 \times \text{Front}\)	Equal blending of the back and front colors, producing a 50% transparency effect.
1	Additive	\(1.0 \times \text{Back} + 1.00 \times \text{Front}\)	Adds the color values of the back and front, resulting in a brighter output color.
2	Subtractive	\(1.0 \times \text{Back} - 1.00 \times \text{Front}\)	Subtracts the front color values from the back, resulting in a darker output color.
3	Screen	\(1.0 \times \text{Back} + 0.25 \times \text{Front}\)	Adds a portion (25%) of the front color values to the back, creating a softer light effect.

Source: http://www.psxdev.net/forum/viewtopic.php?t=953

5 bit to 8 bit¶

\[\begin{split} \begin{align} f(x) = & \frac{255x}{31} \\ or\\ f(x) = & (x << 3) | (x >> 2) \end{align} \end{split}\]

Header¶

Total Size: 8 bytes

Offset (bits)	Size (bits)	Fixed Value	Description
0	8	`0x10`	Tag
8	8	`0`	Version
32	2	`0b00`, `0b01`, `0b10`, or `0b11`	BPP: Bits Per Pixel
35	1	`0` or `1`	CLP: Color Look-Up Table Present

struct TimHeader¶

Public Functions

inline constexpr std::uint8_t tag() const noexcept¶

Gets the TIM file tag.

The tag is the first byte of a TIM file and identifies the file type.

Returns:: The tag value as an 8-bit unsigned integer.

inline constexpr std::uint8_t version() const noexcept¶

Gets the TIM file version.

The version is the second byte of a TIM file and indicates the format version.

Returns:: The version value as an 8-bit unsigned integer.

constexpr TimHeader() = default¶: Default constructor.

constexpr auto operator<=>(const TimHeader&) const = default¶: Default three-way comparison.

inline constexpr BPPT bpp() const noexcept¶

Get the bits per pixel flags and CLP flag.

Returns:: The value of m_bpp.

inline constexpr bool check() const¶

Test member variables for valid values. All none values should be 0. version_ should be VERSION_VAL. tag_ should be TAG_VAL. Only valid values for bpp are 4bpp with CLP, 8bpp with CLP, 16bpp, or 24 bpp.

Returns:: true if Check test passes.

inline explicit constexpr operator bool() const¶

Implicit conversion to bool, calls check() method.

Returns:: true if Check test passes.

Public Static Attributes

static constexpr auto SIZE = std::size_t{8U}¶

The size of the TimHeader struct in bytes.

This constant stores the expected size of the TimHeader struct, in bytes. It is used in a static assertion to ensure that the size of the TimHeader struct matches the expected size at compile time.

Bits Per Pixel¶

BPP Value	Bits Per Pixel	CLP: Color Look-Up Table Present
`0b00`	4-bit	1
`0b01`	8-bit	1
`0b10`	16-bit	0
`0b11`	24-bit	0

struct BPPT¶

Public Functions

inline constexpr bool bpp4() const noexcept¶

Test bits to check if color lookup table is present and 8bpp and 16bpp are not set;

Returns:: true if 4bpp

inline constexpr bool bpp8() const noexcept¶

Test bits to check if color lookup table is present and 8bpp is set and 16bpp is not set;

Returns:: true if 8bpp

inline constexpr bool bpp16() const noexcept¶

Test bits to check if color lookup table is not present and 8bpp is not set and 16bpp is set;

Returns:: true if 16bpp

inline constexpr bool bpp24() const noexcept¶

Test bits to check if color lookup table is not present and 8bpp is set and 16bpp is set;

Returns:: true if 24bpp

inline constexpr bool color_lookup_table_present() const¶

Test bits to check if color lookup table is present and 8bpp is ignored and 16bpp is not set;

Returns:: true if 16bpp

inline constexpr bool check() const noexcept¶

Test that one of the valid states is true.

Returns:: true if is a valid state.

Sub Header¶

Total Size: 12 bytes

Offset (bytes)	Size (bytes)	Description
0	4	Length
4	2	X
6	2	Y
8	2	Width
10	2	Height

The X and Y values in the CLUT header and the image header of TIM files represent the position of the data within the VRAM (Video RAM) of the PlayStation console. These values help the system know where to place the data in the memory when rendering graphics.

X and Y are essentially the coordinates of the top-left corner of the image or the color lookup table in VRAM. In the case of the CLUT header, X is the horizontal position, and Y is the vertical position of the color lookup table within VRAM. Similarly, for the image header, X and Y represent the position of the image data within VRAM.

If you are not working with the PlayStation’s VRAM directly or emulating the rendering process, you may not need to use the X and Y values from the CLUT header and the image header. Instead, you can focus on the color and pixel data contained within the TIM files for your specific use case or application.

CLUT¶

Contains a Sub Header at the start of this section. Total Size: Sub_Header.length bytes. This section might not exist in the file. This contains the 16-bit values of colors organized in cols and rows. In some cases, game developers and graphic artists exploited the unused space in the Color Look-Up Table (CLUT) to store additional palette colors. For example, while a standard 4-bit color palette would only require 16 colors, they could utilize all 256 available colors by storing multiple 16-color palettes in a row. To properly read and display these additional colors, you would need to override the default CLUT row and column settings.

struct TimClutHeader¶

Public Functions

constexpr TimClutHeader() = default¶: Default constructor.

inline explicit constexpr TimClutHeader(TimImageHeader in_image_header)¶

Constructor with TimImageHeader parameter.

Parameters:: in_image_header – The TimImageHeader instance.

inline constexpr TimClutHeader(std::uint32_t in_size, Rectangle<std::uint16_t> in_rect)¶

Constructor with size and rectangle parameters.

Parameters:

in_size – The total header and data size in bytes.
in_rect – The dimensions of the data.

inline constexpr const TimImageHeader &image_header() const noexcept¶

Gets the TIM image header.

Provides read-only access to the image header associated with this object.

Returns:: Const reference to the TimImageHeader.

constexpr auto operator<=>(const TimClutHeader&) const = default¶: Default three-way comparison.

inline constexpr const auto &rectangle() const noexcept¶

Get the dimensions of the color lookup table. Typically, the width = number of colors, and height = number of color lookup tables. Sometimes, if there are only 16 colors (4bpp), there are multiple groups of 16 in the table.

Returns:: The dimensions of the color lookup table.

inline constexpr auto size() const¶

Get the total size of the color lookup table including the header.

Returns:: The size in bytes.

inline constexpr auto data_size() const¶

Get the total size of the color lookup table data without the header.

Returns:: The size in bytes.

inline constexpr bool check() const¶

Check if the X and Y of the rectangle are valid values. Width is usually the number of colors and should be 16 or 256.

Returns:: true if valid.

inline explicit constexpr operator bool() const¶

Implicit conversion to bool, calls check() method.

Returns:: true if check() passes.

Image Data¶

Contains a Sub Header at the start of this section. Total Size: Sub_Header.length bytes

struct TimImageHeader¶

Base header for the following raw 16-bit color image data.

Public Functions

constexpr TimImageHeader() = default¶: Default constructor.

inline constexpr TimImageHeader(std::uint32_t in_size, Rectangle<std::uint16_t> in_rect)¶

Constructor with size and rectangle parameters.

Parameters:

in_size – The total header and data size in bytes.
in_rect – The dimensions of the data.

constexpr auto operator<=>(const TimImageHeader&) const = default¶: Default three-way comparison.

inline constexpr auto size() const¶

Get the total header and data size in bytes.

Returns:: The value of m_size.

inline constexpr const auto &rectangle() const noexcept¶

Get the dimensions of the data.

Returns:: The value of m_rectangle.

inline constexpr auto data_size() const¶

Get the total size of the color lookup table data without the header.

Returns:: The size in bytes.

inline constexpr bool check() const¶

Check whether the width and height of the rectangle are greater than 0.

Returns:: true if the check passes.

inline explicit constexpr operator bool() const¶

Implicit conversion to bool, calls check() method.

Returns:: true if Check test passes.

4 bpp¶

This contains the 4-bit color keys in cols and rows. You reference the CLUT to get the color. Max 16 colors.

8 bpp¶

This contains the 8-bit color keys in cols and rows. You reference the CLUT to get the color. Max 256 colors.

16 bpp¶

This contains the 16-bit values of colors organized in cols and rows.

24 bpp¶

This contains the 24-bit values of colors organized in cols and rows.

Sources: http://www.psxdev.net/forum/viewtopic.php?t=109