Package java.awt.image

Previous

Java API

Index

Next

Class PixelGrabber

public  class  java.awt.image.PixelGrabber
    extends  java.lang.Object  
    implements java.awt.image.ImageConsumer  
{
        // Constructors
    public PixelGrabber(Image  img, int  x, int  y, 	
         int  w, int  h, int  pix[], int  off, int  scansize);
    public PixelGrabber(ImageProducer  ip, int  x,	
        int  y, int  w, int  h, int  pix[], int  off, int  scansize);

        // Methods
    public boolean grabPixels();	
    public boolean grabPixels(long  ms);	
    public void imageComplete(int  status);	
    public void setColorModel(ColorModel  model);	
    public void setDimensions(int  width, int  height)	
        public void setHints(int  hints);	
    public void setPixels(int  srcX, int  srcY, int  srcW,	
                        int  srcH, ColorModel  model,
                       byte  pixels[], int  srcOff, int  srcScan);
    public void setPixels(int  srcX, int  srcY, int  srcW,	
                         int  srcH, ColorModel  model,
                        int  pixels[], int  srcOff,  int  srcScan);
    public void setProperties(Hashtable  props);	
    public int status();	
}

The pixel grabber implements an image consumer which can be attached to an image or image producer object to retrieve a subset of the pixels in that image. Pixels are stored in the array in the default RGB color model .

For example:

public  void  handleSinglePixel(int  x,  int  y,  int  pixel)  {
        int  alpha  =  (pixel  >>  24)  &  0xff;
        int  red      =  (pixel  >>  16)  &  0xff;
        int  green  =  (pixel  >>    8)  &  0xff;
        int  blue    =  (pixel            )  &  0xff;
        //  Deal  with  the  pixel  as  necessary...
}

public  void  GetPixels(Image  img,  int  x,  int  y,  int  w,  int  h)  {
        int[]  pixels  =  new  int[w  *  h];
        PixelGrabber  pg  =  
                new  PixelGrabber(img,  x,  y,  w,  h,  pixels,  0,  w);
        try  {
                pg.grabPixels();
        }  catch  (InterruptedException  e)  {
                System.err.println("interrupted  waiting  for  pixels!");
                return;
        }
        if  ((pg.status()  &  ImageObserver.ABORT)  !=  0)  {
              System.err.println("image  fetch  aborted  or  errored");
              return;
        }
        for  (int  j  =  0;  j  <  h;  j++)  {
                for  (int  i  =  0;  i  <  w;  i++)  {
                        // look at the pixel
                        handleSinglePixel(x+i, y+j, pixels[j * w + i]);
                }
        }

}

Most applications need to call only the grabPixel methods and the status method of this class. The remaining methods are part of the ImageConsumer interface and allow the pixel grabber to receive the image from the image producer.

Constructors

PixelGrabber

public PixelGrabber(Image  img, int  x, int  y, int  w, int  h,
                                        int  pix[], int  off, int  scansize) 

Creates a new pixel grabber object to grab the rectangular section of pixels from the specified image into the specified array.

The pixels are stored in the array in the default RGB color model . The pixel data for the coordinate (i,j), where (i,j) is inside the indicated rectangle, is stored in the array at index

(j - y) ´ scan + (i - x) + offset

of the pixel array.

The x and y coordinates indicate the upper left corner of the rectangle of pixels to retrieve from the image, relative to the default (unscaled) size of the image.

Parameter	Description
img	the image from which to retrieve pixels
x	the x coordinate of the upper left corner
y	the y coordinate of the upper left corner
w	the width of the rectangle to retrieve
h	the height of the rectangle to retrieve
pix	the array of integers into which to place the RGB pixels retrieved from the image
off	the offset into the array to store the first pixel
scansize	the distance from the start of one row of pixels to the start of the next row in the array

PixelGrabber

public PixelGrabber(ImageProducer  ip, int  x, int  y,
                                        int  w, int  h, int  pix[],
                                        int  off, int  scansize) 

Creates a new pixel grabber object to grab the rectangular section of pixels from the specified image producer into the specified array.

The pixels are stored in the array in the default RGB color model . The pixel data for the coordinate (i,j), where (i,j) is inside the indicted rectangle, is stored in the array at the index

(j - y) ´ scan + (i - x) + offset

of the pixel array.

The x and y coordinates indicate the upper left corner of the rectangle of pixels to retrieve from the image, relative to the default (unscaled) size of the image.

Parameter	Description
ip	the image producer
x	the x coordinate of the upper left corner
y	the y coordinate of the upper left corner
w	the width of the rectangle to retrieve
h	the height of the rectangle to retrieve
pix	the array of integers into which to place the RGB pixels retrieved from the image
off	the offset into the array to store the first pixel
scansize	the distance from the start of one row of pixels to the start of the next row in the array

Methods

grabPixels

public boolean grabPixels() 

throws InterruptedException 

Requests the image or image producer to start delivering pixels to this image consumer. It waits for all of the pixels in the rectangle of interest to be delivered.

Return Value:

Returns true if the pixels were successfully grabbed; false on abort or error.

Throw:

InterruptedException

If another thread has interrupted this thread.

grabPixels

public boolean grabPixels(long  ms) 

throws InterruptedException 

Requests the image or image producer to start delivering pixels to this image consumer. It waits for all of the pixels in the rectangle of interest to be delivered, or until the specified timeout has elapsed.

Return Value:

Returns true if the pixels were successfully grabbed; false on abort, error or timeout.

Parameter	Description
ms	the number of milliseconds to wait for the pixels

Throw:

InterruptedException

If another thread has interrupted this thread.

imageComplete

public void imageComplete(int  status) 

The image producer calls the imageComplete method when it has completed an image or it has errored in producing or loading the image. For more information on this method and its status argument, see imageComplete.

The imageComplete method of PixelGrabber notifies all processes waiting for the pixels to wake up. It uses the value of the status flag to determine whether the image was successfully retrieved or not.

Parameter	Description
status	the status of the image

setColorModel

public void setColorModel(ColorModel  model) 

The image producer calls the setColorModel method to specify the color model for the majority of the subsequent setPixels method calls. For more information on this method and its model argument, see setColorModel

The setColorModel method of PixelGrabber ignores this call.

Parameter	Description
model	a color map used in subsequent setPixel calls

setDimensions

public void setDimensions(int  width, int  height) 

The image producer calls the setDimensions of the image consumer to tell it the width and height of the image.

The setDimensions method of PixelGrabber ignores the dimensions.

Parameter	Description
width	the width of the image
height	the height of the image

setHints

public void setHints(int  hints) 

The image producer calls the setHints method of the image consumer to indicate the order in which the bits will be delivered. For more information on the hints passed to the image consumer, see setHints.

The setHints method of PixelGrabber ignores the hints.

Parameter	Description
hints	hints about the order in which the bits will be delivered

setPixels

public void
setPixels(int  srcX, int  srcY, int  srcW, int  srcH,
                    ColorModel  model, byte  pixels[],
                    int  srcOff, int  srcScan) 

The image producer calls the setPixels method of the image consumer one or more times to deliver the pixels of the image. For more information on this method and its arguments, see setPixels.

The setPixels method of PixelGrabber places the bits, if appropriate, into the array of bits passed to it by a call to the grabPixels method .

Parameter	Description
x	left coordinate of rectangle
y	top coordinte of rectangle
w	width of rectangle
h	height of rectangle
model	color model for bits
pixels	array of bits
off	offset for first element
scansize	number of elements per row

setPixels

public void
setPixels(int  srcX, int  srcY, int  srcW, int  srcH,
                    ColorModel  model, int  pixels[],
                    int  srcOff, int  srcScan) 

The image producer calls the setPixels method of the image consumer one or more times to deliver the pixels of the image. For more information on this method and its arguments, see setPixels.

The setPixels method of PixelGrabber places the bits, if appropriate, into the array of bits passed to it by a call to the grabPixels method .

Parameter	Description
x	left coordinate of rectangle
y	top coordinte of rectangle
w	width of rectangle
h	height of rectangle
model	color model for bits
pixels	array of bits
off	offset for first element
scansize	number of elements per row

setProperties

public void setProperties(Hashtable  props) 

The image producer calls the setProperties method of the image consumer to let it know of additional properties of the image. For more information on this method and its arguments, see setProperties.

The setPropertiess method of PixelGrabber ignores the hints.

Parameter	Description
props	a hashtable that maps image properties to their value

status

public int status() 

Returns the bitwise OR of the appropriate ImageObserver interface flags.

Return Value:

Returns the status of the pixels.