scummvm-cursorfix/engines/ags/shared/ac/sprite_file.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/>.
 *
 */

 //=============================================================================
 //
 // SpriteFile class handles sprite file parsing and streaming sprites.
 // SpriteFileWriter manages writing sprites into the output stream one by one,
 // accumulating index information, and may therefore be suitable for a variety
 // of situations.
 //
 //=============================================================================

#ifndef AGS_SHARED_AC_SPRITE_FILE_H
#define AGS_SHARED_AC_SPRITE_FILE_H

#include "ags/shared/core/types.h"
#include "common/std/memory.h"
#include "common/std/vector.h"
#include "ags/shared/util/stream.h"
#include "ags/globals.h"

namespace AGS3 {
namespace AGS {
namespace Shared {

class Bitmap;

// TODO: research old version differences
enum SpriteFileVersion {
	kSprfVersion_Undefined = 0,
	kSprfVersion_Uncompressed = 4,
	kSprfVersion_Compressed = 5,
	kSprfVersion_Last32bit = 6,
	kSprfVersion_64bit = 10,
	kSprfVersion_HighSpriteLimit = 11,
	kSprfVersion_StorageFormats = 12,
	kSprfVersion_Current = kSprfVersion_StorageFormats
};

enum SpriteIndexFileVersion {
	kSpridxfVersion_Initial = 1,
	kSpridxfVersion_Last32bit = 2,
	kSpridxfVersion_64bit = 10,
	kSpridxfVersion_HighSpriteLimit = 11,
	kSpridxfVersion_Current = kSpridxfVersion_HighSpriteLimit
};

// Instructions to how the sprites are allowed to be stored
enum SpriteStorage {
	// When possible convert the sprite into another format for less disk space
	// e.g. save 16/32-bit images as 8-bit colormaps with palette
	kSprStore_OptimizeForSize = 0x01
};

// Format in which the sprite's pixel data is stored
enum SpriteFormat {
	kSprFmt_Undefined = 0, // undefined, or keep as-is
	// Encoded as a 8-bit colormap with palette of 24-bit RGB values
	kSprFmt_PaletteRgb888 = 32,
	// Encoded as a 8-bit colormap with palette of 32-bit ARGB values
	kSprFmt_PaletteArgb8888 = 33,
	// Encoded as a 8-bit colormap with palette of 16-bit RGB565 values
	kSprFmt_PaletteRgb565 = 34
};

enum SpriteCompression {
	kSprCompress_None = 0,
	kSprCompress_RLE,
	kSprCompress_LZW,
	kSprCompress_Deflate
};

typedef int32_t sprkey_t;

// SpriteFileIndex contains sprite file's table of contents
struct SpriteFileIndex {
	int SpriteFileIDCheck = 0; // tag matching sprite file and index file
	std::vector<int16_t> Widths;
	std::vector<int16_t> Heights;
	std::vector<soff_t>  Offsets;

	inline size_t GetCount() const {
		return Offsets.size();
	}
	inline sprkey_t GetLastSlot() const {
		return (sprkey_t)GetCount() - 1;
	}
};

// Invidual sprite data header (as read from the file)
struct SpriteDatHeader {
	int BPP = 0; // color depth (bytes per pixel); or input format
	SpriteFormat SFormat = kSprFmt_Undefined; // storage format
	uint32_t PalCount = 0; // palette length, if applicable to storage format
	SpriteCompression Compress = kSprCompress_None; // compression type
	int Width = 0; // sprite's width
	int Height = 0; // sprite's height

	SpriteDatHeader() = default;
	SpriteDatHeader(int bpp, SpriteFormat sformat = kSprFmt_Undefined,
		uint32_t pal_count = 0, SpriteCompression compress = kSprCompress_None,
		int w = 0, int h = 0) : BPP(bpp), SFormat(sformat), PalCount(pal_count),
		Compress(compress), Width(w), Height(h) {
	}
};

// SpriteFile opens a sprite file for reading, reports general information,
// and lets read sprites in any order.
class SpriteFile {
public:
	// Standart sprite file and sprite index names
	static const char *DefaultSpriteFileName;
	static const char *DefaultSpriteIndexName;

	SpriteFile();
	// Loads sprite reference information and inits sprite stream
	HError      OpenFile(const String &filename, const String &sprindex_filename,
		std::vector<Size> &metrics);
	// Closes stream; no reading will be possible unless opened again
	void        Close();

	int         GetStoreFlags() const;
	// Tells if bitmaps in the file are compressed
	SpriteCompression GetSpriteCompression() const;
	// Tells the highest known sprite index
	sprkey_t    GetTopmostSprite() const;

	// Loads sprite index file
	bool        LoadSpriteIndexFile(const String &filename, int expectedFileID,
		soff_t spr_initial_offs, sprkey_t topmost, std::vector<Size> &metrics);
	// Rebuilds sprite index from the main sprite file
	HError      RebuildSpriteIndex(Stream *in, sprkey_t topmost,
		std::vector<Size> &metrics);

	// Loads an image data and creates a ready bitmap
	HError      LoadSprite(sprkey_t index, Bitmap *&sprite);
	// Loads a raw sprite element data into the buffer, stores header info separately
	HError      LoadRawData(sprkey_t index, SpriteDatHeader &hdr, std::vector<uint8_t> &data);

private:
	// Seek stream to sprite
	void        SeekToSprite(sprkey_t index);

	// Internal sprite reference
	struct SpriteRef {
		soff_t Offset = 0; // data offset
		size_t RawSize = 0; // file size of element, in bytes
		// TODO: RawSize is currently unused, due to incompleteness of spriteindex format
	};

	// Array of sprite references
	std::vector<SpriteRef> _spriteData;
	std::unique_ptr<Stream> _stream; // the sprite stream
	SpriteFileVersion _version = kSprfVersion_Current;
	int _storeFlags = 0; // storage flags, specify how sprites may be stored
	SpriteCompression _compress = kSprCompress_None; // sprite compression typ
	sprkey_t _curPos; // current stream position (sprite slot)
};

// SpriteFileWriter class writes a sprite file in a requested format.
// Start using it by calling Begin, write ready bitmaps or copy raw sprite data
// over slot by slot, then call Finalize to let it close the format correctly.
class SpriteFileWriter {
public:
	SpriteFileWriter(std::unique_ptr<Stream> &out);
	~SpriteFileWriter() {
	}

	// Get the sprite index, accumulated after write
	const SpriteFileIndex &GetIndex() const {
		return _index;
	}

	// Initializes new sprite file format;
	// store_flags are SpriteStorage;
	// optionally hint how many sprites will be written.
	void Begin(int store_flags, SpriteCompression compress, sprkey_t last_slot = -1);
	// Writes a bitmap into file, compressing if necessary
	void WriteBitmap(Bitmap *image);
	// Writes an empty slot marker
	void WriteEmptySlot();
	// Writes a raw sprite data without any additional processing
	void WriteRawData(const SpriteDatHeader &hdr, const uint8_t *data, size_t data_sz);
	// Finalizes current format; no further writing is possible after this
	void Finalize();

private:
	// Writes prepared image data in a proper file format, following explicit data_bpp rule
	void WriteSpriteData(const SpriteDatHeader &hdr,
		const uint8_t *im_data, size_t im_data_sz, int im_bpp,
		const uint32_t palette[256]);

	std::unique_ptr<Stream> &_out;
	int _storeFlags = 0;
	SpriteCompression _compress = kSprCompress_None;
	soff_t _lastSlotPos = -1; // last slot save position in file
	// sprite index accumulated on write for reporting back to user
	SpriteFileIndex _index;
	// compression buffer
	std::vector<uint8_t> _membuf;
};

// Saves all sprites to file; fills in index data for external use.
// TODO: refactor to be able to save main file and index file separately (separate function for gather data?)
// Accepts available sprites as pairs of bool and Bitmap pointer, where boolean value
// tells if sprite exists and Bitmap pointer may be null;
// If a sprite's bitmap is missing, it will try reading one from the input file stream.
int SaveSpriteFile(const String &save_to_file,
	const std::vector<std::pair<bool, Bitmap *> > &sprites,
	SpriteFile *read_from_file, // optional file to read missing sprites from
	int store_flags, SpriteCompression compress, SpriteFileIndex &index);
// Saves sprite index table in a separate file
extern int SaveSpriteIndex(const String &filename, const SpriteFileIndex &index);

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

#endif