001    /*
002     * PixelImage
003     *
004     * Copyright (c) 2000, 2001, 2002 Marco Schmidt.
005     * All rights reserved.
006     */
007    
008    package net.sourceforge.jiu.data;
009    
010    /**
011     * The base interface for all image data types in JIU.
012     * These image data classes and interfaces share the following properties:
013     * <ul>
014     * <li>They are made up of a rectangular grid of <em>pixels</em> (color dots) and 
015     *   have a fixed <em>width</em> (horizontal number of pixels) and <em>height</em>
016     *   (vertical number of pixels).</li>
017     * <li>Coordinates to access pixels in the image are defined to run from 0 to 
018     *   WIDTH - 1 in horizontal direction from left to right and in vertical 
019     *   direction from 0 to HEIGHT - 1 (from top to bottom).</li>
020     * <li>They have one or more channels. A pixel at a given position is made up
021     *   of the <em>samples</em> (primitive values) of all the channels at that 
022     *   position.
023     *   A pixel can thus be considered a vector (in the mathematical sense) of one or more samples.
024     *   Each channel has the same width and height.</li>
025     * </ul>
026     *
027     * @author Marco Schmidt
028     */
029    public interface PixelImage
030    {
031            /**
032             * Creates an instance of the same class as this one, with width and height
033             * given by the arguments.
034             * @param width the horizontal resolution of the new image
035             * @param height the vertical resolution of the new image
036             * @return the new image
037             * @throws IllegalArgumentException if width or height are smaller than one
038             */
039            PixelImage createCompatibleImage(int width, int height);
040    
041            /**
042             * Creates an new image object that will be of the same type as this one,
043             * with the same image data, using entirely new resources.
044             * @return the new image object
045             */
046            PixelImage createCopy();
047    
048            /**
049             * Returns the number of bytes that were dynamically allocated for 
050             * this image object.
051             * @return allocated memory in bytes
052             */
053            long getAllocatedMemory();
054    
055            /**
056             * Returns the number of bits per pixel of this image.
057             * That is the number of bits per sample for all channels of this image.
058             * Does not include any transparency channels.
059             */
060             int getBitsPerPixel();
061    
062            /**
063             * Returns the vertical resolution of the image in pixels.
064             * Must be one or larger.
065             * @return height in pixels
066             */
067            int getHeight();
068    
069            /**
070             * If there is a single interface or class that describes the image data type
071             * of this class, the {@link java.lang.Class} object associated with that
072             * interface (or class) is returned (or <code>null</code> otherwise).
073             * This {@link java.lang.Class} object, if available for two image objects,
074             * can be used to find out if they are compatible.
075             * Example: {@link net.sourceforge.jiu.data.MemoryGray8Image} returns 
076             * <code>net.sourceforge.jiu.data.Gray8Image.class</code>.
077             */
078            Class getImageType();
079    
080            /**
081             * Returns the number of channels in this image.
082             * Must be one or larger.
083             * @return the number of channels
084             */
085            int getNumChannels();
086    
087            /**
088             * Returns the horizontal resolution of the image in pixels.
089             * Must be one or larger.
090             * @return width in pixels
091             */
092            int getWidth();
093    }