source: trunk/src/org/expeditee/gio/ImageManager.java@ 1097

package org.expeditee.gio;

import java.io.File;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;

import org.expeditee.core.Colour;
import org.expeditee.core.Dimension;
import org.expeditee.core.Image;

import com.sun.pdfview.PDFPage;

/**
 * Manager in charge of creating and working with images in memory. Maintains a mapping
 * from org.expeditee.core.Image handles to the underlying images, and provides methods
 * for manipulating the underlying images through those handles.
 * 
 * @author cts16
 */
public abstract class ImageManager {
        
        /*
         * 
         *  Image-creation functions
         *  
         */
        
        /**
         * Creates an image of the given size in either main or video RAM.
         * 
         * @param hintUseAcceleratedMemory
         *                      True to use video RAM, false for main memory.
         */
        public Image createImage(Dimension size, boolean hintUseAcceleratedMemory)
        {
                if (size == null) return null;
                
                return createImage(size.width, size.height, hintUseAcceleratedMemory);
        }
        
        /**
         * Creates an image of the given width and height in either main or video RAM.
         * 
         * @param hintUseAcceleratedMemory
         *                      True to use video RAM, false for main memory.
         */
        public abstract Image createImage(int width, int height, boolean hintUseAcceleratedMemory);

        /** Creates an image in main memory with the given size. */
        public Image createImage(Dimension size)
        {
                return createImage(size, false);
        }

        /** Creates an image in main memory with the given width and height. */
        public Image createImage(int width, int height)
        {
                return createImage(width, height, false);
        }
        
        /** Creates an image from packed 32-bit ARGB data in an array. */
        public abstract Image createImage(int width, int height, int[] pixelData);
        
        /** Creates an image of a PDF page. */
        public abstract Image createImage(int width, int height, PDFPage page);
        
        /** Creates a new image which is a cropped section of another image. */
        public abstract Image createImageAsCroppedCopy(Image orig, int x, int y, int width, int height);
        
        /** Gets image data from a URL. */
        public abstract Image getImage(URL url);
        
        /** Gets image data from a file. */
        public abstract Image getImage(String filename);
        
        /** Gets image data from a HTTP connection. */
        public abstract Image getImage(HttpURLConnection connection) throws IOException;
        
        /*
         * 
         *  Image-destruction functions
         *  
         */
        
        /** Tells the image manager that the given image is no longer needed. */
        public abstract void releaseImage(Image image);
        
        /*
         * 
         *  Image info getters
         *  
         */
        
        /** Checks if the given handle corresponds to a real image in the image manager. */
        public abstract boolean isImageValid(Image image);
        
        /** Gets the width of the given image. */
        public abstract int getWidth(Image image);
        
        /** Gets the height of the given image. */
        public abstract int getHeight(Image image);
        
        /** Gets the colours of an area of pixels from the image. */
        public abstract Colour[] getPixels(Image image, int x, int y, int width, int height);
        
        /** Gets the colour of a single pixel in the image. */
        public Colour getPixel(Image image, int x, int y)
        {
                Colour[] pixels = getPixels(image, x, y, 1, 1);
                
                if (pixels == null) return null;
                
                return pixels[0];
        }
        
        /*
         * 
         *  Image-manipulation functions
         *  
         */
        
        /** Sets the colour of a single pixel in the image. */
        public abstract void setPixel(Image image, int x, int y, Colour c);
        
        /** Writes the image data to disk. Format should be png, bmp, etc. */
        public abstract boolean writeImageToDisk(Image image, String format, File file) throws IOException;
        
}