java.awt.image

Class PixelGrabber

public class PixelGrabber extends Object implements ImageConsumer

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

Constructor Summary
	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.
	PixelGrabber(Image img, int x, int y, int w, int h, boolean forceRGB) Construct a PixelGrabber that will retrieve data from a given Image.

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. setDimensions is an ImageConsumer method.
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.
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. setProperties is an ImageConsumer method.
void	startGrabbing() Start grabbing pixels.
int	status()

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

abortGrabbing

public void abortGrabbing()

Abort pixel grabbing.

getColorModel

public ColorModel getColorModel()

Returns: the ColorModel currently being used for the majority of pixel data conversions

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

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

grabPixels

public 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.

Returns: true if successful, false on abort or error

Throws: InterruptedException if interrupted by another thread.

grabPixels

public boolean grabPixels(long ms)

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

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.

Parameters: status the status of image production, represented by a bitwise OR of ImageConsumer flags

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.

Parameters: model the color model to be used most often by setPixels

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.

Parameters: width the width of the image height the height of the image

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.

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.

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)

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.

Parameters: props a list of properties associated with the image being produced

startGrabbing

public void startGrabbing()

Start grabbing pixels. Spawns an image production thread that calls back to this PixelGrabber's ImageConsumer methods.

status

public int status()

Returns: the return value of getStatus

UNKNOWN: The newer getStatus should be used in place of status.