An 8x8 tile backed by literal-array-based per-pixel storage of an arbitrary pixel type. More...

#include <pixel_tile.hpp>

Inheritance diagram for porytiles::PixelTile< PixelType >:

Public Member Functions
virtual	~PixelTile ()=default

	PixelTile ()

	PixelTile (std::array< PixelType, tile::size_pix > pix)

	PixelTile (const PixelType &fill_value)
	Constructs a PixelTile with all pixels set to a fill value.

auto	operator<=> (const PixelTile &) const =default

bool	is_transparent () const
	Checks if this entire PixelTile is transparent (intrinsic transparency only).

bool	is_transparent (const PixelType &extrinsic) const
	Checks if this entire PixelTile is transparent.

bool	equals_ignoring_transparency (const PixelTile &other) const
	Compares this PixelTile with another, treating all transparent pixels as equal.

bool	equals_ignoring_transparency (const PixelTile &other, const PixelType &extrinsic) const
	Compares this PixelTile with another, treating all transparent pixels as equal.

bool	equals_ignoring_transparency (const PixelTile &other, const PixelType &extrinsic, const PixelType &other_extrinsic) const
	Compares this PixelTile with another, treating transparent pixels as equal, using independent extrinsic transparency values for each tile.

PixelType	at (std::size_t i) const

PixelType	at (std::size_t row, std::size_t col) const

void	set (std::size_t i, const PixelType &p)

void	set (std::size_t row, std::size_t col, const PixelType &p)

PixelTile	flip (bool h_flip, bool v_flip) const
	Creates a flipped copy of this PixelTile.

std::set< PixelType >	unique_nontransparent_colors () const
	Returns the set of unique non-transparent colors present in this PixelTile (intrinsic transparency only).

std::set< PixelType >	unique_nontransparent_colors (const PixelType &extrinsic) const
	Returns the set of unique non-transparent colors present in this PixelTile.

const std::array< PixelType, tile::size_pix > &	pix () const

Static Public Member Functions
static std::weak_ordering	cross_et_compare (const PixelTile &a, const PixelType &a_et, const PixelTile &b, const PixelType &b_et)
	Strict weak ordering that treats transparent pixels under each side's own ET as equivalent.

Detailed Description

template<SupportsTransparency PixelType>
class porytiles::PixelTile< PixelType >

An 8x8 tile backed by literal-array-based per-pixel storage of an arbitrary pixel type.

PixelTile represents tiles using direct per-pixel storage in a 64-element array (8x8 grid). Each pixel position in the tile explicitly stores a PixelType value, providing a straightforward one-to-one mapping between tile coordinates and pixel data. This contrasts with ShapeTile, which uses a mask-based representation that maps shape regions to pixel values.

This representation is ideal for:

Direct pixel-level manipulation and access operations
Simple tile transformations like flipping that operate on individual pixels
Straightforward conversion from image data formats

The PixelType template parameter must satisfy the SupportsTransparency concept, meaning it must provide methods for checking whether a pixel is transparent. This enables transparency checking at both the intrinsic level (for pixel types like IndexPixel that have built-in transparency) and extrinsic level (for pixel types like Rgba32 where transparency is determined by comparison with a reference value).

Invariant: Default-constructed PixelTile is transparent (satisfies SupportsTransparency design invariant). That is, PixelTile<PixelType>{} produces a tile where all pixels are default-constructed (and thus transparent, assuming PixelType itself satisfies the invariant).

Template Parameters

PixelType The pixel type of this tile; must satisfy SupportsTransparency concept

Definition at line 78 of file pixel_tile.hpp.

Constructor & Destructor Documentation

◆ ~PixelTile()

template<SupportsTransparency PixelType>

virtual porytiles::PixelTile< PixelType >::~PixelTile ( )

virtualdefault

◆ PixelTile() [1/3]

template<SupportsTransparency PixelType>

porytiles::PixelTile< PixelType >::PixelTile ( )

inline

Definition at line 82 of file pixel_tile.hpp.

◆ PixelTile() [2/3]

template<SupportsTransparency PixelType>

porytiles::PixelTile< PixelType >::PixelTile ( std::array< PixelType, tile::size_pix > pix )

inlineexplicit

Definition at line 84 of file pixel_tile.hpp.

◆ PixelTile() [3/3]

template<SupportsTransparency PixelType>

porytiles::PixelTile< PixelType >::PixelTile ( const PixelType & fill_value )

inlineexplicit

Constructs a PixelTile with all pixels set to a fill value.

Parameters

fill_value The pixel value to fill all 64 pixels with

Definition at line 91 of file pixel_tile.hpp.

Member Function Documentation

◆ at() [1/2]

template<SupportsTransparency PixelType>

PixelType porytiles::PixelTile< PixelType >::at ( std::size_t i ) const

inline

Definition at line 286 of file pixel_tile.hpp.

◆ at() [2/2]

template<SupportsTransparency PixelType>

PixelType porytiles::PixelTile< PixelType >::at	(	std::size_t	row,
		std::size_t	col
	)		const

inline

Definition at line 294 of file pixel_tile.hpp.

◆ cross_et_compare()

template<SupportsTransparency PixelType>

static std::weak_ordering porytiles::PixelTile< PixelType >::cross_et_compare	(	const PixelTile< PixelType > &	a,
		const PixelType &	a_et,
		const PixelTile< PixelType > &	b,
		const PixelType &	b_et
	)

inlinestatic

Strict weak ordering that treats transparent pixels under each side's own ET as equivalent.

Performs a pairwise pixel comparison between a and b, where each side is classified using its own extrinsic transparency value (a_et for a, b_et for b):

Both transparent (under their respective ETs): equivalent, continue.
One transparent, one opaque: the transparent side sorts less.
Both opaque: raw operator<=>.

This is the strict-weak-ordering analog of equals_ignoring_transparency(other, self_et, other_et). Intended for use as a std::map / std::set comparator where entries have heterogeneous extrinsic transparency values. In particular, the cross-tileset animation lookup map in AnimTileMatcher registers primary and secondary animation key frame tiles that may have been compiled under different extrinsic transparency values.

Note: Return type is std::weak_ordering, not std::strong_ordering. There are two distinct concepts in play that both contain the word "weak":

"Strict weak ordering" as a property of the C++ Compare concept: a binary relation whose "equivalent" equivalence class is defined by !less(a,b) && !less(b,a). This describes what kind of relation a comparator must be.
std::weak_ordering as a comparison category type: the return type of a three-way comparison function indicating that elements comparing equivalent are not necessarily substitutable.

Our comparator satisfies (1) — it IS a strict weak ordering — and because elements that are equivalent under this relation are NOT substitutable (e.g., a tile whose transparent pixels are magenta and one whose transparent pixels are cyan compare equivalent for keyframe-matching purposes but have observably different raw byte data, different associated ETs, and render differently), the appropriate category type for (2) is std::weak_ordering, not std::strong_ordering. Returning std::strong_ordering would be a false claim that equivalent tiles are byte-indistinguishable.

Parameters

a	The first PixelTile to compare.
a_et	The extrinsic transparency applied to pixels of `a`.
b	The second PixelTile to compare.
b_et	The extrinsic transparency applied to pixels of `b`.

Returns: std::weak_ordering indicating a less-than, equivalent-to, or greater-than b under the cross-ET relation.

Definition at line 261 of file pixel_tile.hpp.

◆ equals_ignoring_transparency() [1/3]

template<SupportsTransparency PixelType>

bool porytiles::PixelTile< PixelType >::equals_ignoring_transparency ( const PixelTile< PixelType > & other ) const

inline

Compares this PixelTile with another, treating all transparent pixels as equal.

This method provides a semantic equality comparison that differs from operator== in that it considers all transparent pixels to be equal, regardless of their underlying representation. Two pixels are considered equal if:

Both are transparent (via intrinsic is_transparent()), OR
Neither is transparent and they compare equal via operator==

This is useful when comparing tiles where only the logical transparency state matters, not the specific pixel values. The practical application depends on the pixel type's transparency semantics. For IndexPixel, since only index 0 is intrinsically transparent, this method behaves like operator== in typical usage. However, for pixel types with more complex intrinsic transparency (e.g., hypothetical future types supporting multiple transparent representations), this method would treat all such representations as equal.

This overload is only available for pixel types that support intrinsic transparency (e.g., IndexPixel).

Parameters

other The PixelTile to compare against

Returns: True if the tiles are equivalent under transparency-ignoring semantics, false otherwise

Definition at line 151 of file pixel_tile.hpp.

◆ equals_ignoring_transparency() [2/3]

template<SupportsTransparency PixelType>

bool porytiles::PixelTile< PixelType >::equals_ignoring_transparency	(	const PixelTile< PixelType > &	other,
		const PixelType &	extrinsic
	)		const

inline

Compares this PixelTile with another, treating all transparent pixels as equal.

This method provides a semantic equality comparison that differs from operator== in that it considers all transparent pixels to be equal, regardless of their underlying representation. Two pixels are considered equal if:

Both are transparent (via extrinsic is_transparent(extrinsic)), OR
Neither is transparent and they compare equal via operator==

This is useful when comparing tiles where the specific representation of transparent pixels doesn't matter, only the logical transparency state. For example, a tile with Rgba32{255,0,255} (magenta, considered extrinsically transparent under default settings) and another with Rgba32{0,0,0,0} (black with alpha=0, also transparent) would be considered equal at those positions when using the appropriate extrinsic transparency value.

This overload is only available for pixel types that support extrinsic transparency (e.g., Rgba32).

Parameters

other	The PixelTile to compare against
extrinsic	The extrinsic transparency value to use when checking pixel transparency

Returns: True if the tiles are equivalent under transparency-ignoring semantics, false otherwise

Definition at line 180 of file pixel_tile.hpp.

◆ equals_ignoring_transparency() [3/3]

template<SupportsTransparency PixelType>

bool porytiles::PixelTile< PixelType >::equals_ignoring_transparency	(	const PixelTile< PixelType > &	other,
		const PixelType &	extrinsic,
		const PixelType &	other_extrinsic
	)		const

inline

Compares this PixelTile with another, treating transparent pixels as equal, using independent extrinsic transparency values for each tile.

This overload generalizes equals_ignoring_transparency(other, extrinsic) to the case where the two tiles were authored or compiled under different extrinsic transparency settings. Each tile's pixels are checked against that tile's own extrinsic value: extrinsic is applied to the pixels of *this, while other_extrinsic is applied to the pixels of other. Two pixels are considered equal if:

The pixel in *this is transparent under extrinsic AND the corresponding pixel in other is transparent under other_extrinsic, OR
Neither is transparent (each under its respective extrinsic) and the pixels compare equal via operator==.

This is useful when matching tiles across tilesets that do not share a single canonical transparent color. For example, a secondary tileset compiled with magenta as its extrinsic transparent color may still need to match tiles authored against a primary tileset that used a different extrinsic transparent color.

This overload is only available for pixel types that support extrinsic transparency (e.g., Rgba32).

Parameters

other	The PixelTile to compare against
extrinsic	The extrinsic transparency value applied to pixels of `*this`
other_extrinsic	The extrinsic transparency value applied to pixels of `other`

Returns: True if the tiles are equivalent under transparency-ignoring semantics, false otherwise

Definition at line 211 of file pixel_tile.hpp.

◆ flip()

template<SupportsTransparency PixelType>

PixelTile porytiles::PixelTile< PixelType >::flip	(	bool	h_flip,
		bool	v_flip
	)		const

inline

Creates a flipped copy of this PixelTile.

Returns a new PixelTile flipped according to the specified parameters. Horizontal flip reflects the tile across a vertical axis, vertical flip reflects across a horizontal axis.

Parameters

h_flip	Whether to flip horizontally
v_flip	Whether to flip vertically

Returns: A new PixelTile with the specified flips applied

Definition at line 335 of file pixel_tile.hpp.

◆ is_transparent() [1/2]

template<SupportsTransparency PixelType>

bool porytiles::PixelTile< PixelType >::is_transparent ( ) const

inline

Checks if this entire PixelTile is transparent (intrinsic transparency only).

A PixelTile is transparent if all of its pixels are intrinsically transparent. This overload is only available for pixel types that support parameterless is_transparent() (e.g., IndexPixel).

Returns: True if all pixels in the PixelTile are transparent, false otherwise

Definition at line 107 of file pixel_tile.hpp.

◆ is_transparent() [2/2]

template<SupportsTransparency PixelType>

bool porytiles::PixelTile< PixelType >::is_transparent ( const PixelType & extrinsic ) const

inline

Checks if this entire PixelTile is transparent.

A PixelTile is transparent if all of its pixels are either intrinsically or extrinsically transparent, according to the provided extrinsic transparency value. This overload is only available for pixel types that support extrinsic transparency (e.g., Rgba32).

Parameters

extrinsic The extrinsic transparency value to check each pixel against

Returns: True if all pixels in the PixelTile are transparent, false otherwise

Definition at line 124 of file pixel_tile.hpp.

◆ operator<=>()

template<SupportsTransparency PixelType>

auto porytiles::PixelTile< PixelType >::operator<=> ( const PixelTile< PixelType > & ) const

default

◆ pix()

template<SupportsTransparency PixelType>

const std::array< PixelType, tile::size_pix > & porytiles::PixelTile< PixelType >::pix ( ) const

inline

Definition at line 393 of file pixel_tile.hpp.

◆ set() [1/2]

template<SupportsTransparency PixelType>

void porytiles::PixelTile< PixelType >::set	(	std::size_t	i,
		const PixelType &	p
	)

inline

Definition at line 305 of file pixel_tile.hpp.

◆ set() [2/2]

template<SupportsTransparency PixelType>

void porytiles::PixelTile< PixelType >::set	(	std::size_t	row,
		std::size_t	col,
		const PixelType &	p
	)

inline

Definition at line 313 of file pixel_tile.hpp.

◆ unique_nontransparent_colors() [1/2]

template<SupportsTransparency PixelType>

std::set< PixelType > porytiles::PixelTile< PixelType >::unique_nontransparent_colors ( ) const

inline

Returns the set of unique non-transparent colors present in this PixelTile (intrinsic transparency only).

This method constructs and returns a std::set containing all unique non-transparent PixelType values found in the tile. Pixels are filtered using their intrinsic transparency (via parameterless is_transparent()), and only non-transparent pixels are included in the result. The set automatically handles uniqueness, so duplicate pixel values will only appear once.

This overload is only available for pixel types that support intrinsic transparency (e.g., IndexPixel). For IndexPixel tiles, this means index 0 (intrinsically transparent) will be excluded from the returned set.

Returns: A std::set containing all unique non-transparent pixel values in this tile

Definition at line 362 of file pixel_tile.hpp.

◆ unique_nontransparent_colors() [2/2]

template<SupportsTransparency PixelType>

std::set< PixelType > porytiles::PixelTile< PixelType >::unique_nontransparent_colors ( const PixelType & extrinsic ) const

inline

Returns the set of unique non-transparent colors present in this PixelTile.

This method constructs and returns a std::set containing all unique non-transparent PixelType values found in the tile. Pixels are filtered using both intrinsic and extrinsic transparency (via is_transparent(extrinsic)), and only non-transparent pixels are included in the result. The set automatically handles uniqueness, so duplicate pixel values will only appear once.

This overload is only available for pixel types that support extrinsic transparency (e.g., Rgba32). For Rgba32 tiles:

Pixels with alpha=0 (intrinsically transparent) are excluded
Pixels matching the extrinsic transparency value (e.g., magenta) are excluded
Only opaque, non-transparent pixels are included in the result

Parameters

extrinsic The extrinsic transparency value to check each pixel against

Returns: A std::set containing all unique non-transparent pixel values in this tile

Definition at line 386 of file pixel_tile.hpp.

The documentation for this class was generated from the following file:

porytiles/include/porytiles/domain/models/pixel_tile.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~PixelTile()

◆ PixelTile() [1/3]

◆ PixelTile() [2/3]

◆ PixelTile() [3/3]

Member Function Documentation

◆ at() [1/2]

◆ at() [2/2]

◆ cross_et_compare()

◆ equals_ignoring_transparency() [1/3]

◆ equals_ignoring_transparency() [2/3]

◆ equals_ignoring_transparency() [3/3]

◆ flip()

◆ is_transparent() [1/2]

◆ is_transparent() [2/2]

◆ operator<=>()

◆ pix()

◆ set() [1/2]

◆ set() [2/2]

◆ unique_nontransparent_colors() [1/2]

◆ unique_nontransparent_colors() [2/2]