with Tiles.Matrices; use Tiles.Matrices;
private with Tiles.Indices;
package Tiles.Libraries is
type Tile_Library is new Limited_Object with private;
type A_Tile_Library is access all Tile_Library'Class;
----------------------------------------------------------------------------
-- Initialize the tile library system. This must be called before loading a
-- library.
procedure Initialize;
-- Finalize the tile library system. No libraries can be loaded after this
-- has been called. However, references to loaded libraries will remain
-- valid and should still be unloaded after use.
procedure Finalize;
-- Loads a library by name. This should be the base filename of the library,
-- not including a file extension or any path information. Null will be
-- returned if an error occurs.
function Load_Library( name : String ) return A_Tile_Library;
-- Synchronously loads a library by name. This procedure will not return
-- until the requested library has been fully loaded, or an error occurs.
-- Null will be returned if an error occurs.
function Load_Library_Sync( name : String ) return A_Tile_Library;
-- Unloads a library by name. It will not be deallocated before all
-- references have been unloaded.
procedure Unload_Library( name : String );
-- Unloads a library by reference. It will not be deallocated before all
-- references have been unloaded.
procedure Unload_Library( lib : in out A_Tile_Library );
----------------------------------------------------------------------------
-- Returns True if a tile with the given id exists in the library.
function Exists( this : not null access Tile_Library'Class;
id : Natural ) return Boolean;
-- Returns the bitmap for a tile with the given id, or null if the tile is
-- not found, is not yet loaded, or failed to load its bitmap.
function Get_Bitmap( this : not null access Tile_Library'Class;
id : Natural ) return A_Bitmap;
-- Returns the bitmap for a tile with the given id, blocking if the tile
-- hasn't been loaded into memory yet. null will be returned if the tile
-- bitmap failed to load.
function Get_Bitmap_Sync( this : not null access Tile_Library'Class;
id : Natural ) return A_Bitmap;
-- Returns the bitmap for a tile in the given tile slot, or null if the slot
-- is empty or not yet loaded.
function Get_Bitmap_At_Slot( this : not null access Tile_Library'Class;
slot : Natural ) return A_Bitmap;
-- Returns the clip attribute of a tile.
function Get_Clip( this : not null access Tile_Library'Class;
id : Natural ) return Clip_Type;
-- Returns the id of a tile by tile name.
function Get_Id( this : not null access Tile_Library'Class;
name : String ) return Natural;
-- Returns the id of the tile at the given slot.
function Get_Id_At_Slot( this : not null access Tile_Library'Class;
slot : Natural ) 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. Do not modify the matrix, it
-- belongs to the library!
function Get_Matrix( this : not null access Tile_Library'Class;
num : 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 the loading progress as a percentage. Values will be in the
-- range of 0..100.
function Get_Progress( this : not null access Tile_Library'Class ) return Natural;
pragma Postcondition( Get_Progress'Result <= 100 );
-- Returns the slot number in the tile listing for the given tile id.
function Get_Slot_For_ID( this : not null access Tile_Library'Class;
id : Natural ) return Natural;
-- Returns the number of slots in the library (not necessarily the number
-- of tiles in the library, since empty slots are also counted).
function Get_Tile_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;
private
use Tiles.Indices;
----------------------------------------------------------------------------
type Tile_Library is new Limited_Object with
record
name : Unbounded_String; -- name of the library
dir : Unbounded_String; -- path of the library
index : A_Tile_Index := null; -- tile index of the library
loadState : A_Async_Operation := null; -- loaded state of the library
end record;
-- Creates an empty tile library.
function Create_Tile_Library return A_Tile_Library;
-- 'name' is the base filename of the library, excluding the file extension.
-- 'dir' is the directory where the library will be written.
function Create_Library( name : String; dir : String ) return A_Tile_Library;
procedure Construct( this : access Tile_Library );
procedure Delete( this : in out Tile_Library );
-- Adds a matrix to the library. This is used when reading a tile index or
-- building a 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 reading a tile index or
-- building a library in memory.
--
-- Raises DUPLICATE_TILE if a tile with the same id already exists.
-- Note: If an exception is raised, the tile argument is not 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 );
-- Blocks the caller until the library has been completely loaded by the
-- background loading thread.
procedure Wait_For_Load( this : not null access Tile_Library'Class );
-- Deletes a tile library. This is package private because libraries are
-- intended to be loaded and unloaded; never deleted via the public API.
procedure Delete( this : in out A_Tile_Library );
----------------------------------------------------------------------------
function Library_Extension return String;
end Tiles.Libraries;