001: /*
002: * $RCSfile: RandomIter.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 that allows random read-only access to any sample
016: * within its bounding rectangle. This flexibility will generally
017: * exact a corresponding price in speed and setup overhead.
018: *
019: * <p> The iterator is initialized with a particular rectangle as its
020: * bounds, which it is illegal to exceed. This initialization takes
021: * place in a factory method and is not a part of the iterator
022: * interface itself.
023: *
024: * <p> The getSample(), getSampleFloat(), and getSampleDouble()
025: * methods are provided to allow read-only access to the source data.
026: * The getPixel() methods allow retrieval of all bands simultaneously.
027: *
028: * <p> An instance of RandomIter may be obtained by means of the
029: * RandomIterFactory.create() method, which returns an opaque
030: * object implementing this interface.
031: *
032: * @see WritableRandomIter
033: * @see RandomIterFactory
034: */
035: public interface RandomIter {
036:
037: /**
038: * Returns the specified sample from the image.
039: *
040: * @param x the X coordinate of the desired pixel.
041: * @param y the Y coordinate of the desired pixel.
042: * @param b the band to retrieve.
043: */
044: int getSample(int x, int y, int b);
045:
046: /**
047: * Returns the specified sample from the image as a float.
048: *
049: * @param x the X coordinate of the desired pixel.
050: * @param y the Y coordinate of the desired pixel.
051: * @param b the band to retrieve.
052: */
053: float getSampleFloat(int x, int y, int b);
054:
055: /**
056: * Returns the specified sample from the image as a double.
057: *
058: * @param x the X coordinate of the desired pixel.
059: * @param y the Y coordinate of the desired pixel.
060: * @param b the band to retrieve.
061: */
062: double getSampleDouble(int x, int y, int b);
063:
064: /**
065: * Returns the samples of the specified pixel from the image
066: * in an array of int.
067: *
068: * @param x the X coordinate of the desired pixel.
069: * @param y the Y coordinate of the desired pixel.
070: * @param iArray An optionally preallocated int array.
071: * @return the contents of the pixel as an int array.
072: */
073: int[] getPixel(int x, int y, int[] iArray);
074:
075: /**
076: * Returns the samples of the specified pixel from the image
077: * in an array of float.
078: *
079: * @param x the X coordinate of the desired pixel.
080: * @param y the Y coordinate of the desired pixel.
081: * @param fArray An optionally preallocated float array.
082: * @return the contents of the pixel as a float array.
083: */
084: float[] getPixel(int x, int y, float[] fArray);
085:
086: /**
087: * Returns the samples of the specified pixel from the image
088: * in an array of double.
089: *
090: * @param x the X coordinate of the desired pixel.
091: * @param y the Y coordinate of the desired pixel.
092: * @param dArray An optionally preallocated double array.
093: * @return the contents of the pixel as a double array.
094: */
095: double[] getPixel(int x, int y, double[] dArray);
096:
097: /**
098: * Informs the iterator that it may discard its internal data
099: * structures. This method should be called when the iterator
100: * will no longer be used.
101: */
102: void done();
103: }
|