1. with Tiles.Matrices;                    use Tiles.Matrices; 
  2.  
  3. private with Tiles.Indices; 
  4.  
  5. package Tiles.Libraries is 
  6.  
  7.     -- A Tile_Library is an organized container for images refered to as Tiles. 
  8.     -- Not all images in the library have the same dimensions or file format. 
  9.     -- A library is stored as a .zip archive containing a number of image files 
  10.     -- and one index file describing the order and attributes of the tiles. 
  11.     -- 
  12.     -- For performance reasons, tile libraries are reference counted and cached 
  13.     -- in memory. The library can be loaded synchronously, waiting until all 
  14.     -- tile resources have been loaded from disk, or asynchronously, allowing 
  15.     -- execution to proceed while images are loaded in the background and 
  16.     -- prioritized according to use. 
  17.     type Tile_Library is new Limited_Object with private; 
  18.     type A_Tile_Library is access all Tile_Library'Class; 
  19.  
  20.     -- Returns True if a tile with the given id exists in the library. 
  21.     function Exists( this : not null access Tile_Library'Class; 
  22.                      id   : Natural ) return Boolean; 
  23.  
  24.     -- Returns the bitmap for a tile with the given id, or null if the tile is 
  25.     -- not found, is not yet loaded, or failed to load its bitmap. 
  26.     function Get_Bitmap( this : not null access Tile_Library'Class; 
  27.                          id   : Natural ) return A_Bitmap; 
  28.  
  29.     -- Returns the bitmap for a tile with the given id, blocking if the tile 
  30.     -- hasn't been loaded into memory yet. null will be returned if the tile 
  31.     -- bitmap failed to load. 
  32.     function Get_Bitmap_Sync( this : not null access Tile_Library'Class; 
  33.                               id   : Natural ) return A_Bitmap; 
  34.  
  35.     -- Returns the bitmap for a tile in the given tile slot, or null if the slot 
  36.     -- is empty or not yet loaded. 
  37.     function Get_Bitmap_At_Slot( this : not null access Tile_Library'Class; 
  38.                                  slot : Natural ) return A_Bitmap; 
  39.  
  40.     -- Returns the clip attribute of a tile. 
  41.     function Get_Clip( this : not null access Tile_Library'Class; 
  42.                        id   : Natural ) return Clip_Type; 
  43.  
  44.     -- Returns the id of a tile by tile name. 
  45.     function Get_Id( this : not null access Tile_Library'Class; 
  46.                      name : String ) return Natural; 
  47.  
  48.     -- Returns the id of the tile at the given slot. 
  49.     function Get_Id_At_Slot( this : not null access Tile_Library'Class; 
  50.                              slot : Natural ) return Natural; 
  51.  
  52.     -- Returns the name of the tile library. 
  53.     function Get_Name( this : not null access Tile_Library'Class ) return String; 
  54.  
  55.     -- Returns a reference to a tile matrix. Do not modify the matrix, it 
  56.     -- belongs to the library! 
  57.     function Get_Matrix( this : not null access Tile_Library'Class; 
  58.                          num  :  Natural ) return A_Tile_Matrix; 
  59.  
  60.     -- Returns the number of matrices in the library. 
  61.     function Get_Matrix_Count( this : not null access Tile_Library'Class ) return Natural; 
  62.  
  63.     -- Returns the loading progress as a percentage. Values will be in the 
  64.     -- range of 0..100. 
  65.     function Get_Progress( this : not null access Tile_Library'Class ) return Natural; 
  66.     pragma Postcondition( Get_Progress'Result <= 100 ); 
  67.  
  68.     -- Returns the slot number in the tile listing for the given tile id. 
  69.     function Get_Slot_For_ID( this : not null access Tile_Library'Class; 
  70.                               id   : Natural ) return Natural; 
  71.  
  72.     -- Returns the number of slots in the library (not necessarily the number 
  73.     -- of tiles in the library, since empty slots are also counted). 
  74.     function Get_Tile_Count( this : not null access Tile_Library'Class ) return Natural; 
  75.  
  76.     -- Returns a reference to a tile by id, or 'null' if 'id' doesn't exist. Do 
  77.     -- not modify the tile, it belongs to the library. 
  78.     function Get_Tile( this : not null access Tile_Library'Class; 
  79.                        id   : Natural ) return A_Tile; 
  80.  
  81.     -- Returns True if the tile library has been loaded completely. 
  82.     function Is_Loaded( this : not null access Tile_Library'Class ) return Boolean; 
  83.  
  84.     ---------------------------------------------------------------------------- 
  85.  
  86.     -- Initialize the tile library system. This must be called before loading a 
  87.     -- library. 
  88.     procedure Initialize; 
  89.  
  90.     -- Finalize the tile library system. No libraries can be loaded after this 
  91.     -- has been called. However, references to loaded libraries will remain 
  92.     -- valid and should still be unloaded after use. 
  93.     procedure Finalize; 
  94.  
  95.     -- Asynchronously loads a library by name. This should be the base filename 
  96.     -- of the library, not including a path information or a file extension. 
  97.     -- Null will be returned on error. 
  98.     function Load_Library( name : String ) return A_Tile_Library; 
  99.  
  100.     -- Synchronously loads a library by name. This procedure will not return 
  101.     -- until the requested library has been fully loaded, or an error occurs. 
  102.     -- Null will be returned on error. 
  103.     function Load_Library_Sync( name : String ) return A_Tile_Library; 
  104.  
  105.     -- Unloads a library by name. It will not be removed from memory before all 
  106.     -- other references have been unloaded. 
  107.     procedure Unload_Library( name : String ); 
  108.  
  109.     -- Unloads a library by reference. It will not be removed from memory until 
  110.     -- all other references have been unloaded. 
  111.     procedure Unload_Library( lib : in out A_Tile_Library ); 
  112.  
  113. private 
  114.  
  115.     use Tiles.Indices; 
  116.  
  117.     ---------------------------------------------------------------------------- 
  118.  
  119.     type Tile_Library is new Limited_Object with 
  120.         record 
  121.             name      : Unbounded_String;           -- name of the library 
  122.             dir       : Unbounded_String;           -- path of the library 
  123.             index     : A_Tile_Index := null;       -- tile index of the library 
  124.             loadState : A_Async_Operation := null;  -- loaded state of the library 
  125.         end record; 
  126.  
  127.     -- Creates an empty tile library. 
  128.     function Create_Tile_Library return A_Tile_Library; 
  129.  
  130.     -- 'name' is the base filename of the library, excluding the file extension. 
  131.     -- 'dir' is the directory where the library will be written. 
  132.     function Create_Library( name : String; dir : String ) return A_Tile_Library; 
  133.  
  134.     procedure Construct( this : access Tile_Library ); 
  135.  
  136.     procedure Delete( this : in out Tile_Library ); 
  137.  
  138.     -- Adds a matrix to the library. This is used when reading a tile index or 
  139.     -- building a library in memory. The matrix will be consumed. 
  140.     procedure Add_Matrix( this   : not null access Tile_Library'Class; 
  141.                           matrix : in out A_Tile_Matrix ); 
  142.  
  143.     -- Adds a tile to the library. This is used when reading a tile index or 
  144.     -- building a library in memory. 
  145.     -- 
  146.     -- Raises DUPLICATE_TILE if a tile with the same id already exists. 
  147.     -- Note: If an exception is raised, the tile argument is not consumed. It is 
  148.     -- then the responsibility of the caller to delete the tile. 
  149.     procedure Add_Tile( this : not null access Tile_Library'Class; 
  150.                         tile : in out A_Tile ); 
  151.  
  152.     -- Blocks the caller until the library has been completely loaded by the 
  153.     -- background loading thread. 
  154.     procedure Wait_For_Load( this : not null access Tile_Library'Class ); 
  155.  
  156.     -- Deletes a tile library. This is package private because libraries are 
  157.     -- intended to be loaded and unloaded; never deleted via the public API. 
  158.     procedure Delete( this : in out A_Tile_Library ); 
  159.  
  160.     ---------------------------------------------------------------------------- 
  161.  
  162.     -- Returns the file extension of tile library files, without a leading dot. 
  163.     function Library_Extension return String; 
  164.  
  165. end Tiles.Libraries;