Packages  This Package  Prev  Next  Index

§2.8 Class PixelGrabber

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

        // Methods
    public boolean grabPixels();	§2.8.3
    public boolean grabPixels(long  ms);	§2.8.4
    public void imageComplete(int  status);	§2.8.5
    public void setColorModel(ColorModel  model);	§2.8.6
    public void setDimensions(int  width, int  height)	§2.8.7
        public void setHints(int  hints);	§2.8.8
    public void setPixels(int  srcX, int  srcY, int  srcW,	§2.8.9
                        int  srcH, ColorModel  model,
                       byte  pixels[], int  srcOff, int  srcScan);
    public void setPixels(int  srcX, int  srcY, int  srcW,	§2.8.10
                         int  srcH, ColorModel  model,
                        int  pixels[], int  srcOff,  int  srcScan);
    public void setProperties(Hashtable  props);	§2.8.11
    public int status();	§2.8.12
}

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 (II-§2.1.9).

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 (§2.8.3, §2.8.4) and the status method (II-§2.8.12) 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.

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 (II-§2.1.9). The pixel data for the coordinate

, where

is inside the indicted rectangle, is stored in the array at index

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.

Parameters:: 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 (II-§2.1.9). The pixel data for the coordinate

, where

is inside the indicted rectangle, is stored in the array at the index

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.

Parameters:: 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

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.

Returns:: true if the pixels were successfully grabbed; false on abort or error.
Throws: InterruptedException (I-§1.37); 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.

Parameters:: ms -the number of milliseconds to wait for the pixels
Returns:: true if the pixels were successfully grabbed; false on abort, error or timeout.
Throws: InterruptedException (I-§1.37); 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 §2.10.10 on page 304.

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.

Parameters:: 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 §2.10.11 on page 305

The setColorModel method of PixelGrabber ignores this call.

Parameters:: 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.

Parameters:: 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 §2.10.13 on page 306.

The setHints method of PixelGrabber ignores the hints.

Parameters:: 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 §2.10.14 on page 307.

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 (II-§2.8.3).

Parameters:: 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 setPixels method of PixelGrabber places the bits, if appropriate, into the array of bits passed to it by a call to the grabPixels method (II-§2.8.3).

Parameters:: 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 §2.10.16 on page 308.

The setPropertiess method of PixelGrabber ignores the hints.

Parameters:: props -a hashtable that maps image properties to their value

status

public int status()

Returns the bitwise OR of the appropriate ImageObserver interface (II-§2.11) flags.

Returns:: the status of the pixels.

Packages  This Package  Prev  Next  Index