java.awt.image
Class PixelGrabber

java.lang.Object
  extended by java.awt.image.PixelGrabber
All Implemented Interfaces:
ImageConsumer

public class PixelGrabber
extends Object
implements ImageConsumer

PixelGrabber is an ImageConsumer that extracts a rectangular region of pixels from an Image.


Field Summary
 
Fields inherited from interface java.awt.image.ImageConsumer
COMPLETESCANLINES, IMAGEABORTED, IMAGEERROR, RANDOMPIXELORDER, SINGLEFRAME, SINGLEFRAMEDONE, SINGLEPASS, STATICIMAGEDONE, TOPDOWNLEFTRIGHT
 
Constructor Summary
PixelGrabber(Image img, int x, int y, int w, int h, boolean forceRGB)
          Construct a PixelGrabber that will retrieve data from a given Image.
PixelGrabber(Image img, int x, int y, int w, int h, int[] pix, int off, int scansize)
          Construct a PixelGrabber that will retrieve RGB data from a given Image.
PixelGrabber(ImageProducer ip, int x, int y, int w, int h, int[] pix, int off, int scansize)
          Construct a PixelGrabber that will retrieve RGB data from a given ImageProducer.
 
Method Summary
 void abortGrabbing()
          Abort pixel grabbing.
 ColorModel getColorModel()
           
 int getHeight()
           
 Object getPixels()
           
 int getStatus()
           
 int getWidth()
           
 boolean grabPixels()
          Have our Image or ImageProducer start sending us pixels via our ImageConsumer methods and wait for all pixels in the grab rectangle to be delivered.
 boolean grabPixels(long ms)
          grabPixels's behavior depends on the value of ms.
 void imageComplete(int status)
          Our ImageProducer calls this method to inform us that a single frame or the entire image is complete.
 void setColorModel(ColorModel model)
          Our ImageProducer will call setColorModel to indicate the model used by the majority of calls to setPixels.
 void setDimensions(int width, int height)
          Our ImageProducer calls this method to indicate the size of the image being produced.
 void setHints(int flags)
          Our ImageProducer may call this method with a bit mask of hints from any of RANDOMPIXELORDER, TOPDOWNLEFTRIGHT, COMPLETESCANLINES, SINGLEPASS, SINGLEFRAME.
 void setPixels(int x, int y, int w, int h, ColorModel model, byte[] pixels, int offset, int scansize)
          Our ImageProducer calls setPixels to deliver a subset of its pixels.
 void setPixels(int x, int y, int w, int h, ColorModel model, int[] pixels, int offset, int scansize)
          Our ImageProducer calls setPixels to deliver a subset of its pixels.
 void setProperties(Hashtable<?,?> props)
          Our ImageProducer may call this method to send us a list of its image's properties.
 void startGrabbing()
          Start grabbing pixels.
 int status()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PixelGrabber

public PixelGrabber(Image img,
                    int x,
                    int y,
                    int w,
                    int h,
                    int[] pix,
                    int off,
                    int scansize)
Construct a PixelGrabber that will retrieve RGB data from a given Image. The RGB data will be retrieved from a rectangular region (x, y, w, h) within the image. The data will be stored in the provided pix array, which must have been initialized to a size of at least w * h. The data for a pixel (m, n) in the grab rectangle will be stored at pix[(n - y) * scansize + (m - x) + off].

Parameters:
img - the Image from which to grab pixels
x - the x coordinate, relative to img's top-left corner, of the grab rectangle's top-left pixel
y - the y coordinate, relative to img's top-left corner, of the grab rectangle's top-left pixel
w - the width of the grab rectangle, in pixels
h - the height of the grab rectangle, in pixels
pix - the array in which to store grabbed RGB pixel data
off - the offset into the pix array at which to start storing RGB data
scansize - a set of scansize consecutive elements in the pix array represents one row of pixels in the grab rectangle

PixelGrabber

public PixelGrabber(ImageProducer ip,
                    int x,
                    int y,
                    int w,
                    int h,
                    int[] pix,
                    int off,
                    int scansize)
Construct a PixelGrabber that will retrieve RGB data from a given ImageProducer. The RGB data will be retrieved from a rectangular region (x, y, w, h) within the image produced by ip. The data will be stored in the provided pix array, which must have been initialized to a size of at least w * h. The data for a pixel (m, n) in the grab rectangle will be stored at pix[(n - y) * scansize + (m - x) + off].

Parameters:
ip - the ImageProducer from which to grab pixels. This can be null.
x - the x coordinate of the grab rectangle's top-left pixel, specified relative to the top-left corner of the image produced by ip
y - the y coordinate of the grab rectangle's top-left pixel, specified relative to the top-left corner of the image produced by ip
w - the width of the grab rectangle, in pixels
h - the height of the grab rectangle, in pixels
pix - the array in which to store grabbed RGB pixel data
off - the offset into the pix array at which to start storing RGB data
scansize - a set of scansize consecutive elements in the pix array represents one row of pixels in the grab rectangle

PixelGrabber

public PixelGrabber(Image img,
                    int x,
                    int y,
                    int w,
                    int h,
                    boolean forceRGB)
Construct a PixelGrabber that will retrieve data from a given Image. The RGB data will be retrieved from a rectangular region (x, y, w, h) within the image. The data will be stored in an internal array which can be accessed by calling getPixels. The data for a pixel (m, n) in the grab rectangle will be stored in the returned array at index (n - y) * scansize + (m - x) + off. If forceRGB is false, then the returned data will be not be converted to RGB from its format in img. If w is negative, the width of the grab region will be from x to the right edge of the image. Likewise, if h is negative, the height of the grab region will be from y to the bottom edge of the image.

Parameters:
img - the Image from which to grab pixels
x - the x coordinate, relative to img's top-left corner, of the grab rectangle's top-left pixel
y - the y coordinate, relative to img's top-left corner, of the grab rectangle's top-left pixel
w - the width of the grab rectangle, in pixels
h - the height of the grab rectangle, in pixels
forceRGB - true to force conversion of the rectangular region's pixel data to RGB
Method Detail

startGrabbing

public void startGrabbing()
Start grabbing pixels. Spawns an image production thread that calls back to this PixelGrabber's ImageConsumer methods.


abortGrabbing

public void abortGrabbing()
Abort pixel grabbing.


grabPixels

public boolean grabPixels()
                   throws InterruptedException
Have our Image or ImageProducer start sending us pixels via our ImageConsumer methods and wait for all pixels in the grab rectangle to be delivered.

Returns:
true if successful, false on abort or error
Throws:
InterruptedException - if interrupted by another thread.

grabPixels

public boolean grabPixels(long ms)
                   throws InterruptedException
grabPixels's behavior depends on the value of ms. If ms < 0, return true if all pixels from the source image have been delivered, false otherwise. Do not wait. If ms >= 0 then we request that our Image or ImageProducer start delivering pixels to us via our ImageConsumer methods. If ms > 0, wait at most ms milliseconds for delivery of all pixels within the grab rectangle. If ms == 0, wait until all pixels have been delivered.

Returns:
true if all pixels from the source image have been delivered, false otherwise
Throws:
InterruptedException - if this thread is interrupted while we are waiting for pixels to be delivered

getStatus

public int getStatus()
Returns:
the status of the pixel grabbing thread, represented by a bitwise OR of ImageObserver flags

getWidth

public int getWidth()
Returns:
the width of the grab rectangle in pixels, or a negative number if the ImageProducer has not yet called our setDimensions method

getHeight

public int getHeight()
Returns:
the height of the grab rectangle in pixels, or a negative number if the ImageProducer has not yet called our setDimensions method

getPixels

public Object getPixels()
Returns:
a byte array of pixel data if ImageProducer delivered pixel data using the byte[] variant of setPixels, or an int array otherwise

getColorModel

public ColorModel getColorModel()
Returns:
the ColorModel currently being used for the majority of pixel data conversions

setDimensions

public void setDimensions(int width,
                          int height)
Our ImageProducer calls this method to indicate the size of the image being produced. setDimensions is an ImageConsumer method. None of PixelGrabber's ImageConsumer methods should be called by code that instantiates a PixelGrabber. They are only made public so they can be called by the PixelGrabber's ImageProducer.

Specified by:
setDimensions in interface ImageConsumer
Parameters:
width - the width of the image
height - the height of the image

setProperties

public void setProperties(Hashtable<?,?> props)
Our ImageProducer may call this method to send us a list of its image's properties. setProperties is an ImageConsumer method. None of PixelGrabber's ImageConsumer methods should be called by code that instantiates a PixelGrabber. They are only made public so they can be called by the PixelGrabber's ImageProducer.

Specified by:
setProperties in interface ImageConsumer
Parameters:
props - a list of properties associated with the image being produced

setColorModel

public void setColorModel(ColorModel model)
Our ImageProducer will call setColorModel to indicate the model used by the majority of calls to setPixels. Each call to setPixels could however indicate a different ColorModel. setColorModel is an ImageConsumer method. None of PixelGrabber's ImageConsumer methods should be called by code that instantiates a PixelGrabber. They are only made public so they can be called by the PixelGrabber's ImageProducer.

Specified by:
setColorModel in interface ImageConsumer
Parameters:
model - the color model to be used most often by setPixels
See Also:
ColorModel

setHints

public void setHints(int flags)
Our ImageProducer may call this method with a bit mask of hints from any of RANDOMPIXELORDER, TOPDOWNLEFTRIGHT, COMPLETESCANLINES, SINGLEPASS, SINGLEFRAME. setHints is an ImageConsumer method. None of PixelGrabber's ImageConsumer methods should be called by code that instantiates a PixelGrabber. They are only made public so they can be called by the PixelGrabber's ImageProducer.

Specified by:
setHints in interface ImageConsumer
Parameters:
flags - a bit mask of hints

setPixels

public void setPixels(int x,
                      int y,
                      int w,
                      int h,
                      ColorModel model,
                      byte[] pixels,
                      int offset,
                      int scansize)
Our ImageProducer calls setPixels to deliver a subset of its pixels. Each element of the pixels array represents one pixel. The pixel data is formatted according to the color model model. The x and y parameters are the coordinates of the rectangular region of pixels being delivered to this ImageConsumer, specified relative to the top left corner of the image being produced. Likewise, w and h are the pixel region's dimensions.

Specified by:
setPixels in interface ImageConsumer
Parameters:
x - x coordinate of pixel block
y - y coordinate of pixel block
w - width of pixel block
h - height of pixel block
model - color model used to interpret pixel data
pixels - pixel block data
offset - offset into pixels array
scansize - width of one row in the pixel block

setPixels

public void setPixels(int x,
                      int y,
                      int w,
                      int h,
                      ColorModel model,
                      int[] pixels,
                      int offset,
                      int scansize)
Our ImageProducer calls setPixels to deliver a subset of its pixels. Each element of the pixels array represents one pixel. The pixel data is formatted according to the color model model. The x and y parameters are the coordinates of the rectangular region of pixels being delivered to this ImageConsumer, specified relative to the top left corner of the image being produced. Likewise, w and h are the pixel region's dimensions.

Specified by:
setPixels in interface ImageConsumer
Parameters:
x - x coordinate of pixel block
y - y coordinate of pixel block
w - width of pixel block
h - height of pixel block
model - color model used to interpret pixel data
pixels - pixel block data
offset - offset into pixels array
scansize - width of one row in the pixel block

imageComplete

public void imageComplete(int status)
Our ImageProducer calls this method to inform us that a single frame or the entire image is complete. The method is also used to inform us of an error in loading or producing the image.

Specified by:
imageComplete in interface ImageConsumer
Parameters:
status - the status of image production, represented by a bitwise OR of ImageConsumer flags

status

public int status()
Returns:
the return value of getStatus