A generic palette container for colors that support transparency checking. More...

#include <palette.hpp>

Public Types
using	StorageType = std::conditional_t< N==0, std::vector< std::optional< ColorType > >, std::array< std::optional< ColorType >, N > >
	The storage type used internally, selected based on N.

Public Member Functions
	Palette ()=default
	Default constructs a Palette.

	Palette (std::vector< ColorType > colors)
	Construct this palette with a given color vector.

	Palette (std::array< ColorType, N > colors)
	Construct this palette from an array of colors.

	Palette (ColorType color)
	Constructs a Palette filled with a single color.

void	add (ColorType color)
	Adds a color to the end of the palette.

void	add_wildcard ()
	Adds a wildcard slot to the end of the palette.

void	set (std::size_t index, ColorType color)
	Sets the color at a specific index in the palette.

void	set_wildcard (std::size_t index)
	Sets a slot as a wildcard at a specific index.

bool	is_wildcard (std::size_t index) const
	Checks if a slot is a wildcard.

bool	has_any_wildcards () const
	Checks if the palette contains any wildcard slots.

std::size_t	size () const
	Returns the number of slots in the palette.

ColorType	slot_zero_color () const
	Get the slot 0 palette color.

ColorType	at (std::size_t index) const
	Gets the color at a specific index.

std::optional< ColorType >	at_optional (std::size_t index) const
	Gets the optional color at a specific index.

std::map< ColorType, PaletteIndex >	color_to_index_map () const
	Creates a map from colors to their palette indices.

std::map< PaletteIndex, ColorType >	index_to_color_map () const
	Creates a map from palette indices to their colors.

Detailed Description

template<SupportsTransparency ColorType, std::size_t N = 0>
class porytiles::Palette< ColorType, N >

A generic palette container for colors that support transparency checking.

Palette is a container for storing colors that satisfy the SupportsTransparency concept. It supports both dynamic (vector-backed) and fixed-size (array-backed) storage based on the template parameter N.

When N == 0 (the default), the palette uses std::vector for dynamic storage, allowing colors to be added incrementally. When N > 0, the palette uses std::array<T, N> for fixed-size storage with compile-time size guarantees.

Both variants support "wildcard" slots - palette positions that have no assigned color. Wildcards are represented internally as std::nullopt. Client code can use wildcards to represent partially-filled palettes or to allow flexible color assignment.

The ColorType template parameter must satisfy the SupportsTransparency concept, meaning it must provide methods for checking whether a color is transparent.

Template Parameters

ColorType	The color type of this palette must satisfy the SupportsTransparency concept
N	The fixed size of the palette (0 for dynamic sizing, default)

Definition at line 47 of file palette.hpp.

Member Typedef Documentation

◆ StorageType

template<SupportsTransparency ColorType, std::size_t N = 0>

using porytiles::Palette< ColorType, N >::StorageType = std::conditional_t<N == 0, std::vector<std::optional<ColorType> >, std::array<std::optional<ColorType>, N> >

The storage type used internally, selected based on N.

When N == 0, uses std::vector for dynamic sizing. When N > 0, uses std::array for fixed-size storage. Both use std::optional to support wildcard slots.

Definition at line 56 of file palette.hpp.

Constructor & Destructor Documentation

◆ Palette() [1/4]

template<SupportsTransparency ColorType, std::size_t N = 0>

porytiles::Palette< ColorType, N >::Palette ( )

default

Default constructs a Palette.

For dynamic palettes (N == 0), creates an empty palette. For fixed-size palettes (N > 0), creates a palette with N wildcard slots (all std::nullopt).

◆ Palette() [2/4]

template<SupportsTransparency ColorType, std::size_t N = 0>

porytiles::Palette< ColorType, N >::Palette ( std::vector< ColorType > colors )

inlineexplicit

Construct this palette with a given color vector.

Only available for dynamic palettes (N == 0). Each color in the input vector becomes a non-wildcard slot.

Parameters

colors The color vector

Definition at line 76 of file palette.hpp.

◆ Palette() [3/4]

template<SupportsTransparency ColorType, std::size_t N = 0>

porytiles::Palette< ColorType, N >::Palette ( std::array< ColorType, N > colors )

inlineexplicit

Construct this palette from an array of colors.

Only available for fixed-size palettes (N > 0). Each color in the input array becomes a non-wildcard slot.

Parameters

colors The color array

Definition at line 92 of file palette.hpp.

◆ Palette() [4/4]

template<SupportsTransparency ColorType, std::size_t N = 0>

porytiles::Palette< ColorType, N >::Palette ( ColorType color )

inlineexplicit

Constructs a Palette filled with a single color.

For dynamic palettes (N == 0), creates a palette containing 16 copies of the provided color. For fixed-size palettes (N > 0), fills all N slots with the provided color. No slots are wildcards after this construction.

Parameters

color The color to fill the palette with

Definition at line 109 of file palette.hpp.

Member Function Documentation

◆ add()

template<SupportsTransparency ColorType, std::size_t N = 0>

void porytiles::Palette< ColorType, N >::add ( ColorType color )

inline

Adds a color to the end of the palette.

Appends the provided color as a non-wildcard slot at the end of the palette. This method is only available for dynamic palettes (N == 0).

Parameters

color The color to add

Definition at line 132 of file palette.hpp.

◆ add_wildcard()

template<SupportsTransparency ColorType, std::size_t N = 0>

void porytiles::Palette< ColorType, N >::add_wildcard ( )

inline

Adds a wildcard slot to the end of the palette.

Appends a wildcard slot (std::nullopt) at the end of the palette. This method is only available for dynamic palettes (N == 0).

Definition at line 145 of file palette.hpp.

◆ at()

template<SupportsTransparency ColorType, std::size_t N = 0>

ColorType porytiles::Palette< ColorType, N >::at ( std::size_t index ) const

inline

Gets the color at a specific index.

Returns the color at the given index. Panics if the index is out of bounds or if the slot is a wildcard.

Parameters

index The index to get

Precondition: index must be less than size(); The slot at index must not be a wildcard

Returns: The color at the given index

Definition at line 276 of file palette.hpp.

◆ at_optional()

template<SupportsTransparency ColorType, std::size_t N = 0>

std::optional< ColorType > porytiles::Palette< ColorType, N >::at_optional ( std::size_t index ) const

inline

Gets the optional color at a specific index.

Returns the optional color at the given index, which may be std::nullopt if the slot is a wildcard. Panics if the index is out of bounds.

Parameters

index The index to get

Precondition: index must be less than size()

Returns: The optional color at the given index

Definition at line 298 of file palette.hpp.

◆ color_to_index_map()

template<SupportsTransparency ColorType, std::size_t N = 0>

std::map< ColorType, PaletteIndex > porytiles::Palette< ColorType, N >::color_to_index_map ( ) const

inline

Creates a map from colors to their palette indices.

Builds a lookup table that maps each non-wildcard color in the palette to its corresponding index position. Slot 0 is explicitly excluded because it is reserved for the transparent color and handled separately. Wildcard slots are also excluded.

Warning: Duplicate Color Handling: Since std::map stores only one value per key, if the palette contains duplicate colors at multiple indices, only the first occurrence (lowest index) will be stored in the map. For example, if slots 7 and 14 both contain the same RGBA color, the map will only contain an entry for slot 7.

This can cause issues when comparing tiles that were indexed using different palette slots for the same color. If you need to match tiles where the palette may have duplicate colors, use color-equivalence comparison (compare the actual palette colors at each index) rather than direct index comparison. See TilesPngWorkspace::find_existing_contiguous_tiles_by_color() for an example of this pattern.

Returns: A map from ColorType to PaletteIndex for non-wildcard indices 1 through size()-1

Definition at line 325 of file palette.hpp.

◆ has_any_wildcards()

template<SupportsTransparency ColorType, std::size_t N = 0>

bool porytiles::Palette< ColorType, N >::has_any_wildcards ( ) const

inline

Checks if the palette contains any wildcard slots.

Returns: true if any slot is a wildcard, false if all slots have colors

Definition at line 211 of file palette.hpp.

◆ index_to_color_map()

template<SupportsTransparency ColorType, std::size_t N = 0>

std::map< PaletteIndex, ColorType > porytiles::Palette< ColorType, N >::index_to_color_map ( ) const

inline

Creates a map from palette indices to their colors.

Builds a lookup table that maps each non-wildcard palette index to its corresponding color. Slot 0 is explicitly excluded because it is reserved for the transparent color and handled separately. Wildcard slots are also excluded.

Returns: A map from PaletteIndex to ColorType for non-wildcard indices 1 through size()-1

Definition at line 346 of file palette.hpp.

◆ is_wildcard()

template<SupportsTransparency ColorType, std::size_t N = 0>

bool porytiles::Palette< ColorType, N >::is_wildcard ( std::size_t index ) const

inline

Checks if a slot is a wildcard.

Returns true if the slot at the given index is a wildcard (has no assigned color). Panics if the index is out of bounds.

Parameters

index The index to check

Precondition: index must be less than size()

Returns: true if the slot is a wildcard, false otherwise

Definition at line 198 of file palette.hpp.

◆ set()

template<SupportsTransparency ColorType, std::size_t N = 0>

void porytiles::Palette< ColorType, N >::set	(	std::size_t	index,
		ColorType	color
	)

inline

Sets the color at a specific index in the palette.

Replaces the slot at the given index with the provided color, making it a non-wildcard slot. Panics if the index is out of bounds.

Parameters

index	The index at which to set the color
color	The color to set

Precondition: index must be less than size()

Definition at line 162 of file palette.hpp.

◆ set_wildcard()

template<SupportsTransparency ColorType, std::size_t N = 0>

void porytiles::Palette< ColorType, N >::set_wildcard ( std::size_t index )

inline

Sets a slot as a wildcard at a specific index.

Replaces the slot at the given index with a wildcard (std::nullopt). Panics if the index is out of bounds.

Parameters

index The index at which to set the wildcard

Precondition: index must be less than size()

Definition at line 179 of file palette.hpp.

◆ size()

template<SupportsTransparency ColorType, std::size_t N = 0>

std::size_t porytiles::Palette< ColorType, N >::size ( ) const

inline

Returns the number of slots in the palette.

For dynamic palettes (N == 0), returns the current vector size. For fixed-size palettes (N > 0), returns N.

Returns: The size of the palette

Definition at line 229 of file palette.hpp.

◆ slot_zero_color()

template<SupportsTransparency ColorType, std::size_t N = 0>

ColorType porytiles::Palette< ColorType, N >::slot_zero_color ( ) const

inline

Get the slot 0 palette color.

The slot 0 color is effectively unused by the GBA. Any tile pixel with value 0 will be treated as transparent by the hardware, thus the value in any palette's 0 slot is basically ignored. Some community tools exploit this by utilizing slot 0 for configuration, metadata, etc. (see .pla blend colors). Porytiles should respect user slot 0 preferences and do its best to ignore the value set here. It should also avoid clobbering it at all costs. Users communicate transparency information in Porytiles assets by utilizing the intrinsic/extrinsic transparency concept.

Precondition: Palette must have size >= 1; Slot 0 must not be a wildcard

Returns: The ColorType in pal slot 0

Definition at line 254 of file palette.hpp.

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

porytiles/include/porytiles/domain/models/palette.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ StorageType

Constructor & Destructor Documentation

◆ Palette() [1/4]

◆ Palette() [2/4]

◆ Palette() [3/4]

◆ Palette() [4/4]

Member Function Documentation

◆ add()

◆ add_wildcard()

◆ at()

◆ at_optional()

◆ color_to_index_map()

◆ has_any_wildcards()

◆ index_to_color_map()

◆ is_wildcard()

◆ set()

◆ set_wildcard()

◆ size()

◆ slot_zero_color()