001    /*
002     * ShortChannelImage
003     *
004     * Copyright (c) 2003 Marco Schmidt.
005     * All rights reserved.
006     */
007    
008    package net.sourceforge.jiu.data;
009    
010    /**
011     * An extension of the {@link IntegerImage} interface that restricts the image to 
012     * <code>short</code> samples.
013     * The minimum sample value for all channels is <code>0</code>, 
014     * the maximum sample value <code>65535</code> (2<sup>16</sup> - 1).
015     * <p>
016     * Number of channels and resolution must be given to the constructor
017     * and cannot be changed after creation.
018     * <p>
019     * Each channel of the image is made up of <code>short</code> values.
020     * Note that shorts in Java are signed, they can take values from <code>-32768</code> to <code>32767</code>.
021     * If you use {@link IntegerImage}'s getSample and putSample methods
022     * you don't have to deal with this, you always get <code>int</code> samples
023     * that are in the 0 .. 65535 interval.
024     * <p>
025     * To manually convert a Java <code>short</code> value to an <code>int</code> value 
026     * in the range of 0 to 65535, do the following:
027     * <pre>
028     * short s = ...; // initialize short value
029     * int i = s & 0xffff; 
030     * // i now is a value between 0 and 65535
031     * </pre>
032     * @author Marco Schmidt
033     * @since 0.11.0
034     */
035    public interface ShortChannelImage extends IntegerImage
036    {
037            /**
038             * Sets all samples of the first channel to the argument short value.
039             * Equal to <code>clear(0, newValue);</code>.
040             * @param newValue all samples in the first channel are set to this value
041             * @see #clear(int, short)
042             * @see #clear(int)
043             * @see #clear(int, int)
044             */
045            void clear(short newValue);
046    
047            /**
048             * Sets all samples of one channel to a new value.
049             * @param channelIndex zero-based index of the channel to be cleared (must be smaller than {@link #getNumChannels()}
050             * @param newValue all samples in the channel will be set to this value
051             */
052            void clear(int channelIndex, short newValue);
053    
054            /**
055             * Returns a single short sample from the first channel and the specified position.
056             * A call to this method is the same as <code>getShortSample(0, x, y)</code>.
057             * @param x horizontal position of the sample to be returned (must be between <code>0</code> and {@link #getWidth()}<code> - 1</code>
058             * @param y vertical position of the sample to be returned (must be between <code>0</code> and {@link #getHeight()}<code> - 1</code>
059             * @return the requested short sample
060             */
061            short getShortSample(int x, int y);
062    
063            /**
064             * Returns a single short sample from the image.
065             * When possible, try copying several samples at a time for higher speed ({@link #getShortSamples}).
066             * @param channel the number of the channel of the sample; must be from <code>0</code> to <code>{@link #getNumChannels()} - 1</code>
067             * @param x the column of the sample to be returned; must be from <code>0</code> to <code>{@link #getWidth()} - 1</code>
068             * @param y the row of the sample; must be from <code>0</code> to <code>{@link #getHeight()} - 1</code>
069             * @return the sample, a single short value
070             * @throws IllegalArgumentException if the arguments hurt one of the preconditions above
071             * @see #getShortSamples
072             */
073            short getShortSample(int channel, int x, int y);
074    
075            /**
076             * Copies samples from this image to a short array.
077             * Copies <code>num</code> samples in row <code>y</code> of channel
078             * <code>channel</code>, starting at horizontal offset <code>x</code>.
079             * Data will be written to the <code>dest</code> array, starting at
080             * offset <code>destOffset</code>.
081             * Data will be copied from one row only, so a maximum of 
082             * <code>getWidth()</code>
083             * samples can be copied with a call to this method.
084             * 
085             * @param channelIndex the index of the channel to be copied from; must be 
086             *  from <code>0</code> to <code>getNumChannels() - 1</code>
087             * @param x the horizontal offset where copying will start; must be from
088             *  <code>0</code> to <code>getWidth() - 1</code>
089             * @param y the row from which will be copied; must be from 
090             *  <code>0</code> to <code>getHeight() - 1</code>
091             * @param w number of columns to be copied
092             * @param h number of rows to be copied
093             * @param dest the array where the data will be copied to; must have a 
094             *  length of at least <code>destOffset + num</code>
095             * @param destOffset the offset into <code>dest</code> where this method
096             *  will start copying data
097             * @throws IllegalArgumentException if the arguments hurt one of the many
098             *  preconditions above
099             */
100            void getShortSamples(int channelIndex, int x, int y, int w, int h, short[] dest, int destOffset);
101    
102            /**
103             * Sets one short sample in one channel to a new value.
104             */
105            void putShortSample(int channel, int x, int y, short newValue);
106    
107            /**
108             * Sets one short sample in the first channel (index <code>0</code>) to a new value.
109             * Result is equal to <code>putShortSample(0, x, y, newValue);</code>.
110             */
111            void putShortSample(int x, int y, short newValue);
112    
113            /**
114             * Copies a number of samples from the argument array to this image.
115             */
116            void putShortSamples(int channel, int x, int y, int w, int h, short[] src, int srcOffset);
117    }