Jazz2::Tiles::TileSet class

Represents tile set used by tile map, consists of texture and collision mask.

Holds the source texture and the per-tile collision masks for a single tile set, providing lookups for a tile's mask and texture coordinates. A tile map references one or more of these to render and collide its layers; textures may be true-color or indexed for palette recoloring.

Public static variables

static std::int32_t DefaultTileSize constexpr
Size of a tile.
static std::int32_t TilePadding constexpr
Border of duplicated edge pixels around every tile in the atlas.
static std::int32_t PaddedTileSize constexpr
Size one tile occupies in the atlas, including TilePadding on each side.
static std::int32_t MaskBytesPerTile constexpr
Byte size of one tile's packed collision mask (1 bit per pixel, LSB-first, row-major - the cache file format).
static std::uint8_t TileEffectReflective constexpr
Bit of GetTileEffectInfo() set for a tile with a reflection — a visible texel with some blue.
static std::uint8_t TileEffectDisplaces constexpr
Bit of GetTileEffectInfo() set for a tile that displaces — a visible texel with red or green other than 128.
static std::uint8_t TileEffectTopRowMask constexpr
Bits of GetTileEffectInfo() holding the first visible row of the tile, DefaultTileSize if it has none.

Public static functions

static auto GetTileMaskRow(const std::uint8_t* packedMask, std::int32_t y) -> std::uint32_t
Returns one row of a packed tile mask as a 32-bit word (bit x set = column x solid).
static auto IsTileMaskBitSet(const std::uint8_t* packedMask, std::int32_t x, std::int32_t y) -> bool
Returns whether pixel (x, y) of a packed tile mask is solid.
static auto GetTexelEffectBits(std::uint32_t rgba) -> std::uint8_t constexpr
Returns the bits of GetTileEffectInfo() a visible texel of a given color sets, red in the lowest byte.

Constructors, destructors, conversion operators

TileSet(StringView path, std::uint16_t tileCount, SmallVector<std::unique_ptr<Texture>, 1>&& textureDiffuse, std::unique_ptr<std::uint8_t[]> mask, std::uint32_t maskSize, std::unique_ptr<Color[]> captionTile, const std::uint8_t* tileDiffuseOpaque = nullptr)
Creates a new instance.

Public functions

auto MapToAtlasSlot(std::int32_t tileId) const -> std::int32_t
Returns the atlas slot a tile ID occupies, which is the ID itself unless the atlas was packed.
auto ResolveTextureDiffuse(std::int32_t& tileId) const -> Texture*
Resolves the diffuse texture chunk containing tileId, rebasing the ID into the chunk's local space (mirrors TileMap::ResolveTileSet).
auto GetTextureCount() const -> std::int32_t
Returns the number of diffuse texture chunks (1 unless the device texture-size limit forced a split).
auto GetTileMask(std::int32_t tileId) const -> const std::uint8_t*
Returns the packed mask (MaskBytesPerTile bytes, 1 bit per pixel) for the specified tile.
auto IsTileMaskEmpty(std::int32_t tileId) const -> bool
Returns true if the mask of a tile is completely empty.
auto IsTileMaskFilled(std::int32_t tileId) const -> bool
Returns true if the mask of a tile is completely filled (non-empty).
auto IsColumnContiguous(std::int32_t tileId) const -> bool
Returns true if every column of the tile's mask is vertically contiguous (no gaps).
auto GetColumnSpans(std::int32_t tileId) const -> const std::uint8_t*
Returns per-column solid spans for a tile.
auto IsTileFilled(std::int32_t tileId) const -> bool
Returns true if the texture of a tile is completely opaque (non-transparent).
auto IsTileOpaque(std::int32_t tileId) const -> bool
Returns true if a tile draws every pixel fully opaque with the palette the tile set was built with.
auto GetTileEffectInfo(std::int32_t tileId) const -> std::uint8_t
Returns what a blur-behind layer needs to know about a tile.
void SetTileEffectInfo(std::unique_ptr<std::uint8_t[]> tileEffectInfo)
Sets the table returned by GetTileEffectInfo(), one byte per tile.
auto IsTilePixelVisible(std::int32_t tileId, std::int32_t x, std::int32_t y) const -> bool
Returns whether a pixel of a tile is drawn (not transparent).
void SetTileVisibleMask(std::unique_ptr<std::uint8_t[]> visibleMask)
Sets the visibility mask of the tiles, packed as the collision mask (MaskBytesPerTile bytes each).
auto GetCaptionTile() const -> StaticArrayView<DefaultTileSize*DefaultTileSize, Color>
Returns a caption tile.
auto OverrideTileDiffuse(std::int32_t tileId, StaticArrayView<PaddedTileSize*PaddedTileSize, std::uint32_t> tileDiffuse) -> bool
Overrides the diffuse texture of the specified tile.
auto OverrideTileMask(std::int32_t tileId, StaticArrayView<DefaultTileSize*DefaultTileSize, const std::uint8_t> tileMask) -> bool
Overrides the collision mask of the specified tile.

Public variables

String FilePath
Relative path to source file.
SmallVector<std::unique_ptr<Texture>, 1> TextureDiffuse
Main (diffuse) texture(s): a single texture normally, consecutive row-band chunks when the device texture-size limit forced a split.
std::int32_t TileCount
Total number of tiles.
std::int32_t TilesPerRow
Number of tiles per row.
std::int32_t TilesPerTexture
Number of tiles covered by each diffuse texture chunk (0 when untextured/headless).
bool IsIndexed
Whether TextureDiffuse stores raw palette indices instead of baked colors.
std::unique_ptr<std::uint16_t[]> AtlasSlot
Maps a tile ID to the slot it occupies in the diffuse texture, or nullptr when they are the same.

Function documentation

Jazz2::Tiles::TileSet::TileSet(StringView path, std::uint16_t tileCount, SmallVector<std::unique_ptr<Texture>, 1>&& textureDiffuse, std::unique_ptr<std::uint8_t[]> mask, std::uint32_t maskSize, std::unique_ptr<Color[]> captionTile, const std::uint8_t* tileDiffuseOpaque = nullptr)

Creates a new instance.

Parameters
path Relative path to the source file
tileCount Total number of tiles
textureDiffuse Main (diffuse) texture, or several row-band chunks when the device texture-size limit forced a split (see ContentResolver::BuildTilesetDiffuse)
mask Packed collision mask of all tiles (MaskBytesPerTile bytes each)
maskSize Size of the packed collision mask in bytes
captionTile Pixels of the caption tile
tileDiffuseOpaque Optional table marking fully opaque tiles

std::int32_t Jazz2::Tiles::TileSet::MapToAtlasSlot(std::int32_t tileId) const

Returns the atlas slot a tile ID occupies, which is the ID itself unless the atlas was packed.

Anything that treats an ID as a position in the diffuse texture - the UV maths, and the chunk index when the atlas was split - has to go through this first. One array load; the per-tile collision data stays indexed by the original ID.

Texture* Jazz2::Tiles::TileSet::ResolveTextureDiffuse(std::int32_t& tileId) const

Resolves the diffuse texture chunk containing tileId, rebasing the ID into the chunk's local space (mirrors TileMap::ResolveTileSet).

The returned texture's tile grid starts at the rebased tileId 0, so the usual (tileId % TilesPerRow, tileId / TilesPerRow) UV math applies against ITS size. Returns nullptr when untextured (headless) or out of range.

bool Jazz2::Tiles::TileSet::IsColumnContiguous(std::int32_t tileId) const

Returns true if every column of the tile's mask is vertically contiguous (no gaps).

Contiguity allows replacing the per-pixel collision scan with an exact per-column span test.

const std::uint8_t* Jazz2::Tiles::TileSet::GetColumnSpans(std::int32_t tileId) const

Returns per-column solid spans for a tile.

2 bytes per column (first solid row, last solid row); a first row of 0xFF marks an empty column. Only meaningful when IsColumnContiguous() returns true.

bool Jazz2::Tiles::TileSet::IsTileOpaque(std::int32_t tileId) const

Returns true if a tile draws every pixel fully opaque with the palette the tile set was built with.

Stricter than IsTileFilled() for an indexed tile set, whose tiles are recolored from the palette at draw time: a filled tile only uses no transparent texel, while an opaque one also uses no translucent palette colour. Holds for as long as that palette is in effect. The content loader works it out for indexed tiles only where the tile map reads it (TILEMAP_PER_TILE_OPACITY), and leaves it false elsewhere.

std::uint8_t Jazz2::Tiles::TileSet::GetTileEffectInfo(std::int32_t tileId) const

Returns what a blur-behind layer needs to know about a tile.

The first visible row of the tile in the bits of TileEffectTopRowMask, which is where the mirror line of a reflection that starts with this tile lies, TileEffectReflective if the tile has a reflection at all and TileEffectDisplaces if it moves what is behind it (see LayerRendererType::BlurBehind). Worked out when the tile set is built, with the palette in effect then.

bool Jazz2::Tiles::TileSet::IsTilePixelVisible(std::int32_t tileId, std::int32_t x, std::int32_t y) const

Returns whether a pixel of a tile is drawn (not transparent).

By the visibility mask of the tiles if the content loader made one (see SetTileVisibleMask()), by whether the whole tile is drawn otherwise.

Variable documentation

static std::int32_t Jazz2::Tiles::TileSet::TilePadding constexpr

Border of duplicated edge pixels around every tile in the atlas.

A tile is copied into the atlas with its edge row and column repeated around it, so that a sampler reaching a texel outside the tile - which a bilinear tap does by definition, and a point sampler does when a tile lands on a fractional screen position - reads the tile's own edge instead of its neighbour's pixels. It costs (34*34)/(32*32), about 13% of every atlas.

The Nintendo 64 drops it: there the level is drawn at 1:1 into a 320x240 framebuffer with point sampling and whole-pixel tile positions, so no sample can land outside the tile, and the atlas of a large level is among the biggest allocations on a console that has 6 MB of heap for everything. Any platform that scales the tile layer or samples it bilinearly needs the border.

bool Jazz2::Tiles::TileSet::IsIndexed

Whether TextureDiffuse stores raw palette indices instead of baked colors.

Indexed tiles (red channel holds the index) are recolored at draw time through the palette shaders. false for tilesets containing 32-bit true-color tiles.

std::unique_ptr<std::uint16_t[]> Jazz2::Tiles::TileSet::AtlasSlot

Maps a tile ID to the slot it occupies in the diffuse texture, or nullptr when they are the same.

A tileset describes every tile its author drew, but a level references only a part of them - under half, on the levels measured. Where memory is scarce the atlas holds only the referenced tiles, packed together, and this table says where each ID ended up. Slot 0 is left blank and is what every pruned or out-of-range ID maps to, so a tile that appears later (a script placing one, say) draws as empty rather than sampling whatever happens to sit at its old position.