/* ScummVM - Graphic Adventure Engine
*
* ScummVM is the legal property of its developers, whose names
* are too numerous to list here. Please refer to the COPYRIGHT
* file distributed with this source distribution.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*
*/
//
// Sprite caching system.
//
// SpriteFile handles sprite serialization and streaming.
// SpriteCache provides bitmaps by demand; it uses SpriteFile to load sprites
// and does MRU (most-recent-use) caching.
//
// TODO: store sprite data in a specialized container type that is optimized
// for having most keys allocated in large continious sequences by default.
//
// Only for the reference: one of the ideas is for container to have a table
// of arrays of fixed size internally. When getting an item the hash would be
// first divided on array size to find the array the item resides in, then the
// item is taken from item from slot index = (hash - arrsize * arrindex).
// TODO: find out if there is already a hash table kind that follows similar
// principle.
//
//=============================================================================
#ifndef AGS_SHARED_AC_SPRITE_CACHE_H
#define AGS_SHARED_AC_SPRITE_CACHE_H
#include "common/std/memory.h"
#include "common/std/vector.h"
#include "common/std/list.h"
#include "ags/shared/ac/sprite_file.h"
#include "ags/shared/core/platform.h"
#include "ags/shared/gfx/bitmap.h"
#include "ags/shared/util/error.h"
#include "ags/shared/util/geometry.h"
namespace AGS3 {
namespace AGS {
namespace Shared {
class String;
class Stream;
class Bitmap;
} // namespace AGS3
} // namespace AGS
using namespace AGS; // FIXME later
typedef AGS::Shared::HError HAGSError;
struct SpriteInfo;
// Max size of the sprite cache, in bytes
#if AGS_PLATFORM_OS_ANDROID || AGS_PLATFORM_OS_IOS
#define DEFAULTCACHESIZE_KB (32 * 1024)
#else
#define DEFAULTCACHESIZE_KB (128 * 1024)
#endif
struct SpriteInfo;
namespace AGS {
namespace Shared {
class SpriteCache {
public:
static const sprkey_t MIN_SPRITE_INDEX = 1; // 0 is reserved for "empty sprite"
static const sprkey_t MAX_SPRITE_INDEX = INT32_MAX - 1;
static const size_t MAX_SPRITE_SLOTS = INT32_MAX;
typedef Size (*PfnAdjustSpriteSize)(const Size &size, const uint32_t sprite_flags);
typedef Bitmap *(*PfnInitSprite)(sprkey_t index, Bitmap *image, uint32_t &sprite_flags);
typedef void (*PfnPostInitSprite)(sprkey_t index);
typedef void (*PfnPrewriteSprite)(Bitmap *image);
struct Callbacks {
PfnAdjustSpriteSize AdjustSize;
PfnInitSprite InitSprite;
PfnPostInitSprite PostInitSprite;
PfnPrewriteSprite PrewriteSprite;
};
SpriteCache(std::vector &sprInfos, const Callbacks &callbacks);
~SpriteCache() = default;
// Loads sprite reference information and inits sprite stream
HError InitFile(const String &filename, const String &sprindex_filename);
// Saves current cache contents to the file
int SaveToFile(const String &filename, int store_flags, SpriteCompression compress, SpriteFileIndex &index);
// Closes an active sprite file stream
void DetachFile();
inline int GetStoreFlags() const {
return _file.GetStoreFlags();
}
inline SpriteCompression GetSpriteCompression() const {
return _file.GetSpriteCompression();
}
// Tells if there is a sprite registered for the given index;
// this includes sprites that were explicitly assigned but failed to init and were remapped
bool DoesSpriteExist(sprkey_t index) const;
// Returns sprite's resolution; or empty Size if sprite does not exist
Size GetSpriteResolution(sprkey_t index) const;
// Makes sure sprite cache has allocated slots for all sprites up to the given inclusive limit;
// returns requested index on success, or -1 on failure.
sprkey_t EnlargeTo(sprkey_t topmost);
// Finds a free slot index, if all slots are occupied enlarges sprite bank; returns index
sprkey_t GetFreeIndex();
// Returns current size of the cache, in bytes; this includes locked size too!
size_t GetCacheSize() const;
// Gets the total size of the locked sprites, in bytes
size_t GetLockedSize() const;
// Returns maximal size limit of the cache, in bytes; this includes locked size too!
size_t GetMaxCacheSize() const;
// Returns number of sprite slots in the bank (this includes both actual sprites and free slots)
size_t GetSpriteSlotCount() const;
// Tells if the sprite storage still has unoccupied slots to put new sprites in
bool HasFreeSlots() const;
// Tells if the given slot is reserved for the asset sprite, that is a "static"
// sprite cached from the game assets
bool IsAssetSprite(sprkey_t index) const;
// Loads sprite using SpriteFile if such index is known,
// frees the space if cache size reaches the limit
void PrecacheSprite(sprkey_t index);
// Locks sprite, preventing it from getting removed by the normal cache limit.
// If this is a registered sprite from the game assets, then loads it first.
// If this is a sprite with SPRCACHEFLAG_EXTERNAL flag, then does nothing,
// as these are always "locked".
// If such sprite does not exist, then fails silently.
void LockSprite(sprkey_t index);
// Unlocks sprite, putting it back into the cache logic,
// where it counts towards normal limit may be deleted to free space.
// NOTE: sprites with SPRCACHEFLAG_EXTERNAL flag cannot be unlocked,
// only explicitly removed.
// If such sprite was not present in memory, then fails silently.
void UnlockSprite(sprkey_t index);
// Unregisters sprite from the bank and returns the bitmap
Bitmap *RemoveSprite(sprkey_t index);
// Deletes particular sprite, marks slot as unused
void DeleteSprite(sprkey_t index);
// Deletes a loaded asset image (non-external) from memory, ignoring its
// locked status; this keeps an auxiliary sprite information intact,
// so that the same sprite can be cached back later.
void DisposeCached(sprkey_t index);
// Deletes all free cached asset images (non-locked, non-external)
// from memory; this keeps all the auxiliary sprite information intact,
// so that the same sprite(s) can be cached back later.
void DisposeAllFreeCached();
// Deletes all data and resets cache to the clear state
void Reset();
// Assigns new sprite for the given index; this sprite won't be auto disposed.
// *Deletes* the previous sprite if one was found at the same index.
// "flags" are SPF_* constants that define sprite's behavior in game.
bool SetSprite(sprkey_t index, std::unique_ptr image, int flags = 0);
// Assigns new dummy for the given index, silently remapping it to placeholder;
// optionally marks it as an asset placeholder.
// *Deletes* the previous sprite if one was found at the same index.
void SetEmptySprite(sprkey_t index, bool as_asset);
// Sets max cache size in bytes
void SetMaxCacheSize(size_t size);
// Loads (if it's not in cache yet) and returns bitmap by the sprite index
Bitmap *operator[](sprkey_t index);
private:
// Load sprite from game resource
size_t LoadSprite(sprkey_t index, bool lock = false);
// Remap the given index to the placeholder
void RemapSpriteToPlaceholder(sprkey_t index);
// Delete the oldest (least recently used) image in cache
void DisposeOldest();
// Keep disposing oldest elements until cache has at least the given free space
void FreeMem(size_t space);
// Initialize the empty sprite slot
void InitNullSprite(sprkey_t index);
//
// Dummy no-op variants for callbacks
//
static Size DummyAdjustSize(const Size &size, const uint32_t) { return size; }
static Bitmap *DummyInitSprite(sprkey_t, Bitmap *image, uint32_t &) { return image; }
static void DummyPostInitSprite(sprkey_t) { /* do nothing */ }
static void DummyPrewriteSprite(Bitmap *) { /* do nothing */ }
// Information required for the sprite streaming
struct SpriteData {
size_t Size = 0; // to track cache size, 0 = means don't track
uint32_t Flags = 0; // SPRCACHEFLAG* flags
std::unique_ptr Image; // actual bitmap
// MRU list reference
std::list::iterator MruIt;
SpriteData() = default;
SpriteData(SpriteData &&other) = default;
SpriteData(Bitmap *image, size_t size, uint32_t flags) : Size(size), Flags(flags), Image(image) {}
SpriteData &operator=(SpriteData &&other) = default;
// Tells if this slot has a valid sprite assigned (not empty slot)
bool IsValid() const { return Flags != 0u; }
// Tells if there actually is a registered sprite in this slot
bool DoesSpriteExist() const;
// Tells if there's a game resource corresponding to this slot
bool IsAssetSprite() const;
// Tells if a sprite failed to load from assets, and should not be used
bool IsError() const;
// Tells if sprite was added externally, not loaded from game resources
bool IsExternalSprite() const;
// Tells if sprite is locked and should not be disposed by cache logic
bool IsLocked() const;
};
// Provided map of sprite infos, to fill in loaded sprite properties
std::vector &_sprInfos;
// Array of sprite references
std::vector _spriteData;
// Placeholder sprite, returned from operator[] for a non-existing sprite
std::unique_ptr _placeholder;
Callbacks _callbacks;
SpriteFile _file;
size_t _maxCacheSize; // cache size limit
size_t _lockedSize; // size in bytes of currently locked images
size_t _cacheSize; // size in bytes of currently cached images
// MRU list: the way to track which sprites were used recently.
// When clearing up space for new sprites, cache first deletes the sprites
// that were last time used long ago.
std::list _mru;
};
} // namespace Shared
} // namespace AGS
} // namespace AGS3
#endif