scummvm-cursorfix/engines/ags/shared/ac/sprite_cache.h

/* 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 <http://www.gnu.org/licenses/>.
 *
 */

//
// 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<SpriteInfo> &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<Bitmap> 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<Bitmap> Image; // actual bitmap

		// MRU list reference
		std::list<sprkey_t>::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<SpriteInfo> &_sprInfos;
	// Array of sprite references
	std::vector<SpriteData> _spriteData;
	// Placeholder sprite, returned from operator[] for a non-existing sprite
	std::unique_ptr<Bitmap> _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<sprkey_t> _mru;

};

} // namespace Shared
} // namespace AGS
} // namespace AGS3

#endif