OpenTTD Source: src/spritecache.cpp File Reference

OpenTTD Source 15.0-beta1

Data Structures | Functions | Variables
spritecache.cpp File Reference

Caching of sprites. More...

`#include "stdafx.h"`
`#include "random_access_file_type.h"`
`#include "spriteloader/grf.hpp"`
`#include "gfx_func.h"`
`#include "error.h"`
`#include "error_func.h"`
`#include "zoom_func.h"`
`#include "settings_type.h"`
`#include "blitter/factory.hpp"`
`#include "core/math_func.hpp"`
`#include "core/mem_func.hpp"`
`#include "video/video_driver.hpp"`
`#include "spritecache.h"`
`#include "spritecache_internal.h"`
`#include "table/sprites.h"`
`#include "table/strings.h"`
`#include "table/palette_convert.h"`
`#include "safeguards.h"`

Go to the source code of this file.

## Data Structures
struct | MemBlock
struct | GrfSpriteOffset

## Functions
static SpriteCache * | GetSpriteCache (uint index)
SpriteCache * | AllocateSpriteCache (uint index)
static SpriteFile * | GetCachedSpriteFileByName (const std::string &filename)
| Get the cached SpriteFile given the name of the file.
std::span< const std::unique_ptr< SpriteFile > > | GetCachedSpriteFiles ()
| Get the list of cached SpriteFiles.
SpriteFile & | OpenCachedSpriteFile (const std::string &filename, Subdirectory subdir, bool palette_remap)
| Open/get the SpriteFile that is cached for use in the sprite cache.
static void | CompactSpriteCache ()
| Called when holes in the sprite cache should be removed.
bool | SkipSpriteData (SpriteFile &file, uint8_t type, uint16_t num)
| Skip the given amount of sprite graphics data.
bool | SpriteExists (SpriteID id)
SpriteType | GetSpriteType (SpriteID sprite)
| Get the sprite type of a given sprite.
SpriteFile * | GetOriginFile (SpriteID sprite)
| Get the SpriteFile of a given sprite.
uint32_t | GetSpriteLocalID (SpriteID sprite)
| Get the GRF-local sprite id of a given sprite.
uint | GetSpriteCountForFile (const std::string &filename, SpriteID begin, SpriteID end)
| Count the sprites which originate from a specific file in a range of SpriteIDs.
uint | GetMaxSpriteID ()
| Get a reasonable (upper bound) estimate of the maximum SpriteID used in OpenTTD; there will be no sprites with a higher SpriteID, although there might be up to roughly a thousand unused SpriteIDs below this number.
static bool | ResizeSpriteIn (SpriteLoader::SpriteCollection &sprite, ZoomLevel src, ZoomLevel tgt)
static void | ResizeSpriteOut (SpriteLoader::SpriteCollection &sprite, ZoomLevel zoom)
static bool | PadSingleSprite (SpriteLoader::Sprite *sprite, ZoomLevel zoom, uint pad_left, uint pad_top, uint pad_right, uint pad_bottom)
static bool | PadSprites (SpriteLoader::SpriteCollection &sprite, uint8_t sprite_avail, SpriteEncoder *encoder)
static bool | ResizeSprites (SpriteLoader::SpriteCollection &sprite, uint8_t sprite_avail, SpriteEncoder *encoder)
static void * | ReadRecolourSprite (SpriteFile &file, size_t file_pos, uint num, SpriteAllocator &allocator)
| Load a recolour sprite into memory.
static void * | ReadSprite (const SpriteCache *sc, SpriteID id, SpriteType sprite_type, SpriteAllocator &allocator, SpriteEncoder *encoder)
| Read a sprite from disk.
size_t | GetGRFSpriteOffset (uint32_t id)
| Get the file offset for a specific sprite in the sprite section of a GRF.
void | ReadGRFSpriteOffsets (SpriteFile &file)
| Parse the sprite section of GRFs.
bool | LoadNextSprite (SpriteID load_index, SpriteFile &file, uint file_sprite_id)
| Load a real or recolour sprite.
void | DupSprite (SpriteID old_spr, SpriteID new_spr)
static MemBlock * | NextBlock (MemBlock *block)
static size_t | GetSpriteCacheUsage ()
void | IncreaseSpriteLRU ()
static void | DeleteEntryFromSpriteCache (uint item)
| Delete a single entry from the sprite cache.
static void | DeleteEntryFromSpriteCache ()
static void * | HandleInvalidSpriteRequest (SpriteID sprite, SpriteType requested, SpriteCache *sc, SpriteAllocator *allocator)
| Handles the case when a sprite of different type is requested than is present in the SpriteCache.
void * | GetRawSprite (SpriteID sprite, SpriteType type, SpriteAllocator *allocator, SpriteEncoder *encoder)
| Reads a sprite (from disk or sprite cache).
static void | GfxInitSpriteCache ()
void | GfxInitSpriteMem ()
void | GfxClearSpriteCache ()
| Remove all encoded sprites from the sprite cache without discarding sprite location information.
void | GfxClearFontSpriteCache ()
| Remove all encoded font sprites from the sprite cache without discarding sprite location information.

## Variables
uint | _sprite_cache_size = 4
static uint | _spritecache_items = 0
static SpriteCache * | _spritecache = nullptr
static std::vector< std::unique_ptr< SpriteFile > > | _sprite_files
static uint | _sprite_lru_counter
static MemBlock * | _spritecache_ptr
static uint | _allocated_sprite_cache_size = 0
static int | _compact_cache_counter
static std::map< uint32_t, GrfSpriteOffset > | _grf_sprite_offsets
| Map from sprite numbers to position in the GRF file.
static const size_t | S_FREE_MASK = sizeof(size_t) - 1
| S_FREE_MASK is used to mask-out lower bits of MemBlock::size If they are non-zero, the block is free.

## Detailed Description

Caching of sprites.

Definition in file spritecache.cpp.

## Function Documentation

## ◆ AllocateSpriteCache()

SpriteCache * AllocateSpriteCache | ( | uint | index | ) |

Definition at line 44 of file spritecache.cpp.

## ◆ CompactSpriteCache()

static void CompactSpriteCache | ( |  | ) |
| static

Called when holes in the sprite cache should be removed.

That is accomplished by moving the cached data.

Definition at line 770 of file spritecache.cpp.

References Debug, and S_FREE_MASK.

## ◆ DeleteEntryFromSpriteCache() [1/2]

static void DeleteEntryFromSpriteCache | ( |  | ) |
| static

Definition at line 832 of file spritecache.cpp.

## ◆ DeleteEntryFromSpriteCache() [2/2]

static void DeleteEntryFromSpriteCache | ( | uint | item | ) |
| static

Delete a single entry from the sprite cache.

Parameters

  item | Entry to delete.

Definition at line 814 of file spritecache.cpp.

References DeleteEntryFromSpriteCache(), and S_FREE_MASK.

Referenced by CacheSpriteAllocator::AllocatePtr(), DeleteEntryFromSpriteCache(), GfxClearFontSpriteCache(), and GfxClearSpriteCache().

## ◆ DupSprite()

void DupSprite | ( | SpriteID | old_spr,
|  | SpriteID | new_spr
| ) |  |

Definition at line 693 of file spritecache.cpp.

## ◆ GetCachedSpriteFileByName()

static SpriteFile * GetCachedSpriteFileByName | ( | const std::string & | filename | ) |
| static

Get the cached SpriteFile given the name of the file.

Parameters

  filename | The name of the file at the disk.

Returns
  The SpriteFile or `null`.

Definition at line 67 of file spritecache.cpp.

Referenced by GetSpriteCountForFile(), and OpenCachedSpriteFile().

## ◆ GetCachedSpriteFiles()

std::span< const std::unique_ptr< SpriteFile > > GetCachedSpriteFiles | ( |  | ) |

Get the list of cached SpriteFiles.

Returns
  Read-only list of cache SpriteFiles.

Definition at line 81 of file spritecache.cpp.

Referenced by SpriteAlignerWindow::UpdateWidgetSize().

## ◆ GetGRFSpriteOffset()

size_t GetGRFSpriteOffset | ( | uint32_t | id | ) |

Get the file offset for a specific sprite in the sprite section of a GRF.

Parameters

  id | ID of the sprite to look up.

Returns
  Position of the sprite in the sprite section or SIZE_MAX if no such sprite is present.

Definition at line 556 of file spritecache.cpp.

References _grf_sprite_offsets.

## ◆ GetMaxSpriteID()

uint GetMaxSpriteID | ( |  | ) |

Get a reasonable (upper bound) estimate of the maximum SpriteID used in OpenTTD; there will be no sprites with a higher SpriteID, although there might be up to roughly a thousand unused SpriteIDs below this number.

Note
  It's actually the number of spritecache items.

Returns
  maximum SpriteID

Definition at line 220 of file spritecache.cpp.

Referenced by SpriteAlignerWindow::OnClick(), SpriteAlignerWindow::OnQueryTextFinished(), and UpdateCursorSize().

## ◆ GetOriginFile()

SpriteFile * GetOriginFile | ( | SpriteID | sprite | ) |

Get the SpriteFile of a given sprite.

Parameters

  sprite | The sprite to look at.

Returns
  The SpriteFile.

Definition at line 170 of file spritecache.cpp.

References SpriteCache::file.

Referenced by SpriteAlignerWindow::DrawWidget(), and SpriteAlignerWindow::SetStringParameters().

## ◆ GetRawSprite()

void * GetRawSprite | ( | SpriteID | sprite,
|  | SpriteType | type,
|  | SpriteAllocator * | allocator,
|  | SpriteEncoder * | encoder
| ) |  |

Reads a sprite (from disk or sprite cache).

If the sprite is not available or of wrong type, a fallback sprite is returned.

Parameters

  sprite | Sprite to read.
  type | Expected sprite type.
  allocator | Allocator function to use. Set to nullptr to use the usual sprite cache.
  encoder | Sprite encoder to use. Set to nullptr to use the currently active blitter.

Returns
  Sprite raw data

Definition at line 960 of file spritecache.cpp.

References Debug, SpriteCache::file, HandleInvalidSpriteRequest(), Invalid, SpriteCache::length, MapGen, ReadRecolourSprite(), ReadSprite(), Recolour, and SpriteCache::type.

Referenced by HandleInvalidSpriteRequest(), and ReadSprite().

## ◆ GetSpriteCache()

static SpriteCache * GetSpriteCache | ( | uint | index | ) |
| inlinestatic

Definition at line 39 of file spritecache.cpp.

## ◆ GetSpriteCacheUsage()

static size_t GetSpriteCacheUsage | ( |  | ) |
| static

Definition at line 725 of file spritecache.cpp.

## ◆ GetSpriteCountForFile()

uint GetSpriteCountForFile | ( | const std::string & | filename,
|  | SpriteID | begin,
|  | SpriteID | end
| ) |  |

Count the sprites which originate from a specific file in a range of SpriteIDs.

Parameters

  file | The loaded SpriteFile.
  begin | First sprite in range.
  end | First sprite not in range.

Returns
  Number of sprites.

Definition at line 194 of file spritecache.cpp.

References Debug, SpriteCache::file, and GetCachedSpriteFileByName().

## ◆ GetSpriteLocalID()

uint32_t GetSpriteLocalID | ( | SpriteID | sprite | ) |

Get the GRF-local sprite id of a given sprite.

Parameters

  sprite | The sprite to look at.

Returns
  The GRF-local sprite id.

Definition at line 181 of file spritecache.cpp.

Referenced by SpriteAlignerWindow::DrawWidget(), NewGRFProfiler::EndResolve(), and SpriteAlignerWindow::SetStringParameters().

## ◆ GetSpriteType()

SpriteType GetSpriteType | ( | SpriteID | sprite | ) |

Get the sprite type of a given sprite.

Parameters

  sprite | The sprite to look at.

Returns
  the type of sprite.

Definition at line 159 of file spritecache.cpp.

References Invalid, and SpriteCache::type.

Referenced by SpriteAlignerWindow::OnClick(), and SpriteAlignerWindow::OnQueryTextFinished().

## ◆ GfxClearFontSpriteCache()

void GfxClearFontSpriteCache | ( |  | ) |

Remove all encoded font sprites from the sprite cache without discarding sprite location information.

Definition at line 1079 of file spritecache.cpp.

References DeleteEntryFromSpriteCache(), Font, and SpriteCache::type.

Referenced by AdjustGUIZoom().

## ◆ GfxClearSpriteCache()

void GfxClearSpriteCache | ( |  | ) |

Remove all encoded sprites from the sprite cache without discarding sprite location information.

Definition at line 1064 of file spritecache.cpp.

References VideoDriver::ClearSystemSprites(), DeleteEntryFromSpriteCache(), and VideoDriver::GetInstance().

Referenced by CheckBlitter().

## ◆ GfxInitSpriteCache()

static void GfxInitSpriteCache | ( |  | ) |
| static

Definition at line 1000 of file spritecache.cpp.

## ◆ GfxInitSpriteMem()

void GfxInitSpriteMem | ( |  | ) |

Definition at line 1047 of file spritecache.cpp.

## ◆ HandleInvalidSpriteRequest()

static void * HandleInvalidSpriteRequest | ( | SpriteID | sprite,
|  | SpriteType | requested,
|  | SpriteCache * | sc,
|  | SpriteAllocator * | allocator
| ) |  |
| static

Handles the case when a sprite of different type is requested than is present in the SpriteCache.

For SpriteType::Font sprites, it is normal. In other cases, default sprite is loaded instead.

Parameters

  sprite | ID of loaded sprite
  requested | requested sprite type
  sc | the currently known sprite cache for the requested sprite

Returns
  fallback sprite

Note
  this function will do UserError() in the case the fallback sprite isn't available

Definition at line 915 of file spritecache.cpp.

References Debug, Font, GetRawSprite(), MapGen, Normal, Recolour, SpriteCache::type, and SpriteCache::warned.

Referenced by GetRawSprite().

## ◆ IncreaseSpriteLRU()

void IncreaseSpriteLRU | ( |  | ) |

Definition at line 738 of file spritecache.cpp.

## ◆ LoadNextSprite()

bool LoadNextSprite | ( | SpriteID | load_index,
|  | SpriteFile & | file,
|  | uint | file_sprite_id
| ) |  |

Load a real or recolour sprite.

Parameters

  load_index | Global sprite index.
  file | GRF to load from.
  file_sprite_id | Sprite number in the GRF.
  container_version | Container version of the GRF.

Returns
  True if a valid sprite was loaded, false on any error.

Definition at line 621 of file spritecache.cpp.

References _grf_sprite_offsets, SpriteCache::control_flags, SpriteCache::file, SpriteFile::GetContainerVersion(), RandomAccessFile::GetPos(), Invalid, SpriteCache::length, MapGen, MAX_SPRITES, Normal, RandomAccessFile::ReadByte(), RandomAccessFile::ReadDword(), RandomAccessFile::ReadWord(), Recolour, RandomAccessFile::SkipBytes(), SkipSpriteData(), SpriteCache::type, and SpriteCache::warned.

Referenced by LoadFontGlyph(), LoadGrfFile(), and LoadGrfFileIndexed().

## ◆ NextBlock()

static MemBlock * NextBlock | ( | MemBlock * | block | ) |
| inlinestatic

Definition at line 720 of file spritecache.cpp.

## ◆ OpenCachedSpriteFile()

SpriteFile & OpenCachedSpriteFile | ( | const std::string & | filename,
|  | Subdirectory | subdir,
|  | bool | palette_remap
| ) |  |

Open/get the SpriteFile that is cached for use in the sprite cache.

Parameters

  filename | Name of the file at the disk.
  subdir | The sub directory to search this file in.
  palette_remap | Whether a palette remap needs to be performed for this file.

Returns
  The reference to the SpriteCache.

Definition at line 93 of file spritecache.cpp.

References GetCachedSpriteFileByName(), and SpriteFile::SeekToBegin().

Referenced by LoadGrfFile(), LoadGrfFileIndexed(), and LoadNewGRFFile().

## ◆ PadSingleSprite()

static bool PadSingleSprite | ( | SpriteLoader::Sprite * | sprite,
|  | ZoomLevel | zoom,
|  | uint | pad_left,
|  | uint | pad_top,
|  | uint | pad_right,
|  | uint | pad_bottom
| ) |  |
| static

Definition at line 284 of file spritecache.cpp.

## ◆ PadSprites()

static bool PadSprites | ( | SpriteLoader::SpriteCollection & | sprite,
|  | uint8_t | sprite_avail,
|  | SpriteEncoder * | encoder
| ) |  |
| static

Definition at line 333 of file spritecache.cpp.

## ◆ ReadGRFSpriteOffsets()

void ReadGRFSpriteOffsets | ( | SpriteFile & | file | ) |

Parse the sprite section of GRFs.

Parameters

  container_version | Container version of the GRF we're currently processing.

Definition at line 565 of file spritecache.cpp.

References _grf_sprite_offsets, SpriteFile::GetContainerVersion(), RandomAccessFile::GetPos(), RandomAccessFile::ReadByte(), RandomAccessFile::ReadDword(), SCC_MASK, SCC_PAL, SCCF_ALLOW_ZOOM_MIN_1X_32BPP, SCCF_ALLOW_ZOOM_MIN_1X_PAL, SCCF_ALLOW_ZOOM_MIN_2X_32BPP, SCCF_ALLOW_ZOOM_MIN_2X_PAL, RandomAccessFile::SeekTo(), SetBit(), and RandomAccessFile::SkipBytes().

Referenced by LoadGrfFile(), LoadGrfFileIndexed(), and LoadNewGRFFileFromFile().

## ◆ ReadRecolourSprite()

static void * ReadRecolourSprite | ( | SpriteFile & | file,
|  | size_t | file_pos,
|  | uint | num,
|  | SpriteAllocator & | allocator
| ) |  |
| static

Load a recolour sprite into memory.

Parameters

  file | GRF we're reading from.
  file_pos | Position within file.
  num | Size of the sprite in the GRF.
  allocator | Sprite allocator to use.

Returns
  Sprite data.

Definition at line 426 of file spritecache.cpp.

References _palmap_d2w, SpriteAllocator::Allocate(), SpriteFile::NeedsPaletteRemap(), RandomAccessFile::ReadBlock(), and RandomAccessFile::SeekTo().

Referenced by GetRawSprite().

## ◆ ReadSprite()

static void * ReadSprite | ( | const SpriteCache * | sc,
|  | SpriteID | id,
|  | SpriteType | sprite_type,
|  | SpriteAllocator & | allocator,
|  | SpriteEncoder * | encoder
| ) |  |
| static

Read a sprite from disk.

Parameters

  sc | Location of sprite.
  id | Sprite number.
  sprite_type | Type of sprite.
  allocator | Allocator function to use.
  encoder | Sprite encoder to use.

Returns
  Read sprite data.

Definition at line 464 of file spritecache.cpp.

References _font_zoom, SpriteAllocator::Allocate(), SpriteCache::control_flags, Sprite::data, Debug, SpriteEncoder::Encode(), SpriteCache::file, Font, SpriteFile::GetContainerVersion(), BlitterFactory::GetCurrentBlitter(), GetRawSprite(), Sprite::height, SpriteEncoder::Is32BppSupported(), SpriteLoaderGrf::LoadSprite(), SpriteLoader::CommonPixel::m, MapGen, Normal, Recolour, SpriteCache::type, Sprite::width, Sprite::x_offs, Sprite::y_offs, and ZOOM_LVL_MIN.

Referenced by GetRawSprite().

## ◆ ResizeSpriteIn()

static bool ResizeSpriteIn | ( | SpriteLoader::SpriteCollection & | sprite,
|  | ZoomLevel | src,
|  | ZoomLevel | tgt
| ) |  |
| static

Definition at line 225 of file spritecache.cpp.

## ◆ ResizeSpriteOut()

static void ResizeSpriteOut | ( | SpriteLoader::SpriteCollection & | sprite,
|  | ZoomLevel | zoom
| ) |  |
| static

Definition at line 252 of file spritecache.cpp.

## ◆ ResizeSprites()

static bool ResizeSprites | ( | SpriteLoader::SpriteCollection & | sprite,
|  | uint8_t | sprite_avail,
|  | SpriteEncoder * | encoder
| ) |  |
| static

Definition at line 381 of file spritecache.cpp.

## ◆ SkipSpriteData()

bool SkipSpriteData | ( | SpriteFile & | file,
|  | uint8_t | type,
|  | uint16_t | num
| ) |  |

Skip the given amount of sprite graphics data.

Parameters

  type | the type of sprite (compressed etc)
  num | the amount of sprites to skip

Returns
  true if the data could be correctly skipped.

Definition at line 122 of file spritecache.cpp.

References RandomAccessFile::ReadByte(), and RandomAccessFile::SkipBytes().

Referenced by LoadNewGRFFileFromFile(), and LoadNextSprite().

## ◆ SpriteExists()

bool SpriteExists | ( | SpriteID | id | ) |

Definition at line 145 of file spritecache.cpp.

## Variable Documentation

## ◆ _allocated_sprite_cache_size

uint _allocated_sprite_cache_size = 0
| static

Definition at line 111 of file spritecache.cpp.

## ◆ _compact_cache_counter

int _compact_cache_counter
| static

Definition at line 112 of file spritecache.cpp.

## ◆ _grf_sprite_offsets

std::map<uint32_t, GrfSpriteOffset> _grf_sprite_offsets
| static

Map from sprite numbers to position in the GRF file.

Definition at line 549 of file spritecache.cpp.

Referenced by GetGRFSpriteOffset(), LoadNextSprite(), and ReadGRFSpriteOffsets().

## ◆ _sprite_cache_size

uint _sprite_cache_size = 4

Definition at line 32 of file spritecache.cpp.

## ◆ _sprite_files

std::vector<std::unique_ptr<SpriteFile> > _sprite_files
| static

Definition at line 37 of file spritecache.cpp.

## ◆ _sprite_lru_counter

uint _sprite_lru_counter
| static

Definition at line 109 of file spritecache.cpp.

## ◆ _spritecache

SpriteCache* _spritecache = nullptr
| static

Definition at line 36 of file spritecache.cpp.

## ◆ _spritecache_items

uint _spritecache_items = 0
| static

Definition at line 35 of file spritecache.cpp.

## ◆ _spritecache_ptr

MemBlock* _spritecache_ptr
| static

Definition at line 110 of file spritecache.cpp.

## ◆ S_FREE_MASK

const size_t S_FREE_MASK = sizeof(size_t) - 1
| static

S_FREE_MASK is used to mask-out lower bits of MemBlock::size If they are non-zero, the block is free.

S_FREE_MASK has to ensure MemBlock is correctly aligned - it means 8B (S_FREE_MASK == 7) on 64bit systems!

Definition at line 713 of file spritecache.cpp.

Referenced by CacheSpriteAllocator::AllocatePtr(), CompactSpriteCache(), and DeleteEntryFromSpriteCache().