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