001    /*
002     * ByteChannelImage
003     *
004     * Copyright (c) 2000, 2001, 2002, 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     * byte samples.
013     * The minimum sample value for all channels is <code>0</code>, 
014     * the maximum sample value <code>255</code>.
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>byte</code> values.
020     * Note that bytes in Java are signed, they can take values from <code>-128</code> to <code>127</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 .. 255 interval.
024     * <p>
025     * To manually convert a Java <code>byte</code> value to an <code>int</code> value 
026     * in the range of 0 to 255, do the following:
027     * <pre>
028     * byte b = ...; // initialize byte value
029     * int i = b & 0xff; 
030     * // i now is a value between 0 and 255
031     * </pre>
032     * @author Marco Schmidt
033     */
034    public interface ByteChannelImage extends IntegerImage
035    {
036            /**
037             * Sets all samples of the first channel to the argument byte value.
038             * Equal to <code>clear(0, newValue);</code>.
039             * @param newValue all samples in the first channel are set to this value
040             * @see #clear(int, byte)
041             * @see #clear(int)
042             * @see #clear(int, int)
043             */
044            void clear(byte newValue);
045    
046            /**
047             * Sets all samples of one channel to a new value.
048             * @param channelIndex zero-based index of the channel to be cleared (must be smaller than {@link #getNumChannels()}
049             * @param newValue all samples in the channel will be set to this value
050             */
051            void clear(int channelIndex, byte newValue);
052    
053            /**
054             * Returns a single byte sample from the first channel and the specified position.
055             * A call to this method is the same as <code>getByteSample(0, x, y)</code>.
056             * @param x horizontal position of the sample to be returned (must be between <code>0</code> and {@link #getWidth()}<code> - 1</code>
057             * @param y vertical position of the sample to be returned (must be between <code>0</code> and {@link #getHeight()}<code> - 1</code>
058             * @return the requested byte sample
059             */
060            byte getByteSample(int x, int y);
061    
062            /**
063             * Returns a single byte sample from the image.
064             * When possible, try copying several samples at a time for 
065             * higher speed ({@link #getByteSamples}).
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 byte value
070             * @throws IllegalArgumentException if the arguments hurt one of the preconditions above
071             * @see #getByteSamples
072             */
073            byte getByteSample(int channel, int x, int y);
074    
075            /**
076             * Copies samples from this image to a byte 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 the number of columns to be copied
092             * @param h the 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 getByteSamples(int channelIndex, int x, int y, int w, int h, byte[] dest, int destOffset);
101    
102            /**
103             * Sets one byte sample in one channel to a new value.
104             */
105            void putByteSample(int channel, int x, int y, byte newValue);
106    
107            /**
108             * Sets one byte sample in the first channel (index <code>0</code>) to a new value.
109             * Result is equal to <code>putByteSample(0, x, y, newValue);</code>.
110             */
111            void putByteSample(int x, int y, byte newValue);
112    
113            /**
114             * Copies a number of samples from the argument array to this image.
115             */
116            void putByteSamples(int channel, int x, int y, int w, int h, byte[] src, int srcOffset);
117    }