1. -- 
  2. -- Copyright (c) 2012 Kevin Wellwood 
  3. -- All rights reserved. 
  4. -- 
  5. -- This source code is distributed under the Modified BSD License. For terms and 
  6. -- conditions, see license.txt. 
  7. -- 
  8.  
  9. with Tiles.Matrices;                    use Tiles.Matrices; 
  10.  
  11. private with Tiles.Atlases; 
  12. private with Tiles.Catalogs; 
  13.  
  14. package Tiles.Libraries is 
  15.  
  16.     -- A Tile_Library is an organized container for images refered to as Tiles. 
  17.     -- Not all images in the library have the same dimensions or file format. 
  18.     -- A library is stored as a .zip archive containing a number of image files 
  19.     -- and a catalog file describing the order and attributes of the tiles. 
  20.     -- 
  21.     -- For performance reasons, tile libraries are reference counted and cached 
  22.     -- in memory. The library can be loaded in stages, first including just the 
  23.     -- tile attributes information, and then later the tile bitmaps as well. 
  24.     -- If the application uses a GUI, the tiles' bitmaps will automatically be 
  25.     -- cached to atlas bitmaps (sprite sheets) to improve drawing performance 
  26.     -- when drawing many bitmaps from the same library consecutively. 
  27.     type Tile_Library is new Limited_Object with private; 
  28.     type A_Tile_Library is access all Tile_Library'Class; 
  29.  
  30.     -- Finds the id of the first tile matching 'name' in the library. If 'name' 
  31.     -- does not include a file extension, a matching .png file will be searched 
  32.     -- first, then a matching .bmp file. Zero will be returned if no tile 
  33.     -- matching 'name' can be found. 
  34.     function Get_Id( this : not null access Tile_Library'Class; 
  35.                      name : String ) return Natural; 
  36.  
  37.     -- Returns the name of the tile library. 
  38.     function Get_Name( this : not null access Tile_Library'Class ) return String; 
  39.  
  40.     -- Returns a reference to a tile matrix by index. Do not modify the matrix, 
  41.     -- it belongs to the library! 
  42.     function Get_Matrix( this  : not null access Tile_Library'Class; 
  43.                          index :  Natural ) return A_Tile_Matrix; 
  44.  
  45.     -- Returns the number of matrices in the library. 
  46.     function Get_Matrix_Count( this : not null access Tile_Library'Class ) return Natural; 
  47.  
  48.     -- Returns a reference to a tile by id, or 'null' if 'id' doesn't exist. Do 
  49.     -- not modify the tile, it belongs to the library. 
  50.     function Get_Tile( this : not null access Tile_Library'Class; 
  51.                        id   : Natural ) return A_Tile; 
  52.  
  53.     -- Returns True if the tile library has been loaded completely. 
  54.     function Is_Loaded( this : not null access Tile_Library'Class ) return Boolean; 
  55.  
  56.     -- Iterates across all unique tiles in the tile library, in order of 
  57.     -- ascending ids. 
  58.     procedure Iterate_By_Id( this    : not null access Tile_Library'Class; 
  59.                              examine : not null access procedure( tile : not null A_Tile ) ); 
  60.  
  61.     -- Iterates across all slots in the tile library, beginning at 1. Not every 
  62.     -- slot in the library contains a tile, so the 'tile' argument of 'examine' 
  63.     -- may be null. 
  64.     procedure Iterate_By_Slot( this    : not null access Tile_Library'Class; 
  65.                                examine : not null access procedure( slot : Positive; 
  66.                                                                     tile : A_Tile ) ); 
  67.  
  68.     -- Loads the library's bitmaps from its archive file, if the library was 
  69.     -- loaded from an archive. This procedure will not return until all the 
  70.     -- bitmaps have been loaded. If the library's bitmaps have already been 
  71.     -- loaded, or the library was built in memory and not loaded from an 
  72.     -- archive, it will return immediately. If another  thread is loading the 
  73.     -- bitmaps, the caller will be blocked until loading is complete. 
  74.     procedure Load_Bitmaps( this : not null access Tile_Library'Class ); 
  75.  
  76. private 
  77.  
  78.     use Tiles.Atlases; 
  79.     use Tiles.Catalogs; 
  80.  
  81.     type Tile_Library is new Limited_Object with 
  82.         record 
  83.             name     : Unbounded_String;        -- name of the library 
  84.             file     : A_Archive := null;       -- archive the library was loaded from 
  85.             catalog  : A_Catalog := null;       -- catalog containing tile info 
  86.             atlas    : A_Atlas := null;         -- paged bitmap atlas (sprite sheet) 
  87.  
  88.             loadLock : Locking_Object;          -- protects the bitmap loading process 
  89.             loaded   : Boolean := False;        -- all bitmaps have been loaded 
  90.         end record; 
  91.  
  92.     -- 'name' is the base filename of the library, excluding the file extension. 
  93.     function Create_Library( name : String ) return A_Tile_Library; 
  94.  
  95.     -- Synchronously loads a library by name. 'name' should be the base name 
  96.     -- of the library, not including path information or a file extension. 
  97.     -- If 'bitmaps' is True, all of the library's bitmaps will be loaded. 
  98.     -- Otherwise, just the tile information will be loaded. Null will be 
  99.     -- returned on error. 
  100.     function Load_Library( name : String; bitmaps : Boolean ) return A_Tile_Library; 
  101.  
  102.     procedure Delete( this : in out Tile_Library ); 
  103.  
  104.     -- Adds a matrix to the library. This is used when building the library in 
  105.     -- memory. The matrix will be consumed. 
  106.     procedure Add_Matrix( this   : not null access Tile_Library'Class; 
  107.                           matrix : in out A_Tile_Matrix ); 
  108.  
  109.     -- Adds a tile to the library. This is used when building the library in 
  110.     -- memory. The tile will be consumed. 
  111.     -- 
  112.     -- Raises DUPLICATE_TILE if a tile with the same id already exists. 
  113.     -- Note: If an exception is raised, 'tile' will not be consumed. It is then 
  114.     -- the responsibility of the caller to delete the tile. 
  115.     procedure Add_Tile( this : not null access Tile_Library'Class; 
  116.                         tile : in out A_Tile ); 
  117.  
  118.     -- Deletes a tile library. This is private because libraries are intended to 
  119.     -- be loaded and unloaded via the public API, not deleted. 
  120.     procedure Delete( this : in out A_Tile_Library ); 
  121.  
  122.     ---------------------------------------------------------------------------- 
  123.  
  124.     CATALOG_FILENAME : constant String := "catalog.dat"; 
  125.     INFO_FILENAME    : constant String := "info.txt"; 
  126.  
  127.     -- Returns the file extension of tile library files, without a leading dot. 
  128.     function Library_Extension return String; 
  129.  
  130. end Tiles.Libraries;