001: /*
002: * $RCSfile: RectIter.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:26 $
010: * $State: Exp $
011: */
012: package javax.media.jai.iterator;
013:
014: /**
015: * An iterator for traversing a read-only image in top-to-bottom,
016: * left-to-right order. This will generally be the fastest style of
017: * iterator, since it does not need to perform bounds checks against
018: * the top or left edges of tiles.
019: *
020: * <p> The iterator is initialized with a particular rectangle as its
021: * bounds, which it is illegal to exceed. This initialization takes
022: * place in a factory method and is not a part of the iterator
023: * interface itself. Once initialized, the iterator may be reset to
024: * its initial state by means of the startLine(), startPixels(), and
025: * startBands() methods. Its position may be advanced using the
026: * nextLine(), jumpLines(), nextPixel(), jumpPixels(), and nextBand()
027: * methods.
028: *
029: * <p> The iterator's position may be tested against the bounding
030: * rectangle by means of the finishedLines(), finishedPixels(),
031: * and finishedBands() methods, as well as the hybrid methods
032: * nextLineDone(), nextPixelDone(), and nextBandDone().
033: *
034: * <p> The getSample(), getSampleFloat(), and getSampleDouble()
035: * methods are provided to allow read-only access to the source data.
036: * The various source bands may also be accessed in random fashion
037: * using the variants that accept a band index. The getPixel() methods
038: * allow retrieval of all bands simultaneously.
039: *
040: * <p> An instance of RectIter may be obtained by means
041: * of the RectIterFactory.create() method, which returns
042: * an opaque object implementing this interface.
043: *
044: * @see WritableRectIter
045: * @see RectIterFactory
046: */
047: public interface RectIter {
048:
049: /**
050: * Sets the iterator to the first line of its bounding rectangle.
051: * The pixel and band offsets are unchanged.
052: */
053: void startLines();
054:
055: /**
056: * Sets the iterator to the next line of the image. The pixel and
057: * band offsets are unchanged. If the iterator passes the bottom
058: * line of the rectangles, calls to get() methods are not valid.
059: */
060: void nextLine();
061:
062: /**
063: * Sets the iterator to the next line in the image, and returns
064: * true if the bottom row of the bounding rectangle has been
065: * passed.
066: */
067: boolean nextLineDone();
068:
069: /**
070: * Jumps downward num lines from the current position. Num may be
071: * negative. The pixel and band offsets are unchanged. If the
072: * position after the jump is outside of the iterator's bounding
073: * box, an <code>IndexOutOfBoundsException</code> will be thrown
074: * and the position will be unchanged.
075: *
076: * @throws IndexOutOfBoundsException if the position goes outside
077: * of the iterator's bounding box.
078: */
079: void jumpLines(int num);
080:
081: /**
082: * Returns true if the bottom row of the bounding rectangle has
083: * been passed.
084: */
085: boolean finishedLines();
086:
087: /**
088: * Sets the iterator to the leftmost pixel of its bounding rectangle.
089: * The line and band offsets are unchanged.
090: */
091: void startPixels();
092:
093: /**
094: * Sets the iterator to the next pixel in image (that is, move
095: * rightward). The line and band offsets are unchanged.
096: *
097: * <p>This method may be used in conjunction with the method
098: * <code>finishedPixels</code>. Or the method <code>nextPixelDone</code>,
099: * which sets the iterator to the next pixel and checks the bound,
100: * may be used instead of this method.
101: */
102: void nextPixel();
103:
104: /**
105: * Sets the iterator to the next pixel in the image (that is, move
106: * rightward). Returns true if the right edge of the bounding
107: * rectangle has been passed. The line and band offsets are
108: * unchanged.
109: */
110: boolean nextPixelDone();
111:
112: /**
113: * Jumps rightward num pixels from the current position. Num may
114: * be negative. The line and band offsets are unchanged. If the
115: * position after the jump is outside of the iterator's bounding
116: * box, an <code>IndexOutOfBoundsException</code> will be thrown
117: * and the position will be unchanged.
118: *
119: * @throws IndexOutOfBoundsException if the position goes outside
120: * of the iterator's bounding box.
121: */
122: void jumpPixels(int num);
123:
124: /**
125: * Returns true if the right edge of the bounding rectangle has
126: * been passed.
127: */
128: boolean finishedPixels();
129:
130: /**
131: * Sets the iterator to the first band of the image.
132: * The pixel column and line are unchanged.
133: */
134: void startBands();
135:
136: /**
137: * Sets the iterator to the next band in the image.
138: * The pixel column and line are unchanged.
139: */
140: void nextBand();
141:
142: /**
143: * Sets the iterator to the next band in the image, and returns
144: * true if the max band has been exceeded. The pixel column and
145: * line are unchanged.
146: */
147: boolean nextBandDone();
148:
149: /**
150: * Returns true if the max band in the image has been exceeded.
151: */
152: boolean finishedBands();
153:
154: /**
155: * Returns the current sample as an integer.
156: */
157: int getSample();
158:
159: /**
160: * Returns the specified sample of the current pixel as an integer.
161: *
162: * @param b the band index of the desired sample.
163: */
164: int getSample(int b);
165:
166: /**
167: * Returns the current sample as a float.
168: */
169: float getSampleFloat();
170:
171: /**
172: * Returns the specified sample of the current pixel as a float.
173: *
174: * @param b the band index of the desired sample.
175: */
176: float getSampleFloat(int b);
177:
178: /**
179: * Returns the current sample as a double.
180: */
181: double getSampleDouble();
182:
183: /**
184: * Returns the specified sample of the current pixel as a double.
185: *
186: * @param b the band index of the desired sample.
187: */
188: double getSampleDouble(int b);
189:
190: /**
191: * Returns the samples of the current pixel from the image
192: * in an array of int.
193: *
194: * @param iArray An optionally preallocated int array.
195: * @return the contents of the pixel as an int array.
196: */
197: int[] getPixel(int[] iArray);
198:
199: /**
200: * Returns the samples of the current pixel from the image
201: * in an array of float.
202: *
203: * @param fArray An optionally preallocated float array.
204: * @return the contents of the pixel as a float array.
205: */
206: float[] getPixel(float[] fArray);
207:
208: /**
209: * Returns the samples of the current pixel from the image
210: * in an array of double.
211: *
212: * @param dArray An optionally preallocated double array.
213: * @return the contents of the pixel as a double array.
214: */
215: double[] getPixel(double[] dArray);
216: }
|