001    /*
002     * IntegerImage
003     *
004     * Copyright (c) 2000, 2001, 2002 Marco Schmidt <marcoschmidt@users.sourceforge.net>
005     * All rights reserved.
006     */
007    
008    package net.sourceforge.jiu.data;
009    
010    /**
011     * Extends the {@link PixelImage} interface to access image data as <code>int</code> values.
012     * Image types based on <code>byte</code>, <code>char</code>, <code>short</code> and <code>int</code> will work with this interface.
013     * <code>long</code> will not.
014     * <p>
015     * Using this interface provides a nice way of accessing a large variety of 
016     * image types, but for performance reasons it might be preferable to use 
017     * one of the class-specific access methods that get or put several values 
018     * at a time, e.g. getByteSamples in {@link ByteChannelImage}.
019     *
020     * @author Marco Schmidt
021     */
022    public interface IntegerImage extends PixelImage
023    {
024            /**
025             * Sets all samples in the first channel to the argument value.
026             * Equal to <code>clear(0, newValue);</code>:
027             */
028            void clear(int newValue);
029    
030            /**
031             * Sets all samples of the <code>channelIndex</code>'th channel to <code>newValue</code>.
032             */
033            void clear(int channelIndex, int newValue);
034    
035            /**
036             * Returns the maximum value for one of the image's channels.
037             * The minimum value is always <code>0</code>.
038             * @param channel zero-based index of the channel, from <code>0</code> to {@link #getNumChannels()}<code> - 1</code>
039             * @return maximum allowed sample value
040             */
041            int getMaxSample(int channel);
042    
043            /**
044             * Returns one sample of the first channel (index 0).
045             * A call to this method must have the same result as the call <code>getSample(0, x, y);</code>.
046             * @param x the horizontal position of the sample, from <code>0</code> to {@link #getWidth} <code>- 1</code>
047             * @param y the vertical position of the sample, from <code>0</code> to {@link #getHeight} <code>- 1</code>
048             * @return the desired sample
049             */
050            int getSample(int x, int y);
051    
052            /**
053             * Returns one sample, specified by its channel index and location.
054             * @param channel the number of the channel, from <code>0</code> to {@link #getNumChannels} <code>- 1</code>
055             * @param x the horizontal position of the sample, from <code>0</code> to {@link #getWidth} <code>- 1</code>
056             * @param y the vertical position of the sample, from <code>0</code> to {@link #getHeight} <code>- 1</code>
057             * @return the desired sample
058             */
059            int getSample(int channel, int x, int y);
060    
061            /**
062             * Copies a number of samples from this image to an <code>int[]</code> object.
063             * A rectangular part of one channel is copied.
064             * The channel index is given by  - the upper left corner of
065             * that rectangle is given by the point x / y.
066             * Width and height of that rectangle are given by w and h.
067             * Each sample will be stored as one <code>int</code> value dest,
068             * starting at index destOffs.
069             * @param channelIndex zero-based index of the channel from which data is to be copied (valid values: 0 to {@link #getNumChannels()} - 1)
070             * @param x horizontal position of upper left corner of the rectangle to be copied
071             * @param y vertical position of upper left corner of the rectangle to be copied
072             * @param w width of rectangle to be copied
073             * @param h height of rectangle to be copied
074             * @param dest int array to which the samples will be copied
075             * @param destOffs int index into the dest array for the position to which the samples will be copied
076             */
077            void getSamples(int channelIndex, int x, int y, int w, int h, int[] dest, int destOffs);
078    
079            /**
080             * This method sets one sample of the first channel (index 0) to a new value.
081             * This call must have the same result as the call <code>putSample(0, x, y)</code>.
082             * The sample location is given by the spatial coordinates, x and y.
083             * @param x the horizontal position of the sample, from <code>0</code> to {@link #getWidth} <code>- 1</code>
084             * @param y the vertical position of the sample, from <code>0</code> to {@link #getHeight} <code>- 1</code>
085             * @param newValue the new value of the sample
086             */
087            void putSample(int x, int y, int newValue);
088    
089            /**
090             * This method sets one sample to a new value.
091             * The sample location is given by the channel index and the spatial coordinates, x and y.
092             * @param channel the number of the channel, from <code>0</code> to {@link #getNumChannels} <code>- 1</code>
093             * @param x the horizontal position of the sample, from <code>0</code> to {@link #getWidth} <code>- 1</code>
094             * @param y the vertical position of the sample, from <code>0</code> to {@link #getHeight} <code>- 1</code>
095             * @param newValue the new value of the sample
096             */
097            void putSample(int channel, int x, int y, int newValue);
098    
099            /**
100             * Copies a number of samples from an <code>int[]</code> array to this image.
101             * A rectangular part of one channel is copied - the upper left corner of
102             * that rectangle is given by the point x / y.
103             * Width and height of that rectangle are given by w and h.
104             * Each sample will be stored as one <code>int</code> value src,
105             * starting at index srcOffset.
106             * @param channel int (from 0 to getNumChannels() - 1) to indicate the channel to which data is copied
107             * @param x horizontal position of upper left corner of the rectangle to be copied
108             * @param y vertical position of upper left corner of the rectangle to be copied
109             * @param w width of rectangle to be copied
110             * @param h height of rectangle to be copied
111             * @param src int array from which the samples will be copied
112             * @param srcOffset int index into the src array for the position from which the samples will be copied
113             */
114            void putSamples(int channel, int x, int y, int w, int h, int[] src, int srcOffset);
115    }