A workspace for managing canonical IndexPixel tiles destined for tiles.png output. More...

#include <tiles_png_workspace.hpp>

Public Member Functions
	TilesPngWorkspace (std::size_t capacity)
	Constructs a TilesPngWorkspace with a specified capacity, initializing all slots with transparent tiles.

	TilesPngWorkspace (const Image< IndexPixel > &img, std::size_t capacity)
	Constructs a TilesPngWorkspace from an existing IndexPixel image and capacity.

bool	insert_tile (const CanonicalPixelTile< IndexPixel > &tile)
	Attempts to insert a non-transparent tile into the workspace at the current cursor position.

std::optional< std::size_t >	first_occurrence_of (const CanonicalPixelTile< IndexPixel > &tile) const
	Finds the first occurrence index of a given canonical tile in the workspace.

CanonicalPixelTile< IndexPixel >	tile_at (std::size_t index) const
	Retrieves the canonical tile at the specified index in the workspace.

Image< IndexPixel >	export_canonical_image () const
	Exports the workspace tiles to an Image<IndexPixel> in canonical form (tiles.png format).

Image< IndexPixel >	export_original_image () const
	Exports the workspace tiles to an Image<IndexPixel> in original (pre-canonicalization) form.

bool	at_capacity () const
	Checks if the workspace has reached capacity and can no longer accept new tile insertions.

std::size_t	capacity () const
	Returns the maximum number of tiles this workspace can hold.

Detailed Description

A workspace for managing canonical IndexPixel tiles destined for tiles.png output.

TilesPngWorkspace provides a fixed-capacity container for PixelTiles that will be written to the tiles.png output file in the PorymapTilesetComponent of a Tileset. The workspace manages tile deduplication, transparent tile slots, and efficient insertion through cursor-based tracking.

Key Features:

Pre-allocated storage: The workspace pre-allocates all tile slots up to capacity with transparent tiles
Tile 0 reservation: Index 0 is always reserved for a transparent tile per pokeemerald tileset conventions
Cursor-based insertion: Tracks the next available transparent slot for O(1) insertion in the common case
Deduplication support: Maintains a mapping of canonical tile forms to their first occurrence indices
Transparent tile rejection: Refuses to insert transparent tiles (except the reserved tile 0)

Storage Model: The workspace uses a pre-allocated vector where all slots are initialized with transparent tiles. Non-transparent tiles are inserted by replacing transparent tiles at the cursor position. The cursor always points to the next available transparent slot, skipping over already-inserted non-transparent tiles.

Canonical Forms: Only non-transparent tiles are tracked in the canonical forms map for deduplication purposes. This map stores the canonical (lexicographically minimal) representation of each unique tile and all indices where that tile appears in the workspace.

Definition at line 39 of file tiles_png_workspace.hpp.

Constructor & Destructor Documentation

◆ TilesPngWorkspace() [1/2]

porytiles2::TilesPngWorkspace::TilesPngWorkspace ( std::size_t capacity )

explicit

Constructs a TilesPngWorkspace with a specified capacity, initializing all slots with transparent tiles.

Creates a workspace that can hold up to capacity tiles. All tile slots are pre-initialized with transparent tiles (tiles where every pixel is IndexPixel(0)). The cursor is initialized to position 1, as position 0 is reserved for the mandatory transparent tile per GBA tileset requirements.

After construction:

tiles_ vector contains capacity transparent tiles
cursor_ points to index 1 (first available slot after the reserved tile 0)
canonical_forms_ map is empty (transparent tiles are not tracked)
The workspace is ready to accept non-transparent tile insertions

Parameters

capacity The maximum number of tiles this workspace can hold

Definition at line 79 of file tiles_png_workspace.cpp.

◆ TilesPngWorkspace() [2/2]

porytiles2::TilesPngWorkspace::TilesPngWorkspace	(	const Image< IndexPixel > &	img,
		std::size_t	capacity
	)

explicit

Constructs a TilesPngWorkspace from an existing IndexPixel image and capacity.

Extracts 8×8 pixel tiles from the input image in row-major order and populates the workspace. The image dimensions must be multiples of 8 (the tile dimension). If the image contains more tiles than the specified capacity, the constructor panics.

Extraction Process:

Validates image dimensions are multiples of 8
Calculates the number of tiles in the image (width/8 × height/8)
Verifies the tile count does not exceed capacity
Extracts each 8×8 tile region from the image in row-major order
Creates a CanonicalPixelTile for each extracted tile
Adds non-transparent tiles to the canonical_forms_ map for deduplication
Pads the tiles_ vector to capacity with transparent tiles
Sets the cursor to the first transparent tile after tile 0

Non-transparent tile tracking: Only tiles that contain at least one non-zero IndexPixel are added to canonical_forms_. This enables efficient deduplication via first_occurrence_of() lookups.

Cursor initialization: After loading the image, the cursor is positioned at the first transparent tile index greater than 0. If all tiles from the image are non-transparent, the cursor points to the first padding tile.

Precondition: Image dimensions must be multiples of 8; Image may not contain more tiles than the specified capacity

Parameters

img	The IndexPixel image to extract tiles from; dimensions must be multiples of 8
capacity	The maximum number of tiles this workspace can hold

Definition at line 89 of file tiles_png_workspace.cpp.

Member Function Documentation

◆ at_capacity()

bool porytiles2::TilesPngWorkspace::at_capacity ( ) const

Checks if the workspace has reached capacity and can no longer accept new tile insertions.

Returns true when the cursor has reached or exceeded the capacity, indicating that all available transparent tile slots have been filled with non-transparent tiles. At this point, insert_tile() will return false for any further insertion attempts.

Note: This method returns true even if there are still transparent tiles in the workspace beyond the cursor position, as the cursor always advances forward and never backtracks.

Returns: true if cursor == capacity, false otherwise

Definition at line 222 of file tiles_png_workspace.cpp.

◆ capacity()

std::size_t porytiles2::TilesPngWorkspace::capacity ( ) const

inline

Returns the maximum number of tiles this workspace can hold.

Returns the capacity value specified during construction. This is the fixed size of the tiles_ vector and represents the maximum number of tiles (both transparent and non-transparent) that can be stored.

Returns: The workspace capacity

Definition at line 233 of file tiles_png_workspace.hpp.

◆ export_canonical_image()

Image< IndexPixel > porytiles2::TilesPngWorkspace::export_canonical_image ( ) const

Exports the workspace tiles to an Image<IndexPixel> in canonical form (tiles.png format).

Creates an Image<IndexPixel> representation of all tiles in the workspace, arranged in row-major order with 16 tiles per row (128 pixels wide). This method exports tiles in their canonical (lexicographically minimal) form as stored in the workspace, without applying any flip transformations.

Image Layout:

Width: Always 128 pixels (16 tiles × 8 pixels per tile)
Height: Calculated to accommodate all tiles in the workspace (must be a multiple of 8)
Tile arrangement: Row-major order, matching the extraction order from the constructor

Canonical Form: Each tile is exported exactly as stored in the workspace - in its canonical (lexicographically minimal) orientation among all flip variants. Flip flags are not applied during export. This is the appropriate format for tiles.png output in fresh compilations, where there is no "original" tile orientation to preserve.

Returns: An Image<IndexPixel> containing all workspace tiles in canonical form (tiles.png format)

Definition at line 212 of file tiles_png_workspace.cpp.

◆ export_original_image()

Image< IndexPixel > porytiles2::TilesPngWorkspace::export_original_image ( ) const

Exports the workspace tiles to an Image<IndexPixel> in original (pre-canonicalization) form.

Creates an Image<IndexPixel> representation of all tiles in the workspace, arranged in row-major order with 16 tiles per row (128 pixels wide). This method applies flip transformations to restore tiles to their original orientations as they were before canonicalization.

Image Layout:

Width: Always 128 pixels (16 tiles × 8 pixels per tile)
Height: Calculated to accommodate all tiles in the workspace (must be a multiple of 8)
Tile arrangement: Row-major order, matching the extraction order from the constructor

Original Form Restoration: Each tile is exported with flip transformations applied based on its stored h_flip and v_flip flags. This reverses the canonicalization process, restoring tiles to their original pixel arrangements. This enables round-trip preservation: original image → workspace → exported original image, which is particularly useful in patch builds.

Returns: An Image<IndexPixel> containing all workspace tiles in original (flipped) form

Definition at line 217 of file tiles_png_workspace.cpp.

◆ first_occurrence_of()

std::optional< std::size_t > porytiles2::TilesPngWorkspace::first_occurrence_of ( const CanonicalPixelTile< IndexPixel > & tile ) const

Finds the first occurrence index of a given canonical tile in the workspace.

Searches the canonical_forms_ map for the given tile and returns the index of its first occurrence in the workspace. This method only finds non-transparent tiles that have been explicitly inserted or loaded from an image during construction.

Deduplication Use Case: This method is used to check if a tile already exists in the workspace before inserting it. If the tile is found, the caller can reuse the existing tile's index rather than inserting a duplicate.

Transparent Tiles: Transparent tiles are never tracked in canonical_forms_, so this method will always return std::nullopt for any transparent tile, even though the workspace may contain many transparent tiles. Since tile 0 is guaranteed to be transparent, callers who need to index into a transparent tile can always just use tile 0 instead of searching for one.

Parameters

tile	The canonical pixel tile to search for

Returns: The index of the tile's first occurrence if found, std::nullopt otherwise

Definition at line 194 of file tiles_png_workspace.cpp.

◆ insert_tile()

bool porytiles2::TilesPngWorkspace::insert_tile ( const CanonicalPixelTile< IndexPixel > & tile )

Attempts to insert a non-transparent tile into the workspace at the current cursor position.

Inserts the given canonical tile at the cursor position, replacing the transparent tile that was there. After insertion, the cursor is advanced to the next available transparent tile slot. The inserted tile is added to the canonical_forms_ map for deduplication support.

Insertion Criteria:

Returns false if the workspace is at capacity (cursor >= capacity)
Returns false if the tile is transparent (no point inserting transparent tiles)
Returns true if the tile was successfully inserted

Post-insertion State:

The tile replaces the transparent tile at the cursor position
The tile's canonical form is added to canonical_forms_ with its index
The cursor advances to the next transparent tile (or reaches capacity)
Fast-forward: The cursor skips over any non-transparent tiles to find the next available slot

Cursor Fast-Forward: After inserting a tile, the cursor is incremented and then fast-forwarded through any non-transparent tiles until it finds the next transparent slot or reaches capacity. This ensures O(1) insertion for the next insert_tile call in the common case.

Parameters

tile	The canonical pixel tile to insert; must be non-transparent for successful insertion

Returns: true if the tile was successfully inserted, false if the workspace is at capacity or the tile is transparent

Definition at line 166 of file tiles_png_workspace.cpp.

◆ tile_at()

CanonicalPixelTile< IndexPixel > porytiles2::TilesPngWorkspace::tile_at ( std::size_t index ) const

Retrieves the canonical tile at the specified index in the workspace.

Returns a copy of the CanonicalPixelTile at the given index. The index must be within the bounds of the tiles_ vector (0 to capacity - 1). This method provides read-only access to any tile in the workspace, including transparent tiles and non-transparent tiles.

Bounds Checking: If the index is out of bounds, the method panics with an error message indicating the invalid index and the workspace size.

Parameters

index The zero-based index of the tile to retrieve; must be < capacity

Precondition: index must be less than tiles_.size()

Returns: A copy of the CanonicalPixelTile at the specified index

Definition at line 204 of file tiles_png_workspace.cpp.

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

Porytiles2/include/porytiles2/domain/models/tiles_png_workspace.hpp
Porytiles2/lib/domain/models/tiles_png_workspace.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TilesPngWorkspace() [1/2]

◆ TilesPngWorkspace() [2/2]

Member Function Documentation

◆ at_capacity()

◆ capacity()

◆ export_canonical_image()

◆ export_original_image()

◆ first_occurrence_of()

◆ insert_tile()

◆ tile_at()