001    /*
002     * BilevelImage
003     *
004     * Copyright (c) 2000, 2001, 2002, 2003 Marco Schmidt.
005     * All rights reserved.
006     */
007    
008    package net.sourceforge.jiu.data;
009    
010    import net.sourceforge.jiu.data.GrayIntegerImage;
011    
012    /**
013     * An interface for bilevel pixel image data classes.
014     * Each pixel in a bilevel image can have two possible values, {@link #BLACK} and {@link #WHITE}.
015     * Those two constants are guaranteed to be <code>0</code> and <code>1</code>, although
016     * you should not make any assumptions about what value any of the two constants has.
017     * This is the type of image used for faxes.
018     * Black and white photos are usually stored as grayscale images.
019     * <p>
020     * Apart from implementing {@link PixelImage} - like all image data classes in JIU - 
021     * this interface is also an {@link IntegerImage} (each sample is either 0 or 1) and
022     * a {@link GrayImage} (black and white are both grayscale values).
023     * The combination of {@link IntegerImage} and {@link GrayImage} is {@link GrayIntegerImage},
024     * which is the direct superinterface of this interface.
025     *
026     * <h3>Packed bytes</h3>
027     *
028     * There are methods to get and put <em>packed bytes</em> in this interface.
029     * A packed byte is a <code>byte</code> value that stores eight horizontally neighbored bilevel 
030     * pixels in it (pixel and sample can be used interchangeably in the context of bilevel images
031     * because there is only one sample per pixel).
032     * The most significant bit of such a packed bit is defined to be the leftmost of the
033     * eight pixels, the second-most significant bit is the pixel to the right of that leftmost pixel,
034     * and so on. The least significant bit is the rightmost pixel.
035     * If a bit is set, the corresponing pixel value is supposed to be white, otherwise black.
036     *
037     * <h3>Usage examples</h3>
038     * 
039     * Here are some code examples that demonstrate how to access image data with this class.
040     * <pre>
041     * BilevelImage image = new MemoryBilevelImage(2000, 500);
042     * // now set all pixels in the first row to white
043     * for (int x = 0; x < image.getWidth(); x++)
044     * {
045     *   image.putWhite(x, 0);
046     * }
047     * // put vertical stripes on the rest
048     * for (int y = 1; y < image.getHeight(); y++)
049     * {
050     *   for (int x = 0; x < image.getWidth(); x++)
051     *   {
052     *     int sample;
053     *     if ((x % 2) == 0)
054     *     {
055     *       sample = BilevelImage.BLACK;
056     *     }
057     *     else
058     *     {
059     *       sample = BilevelImage.WHITE;
060     *     }
061     *     image.putSample(x, y, sample);
062     *   }
063     * }
064     * </pre>
065     *
066     * @author Marco Schmidt
067     */
068    public interface BilevelImage extends GrayIntegerImage
069    {
070            /**
071             * The value for a black pixel.
072             * To be used with all methods that require <code>int</code> arguments for sample values.
073             * You can rely on this value being either 0 or 1 (that way you can safely store it
074             * in a byte or short).
075             */
076            int BLACK = 0;
077    
078            /**
079             * The value for a white pixel.
080             * To be used with all methods that require <code>int</code> arguments for sample values.
081             * You can rely on this value being either 0 or 1 (that way you can safely store it
082             * in a byte or short).
083             */
084            int WHITE = 1;
085    
086            /**
087             * Sets a number of samples in the argument array from this image.
088             * @param x horizontal position of first sample of this image to read
089             * @param y vertical position of samples to be read from this image
090             * @param numSamples number of samples to be set
091             * @param dest array with packed pixels to which samples are copied
092             * @param destOffset index into dest array of the first byte value to write sample values to
093             * @param destBitOffset index of first bit of <code>dest[destOffset]</code> to write a sample to (0 is leftmost, 1 is second-leftmost up to 7, which is the rightmost)
094             */
095            void getPackedBytes(int x, int y, int numSamples, byte[] dest, int destOffset, int destBitOffset);
096    
097            /**
098             * Sets a number of samples in the image from the argument array data.
099             * @param x horizontal position of first sample to be set
100             * @param y vertical position of samples to be set
101             * @param numSamples number of samples to be set
102             * @param src array with packed pixels to be set
103             * @param srcOffset index into src array of the first byte value to read sample values from
104             * @param srcBitOffset index of first bit of <code>src[srcOffset]</code> to 
105             *  read a sample from (0 is leftmost, 1 is second-leftmost up to 7, which is the rightmost)
106             */
107            void putPackedBytes(int x, int y, int numSamples, byte[] src, int srcOffset, int srcBitOffset);
108    }