imagelibrary.java

Vyger offers a D & D and Rogue-like environment in a graphical online roleplay game.

/*
 * Light And Shadow. A Persistent Universe based on Robert Jordan's Wheel of Time Books.
 * Copyright (C) 2001-2002 WOTLAS Team
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */

package wotlas.libs.graphics2D;

import java.awt.*;
import java.awt.image.*;
import java.io.*;

/** An ImageLibrary manages shared images ( i.e. used by more than
 *  one object ).
 *
 *  <p>It relies on a image database that is loaded into memory at creation time.
 *  The database must have the following structure:</p>
 *   <pre>
 *     - it is a tree composed of directories and images. Each directory can contain
 *       sub-directories or/and images.
 *
 *     - the directories must have the following format : <DIR_NAME>-<XXX>[-option]
 *       XXX represents the directory ID (must start at 0 and increase one by one).
 *       Available options are :
 *
 *          o -jit : "just in time". All the images that are in the directory AND its
 *            sub-directories are NOT loaded into memory until they are needed. This
 *            option is always automatically propagated to sub-directories.
 *
 *          o -exc : "exclusion". Only one of the sub-directories can be loaded into
 *            memory at the same time. When you load one of them the others are
 *            automatically unloaded (flushed). It is logical that the images of a
 *            "-exc" directory are not loaded at start-up. You need to load them manually.
 *            
 *            This option is especially useful when handling huge images that don't need
 *            to be in memory at the same time.
 *
 *       Example :  animals-0
 *                      |
 *                      --- cats-0-jit    // lots of small cat images, loaded just in time
 *                      |
 *                      --- dogs-1-exc    // huge dog images
 *                           |
 *                           --- poddle-0
 *                           |
 *                           --- ousti-1
 *                           |
 *                           --- cork-2
 *
 *     - images must have the following format : <IMAGE_NAME>-<XXX>.<jpg|gif|*>
 *       XXX represents the image ID (must start at 0 and increase one by one).
 *
 *       Example : cats-0-jit
 *                    |
 *                    --- cat-0.jpg
 *                    |
 *                    --- strange_cat-1.jpg
 *                    |
 *                    --- an_other_cat-2.png
 *                    |
 *                    --- big_cats-0  // sub-directory, note that the IDs between images
 *                                    // and directories are separated.
 *
 *     - for animations all the images must be in the same directory. There musn't
 *       be other images in the directory. You can create an Animation object to manage
 *       your animation.
 *   </pre>
 *
 *   <p>As you see directories and images have IDs. These IDs help for array creation and 
 *      direct access to images. Images in the ImageLibrary are INT_ARGB buffered images.
 *   </p>
 *   <p>With the example above an ImageIdentifier representing the cat-0.jpg could be created
 *      either by calling :</p>
 *      <pre>
 *        String path[] = { "animals-0", "cats-0" };
 *        ImageIdentifier imCat = new ImageIdentifier( path );
 *
 *        or
 *
 *        String path[] = { "animals-0", "cats-0", "cat-0.jpg" };
 *        ImageIdentifier imCat = new ImageIdentifier( path );
 *
 *        or
 *
 *        ImageIdentifier imCat = new ImageIdentifier( "animals-0/cats-0/cat-0.jpg" );
 *       </pre>
 *
 *   <p> Note that in both case the internal representation of the ImageIdentifier will be
 *       { [0, 0], 0 }. Note also that it is optional to give the directory options such as '-jit'
 *       or '-exc'. You can either enter 'cats-0' or 'cats-0-jit'. If you specify a precise image
 *       name, the extension is mandatory : we entered 'cat-0.jpg' not 'cat-0'.
 *   </p>
 *
 *   <p> Developer Tips: This image library can be used as a singleton if your application
 *       has a need for it. Otherwise we recommend that you extend this class and add a
 *       public constructor. You could then have, for example, an application that has more
 *       than one ImageLibrary. For security just set the 'defaultImageLibrary' to null in the
 *       sub-class constructor.
 *   </p>
 *
 * @author MasterBob, Aldiss, Diego
 * @see wotlas.libs.graphics2D.ImageIdentifier
 */

public class ImageLibrary {

 /*------------------------------------------------------------------------------------*/

  /** Debug Mode. If set to true, recompile the class and it will display extra
   *  warning/error messages.
   */
     protected static final boolean DEBUG_MODE = true;

  /** Do we have to warn about db entries that have bad format ? or just ignore them ?
   */
     protected static boolean ignoreBadFormatEntries = true;

   /** Our Default ImageLibrary. (avoid its use, prefer a simple "new ImageLibrary" )
    */
     protected static ImageLibrary defaultImageLibrary;

 /*------------------------------------------------------------------------------------*/

  /** Root Directory of the Image Library. ImageLibDir is an internal class.
   */
     protected ImageLibDir rootDir;

  /** Resource locator for easier use of this library when resources are in
   *  JAR files or need special access (security/network).
   */
     protected ImageResourceLocator resourceLocator;

  /** JIT Behaviour : If true we load all the images from the JIT directory when asked to load
   *  one image from that directory. If false we only load the images one by one when they are needed.
   *  Default Value is false.
   */
     protected boolean loadAllJITDirectoryImages = false;

 /*------------------------------------------------------------------------------------*/
  
  /** Do we have to display db entries with bad format ?
   * 
   * @param ignore if false we warn about disk entries of the ImageLibrary that
   *        have a bad format (exceptions are thrown).
   */
    public static void ignoreBadFormatEntries( boolean ignore ) {
          ignoreBadFormatEntries = ignore;
    }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Constructor with the image database path.
   *  Use this constructor if your image library is on your local file system.
   *
   * @param imageDataBasePath the path to the image database.
   * @exception ImageLibraryException if an error occurs while loading the images.
   */
    public ImageLibrary( String imageDataBasePath )
    throws ImageLibraryException {

       // 1 - Check DataBase
          File homeDir = new File(imageDataBasePath);
  
          if( !homeDir.isDirectory() || !homeDir.exists() )
             throw new ImageLibraryException("Image DataBase Not found : "+imageDataBasePath
                                    +" is not a valid directory.");

       // We create the database structure (recursive creation)
          this.resourceLocator = new SimpleImageResourceLocator(imageDataBasePath);
          rootDir = new ImageLibDir( imageDataBasePath, null );

       // We load the images of the database structure
          int loadedImages = rootDir.initImageLoad();

          if(DEBUG_MODE)
             System.out.println("Notice: ImageLibrary created with "+loadedImages+" images.");
    }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Constructor with the image resource locator.
   *  Use this constructor if the images are in a zip/jar file or need special
   *  access (security/network). You just need to develop the methods of the
   *  ImageResourceLocator interface.
   *
   * @param resourceLocator an interface that provides access to resources.
   * @exception ImageLibraryException if an error occurs while loading the images.
   */
    public ImageLibrary( ImageResourceLocator resourceLocator )
    throws ImageLibraryException {

       // We create the database structure (recursive creation)
          this.resourceLocator = resourceLocator;
          rootDir = new ImageLibDir( resourceLocator.getImageLibraryDir(), null );

       // We load the images of the database structure
          int loadedImages = rootDir.initImageLoad();

          if(DEBUG_MODE)
             System.out.println("Notice: ImageLibrary created with "+loadedImages+" images.");
    }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To get the default image databasepath.
   *
   * @return the default image databasepath.
   */
    public String getImageDataBasePath() {
          return resourceLocator.getImageLibraryDir();
    }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** Creates an ImageLibrary or returned the previously created one.
   *
   *  <p>To manually load directories/images which parent directories have the format
   *  "-XX-jit" or "-XX-exc" you can use the loadImage() method.<br>
   *
   *  <p>You can manually unload images from "-jit" or "-exc" "set" directories by calling
   *  the unloadImage() method.
   *
   *  IMPORTANT: for directory names that end with "-XX" or "-XX-<option>" the XX index must start
   *  at zero and increment with no jumps between numbers.
   *
   * @param imageDataBasePath the path to the image database.
   * @return the created (or previously created) image library.
   * @exception ImageLibraryException if an error occurs while loading the images.
   */
   public static ImageLibrary createImageLibrary( String imageDataBasePath )
   throws ImageLibraryException {

         if( defaultImageLibrary==null ) {
             defaultImageLibrary = new ImageLibrary( imageDataBasePath );
         }
         return defaultImageLibrary;
   }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To get the default image library.
   *
   * @return the default image library.
   */
   public static ImageLibrary getDefaultImageLibrary() {
         return defaultImageLibrary;
   }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To set the JIT Behaviour : If true we load all the images from the JIT directory when asked to
   *  load one image from that directory. If false we only load the images one by one when they are needed.
   *  Default Value is false.
   */
     public void setLoadAllJITDirectoryImages( boolean loadAllJITDirectoryImages ) {
        this.loadAllJITDirectoryImages = loadAllJITDirectoryImages;
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To get the JIT Behaviour : If true we load all the images from the JIT directory when asked to
   *  load one image from that directory. If false we only load the images one by one when they are needed.
   *  Default Value is false.
   */
     public boolean getLoadAllJITDirectoryImages() {
        return loadAllJITDirectoryImages;
     }

 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*/

  /** To get an image from the database. If we have to load the given image we check that
   *  it is in a "JIT" or "EXC" directory. If it's the case we load/unload images as expected
   *  by the option and return the image wanted. We return null if an error occurs.
   *
   * @param imId complete image identifier
   * @return image found in the library.
   * @exception ImageLibraryException if the imId is invalid.
   */
   public BufferedImage getImage( ImageIdentifier imId )
   throws ImageLibraryException{

      ImageLibDir dir = rootDir;

       try{
        // we select the directory where the image is        
           for( int index=0; index<imId.dirIds.length; index++ )
                dir = dir.childDirs[imId.dirIds[index]];

        // is the image available ?
           BufferedImage bufIm = dir.images[imId.imageId];

           if(bufIm!=null)
              return bufIm; // success !

        // We try to load the image.
           return loadImage( imId );
        }
        catch( Exception e ) {
       	   throw new ImageLibraryException(""+e+" in "+imId);
        }
   }