--
-- Copyright (c) 2012 Kevin Wellwood
-- All rights reserved.
--
-- This source code is distributed under the Modified BSD License. For terms and
-- conditions, see license.txt.
--
with Tiles.Matrices; use Tiles.Matrices;
private with Tiles.Atlases;
private with Tiles.Catalogs;
package Tiles.Libraries is
-- A Tile_Library is an organized container for images refered to as Tiles.
-- Not all images in the library have the same dimensions or file format.
-- A library is stored as a .zip archive containing a number of image files
-- and a catalog file describing the order and attributes of the tiles.
--
-- For performance reasons, tile libraries are reference counted and cached
-- in memory. The library can be loaded in stages, first including just the
-- tile attributes information, and then later the tile bitmaps as well.
-- If the application uses a GUI, the tiles' bitmaps will automatically be
-- cached to atlas bitmaps (sprite sheets) to improve drawing performance
-- when drawing many bitmaps from the same library consecutively.
type Tile_Library is new Limited_Object with private;
type A_Tile_Library is access all Tile_Library'Class;
-- Finds the id of the first tile matching 'name' in the library. If 'name'
-- does not include a file extension, a matching .png file will be searched
-- first, then a matching .bmp file. Zero will be returned if no tile
-- matching 'name' can be found.
function Get_Id( this : not null access Tile_Library'Class;
name : String ) return Natural;
-- Returns the name of the tile library.
function Get_Name( this : not null access Tile_Library'Class ) return String;
-- Returns a reference to a tile matrix by index. Do not modify the matrix,
-- it belongs to the library!
function Get_Matrix( this : not null access Tile_Library'Class;
index : Natural ) return A_Tile_Matrix;
-- Returns the number of matrices in the library.
function Get_Matrix_Count( this : not null access Tile_Library'Class ) return Natural;
-- Returns a reference to a tile by id, or 'null' if 'id' doesn't exist. Do
-- not modify the tile, it belongs to the library.
function Get_Tile( this : not null access Tile_Library'Class;
id : Natural ) return A_Tile;
-- Returns True if the tile library has been loaded completely.
function Is_Loaded( this : not null access Tile_Library'Class ) return Boolean;
-- Iterates across all unique tiles in the tile library, in order of
-- ascending ids.
procedure Iterate_By_Id( this : not null access Tile_Library'Class;
examine : not null access procedure( tile : not null A_Tile ) );
-- Iterates across all slots in the tile library, beginning at 1. Not every
-- slot in the library contains a tile, so the 'tile' argument of 'examine'
-- may be null.
procedure Iterate_By_Slot( this : not null access Tile_Library'Class;
examine : not null access procedure( slot : Positive;
tile : A_Tile ) );
-- Loads the library's bitmaps from its archive file, if the library was
-- loaded from an archive. This procedure will not return until all the
-- bitmaps have been loaded. If the library's bitmaps have already been
-- loaded, or the library was built in memory and not loaded from an
-- archive, it will return immediately. If another thread is loading the
-- bitmaps, the caller will be blocked until loading is complete.
procedure Load_Bitmaps( this : not null access Tile_Library'Class );
private
use Tiles.Atlases;
use Tiles.Catalogs;
type Tile_Library is new Limited_Object with
record
name : Unbounded_String; -- name of the library
file : A_Archive := null; -- archive the library was loaded from
catalog : A_Catalog := null; -- catalog containing tile info
atlas : A_Atlas := null; -- paged bitmap atlas (sprite sheet)
loadLock : Locking_Object; -- protects the bitmap loading process
loaded : Boolean := False; -- all bitmaps have been loaded
end record;
-- 'name' is the base filename of the library, excluding the file extension.
function Create_Library( name : String ) return A_Tile_Library;
-- Synchronously loads a library by name. 'name' should be the base name
-- of the library, not including path information or a file extension.
-- If 'bitmaps' is True, all of the library's bitmaps will be loaded.
-- Otherwise, just the tile information will be loaded. Null will be
-- returned on error.
function Load_Library( name : String; bitmaps : Boolean ) return A_Tile_Library;
procedure Delete( this : in out Tile_Library );
-- Adds a matrix to the library. This is used when building the library in
-- memory. The matrix will be consumed.
procedure Add_Matrix( this : not null access Tile_Library'Class;
matrix : in out A_Tile_Matrix );
-- Adds a tile to the library. This is used when building the library in
-- memory. The tile will be consumed.
--
-- Raises DUPLICATE_TILE if a tile with the same id already exists.
-- Note: If an exception is raised, 'tile' will not be consumed. It is then
-- the responsibility of the caller to delete the tile.
procedure Add_Tile( this : not null access Tile_Library'Class;
tile : in out A_Tile );
-- Deletes a tile library. This is private because libraries are intended to
-- be loaded and unloaded via the public API, not deleted.
procedure Delete( this : in out A_Tile_Library );
----------------------------------------------------------------------------
CATALOG_FILENAME : constant String := "catalog.dat";
INFO_FILENAME : constant String := "info.txt";
-- Returns the file extension of tile library files, without a leading dot.
function Library_Extension return String;
end Tiles.Libraries;