[Chapter 22] PixelGrabber

#

| Chapter 22 java.awt.image Reference |

# PixelGrabber

## Name

PixelGrabber

##

## Description

The `PixelGrabber` class is an `ImageConsumer` that captures the pixels from an image and saves them in an array.

## Class Definition

    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,
          boolean forceRGB);
      public PixelGrabber (Image image, int x, int y, int width,
          int height, int[] pixels, int offset, int scansize);
      public PixelGrabber (ImageProducer ip, int x, int y, int width,
          int height, int[] pixels, int offset, int scansize);
      // Instance Methods
      public synchronized void abortGrabbing();
      public synchronized ColorModel getColorModel();
      public synchronized int getHeight();
      public synchronized Object getPixels();
      public synchronized int getStatus();
      public synchronized int getWidth();
      public boolean grabPixels() throws InterruptedException;
      public synchronized boolean grabPixels (long ms)
          throws InterruptedException;
      public synchronized 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 x, int y, int width, int height,
          ColorModel model, byte[] pixels, int offset, int scansize);
      public void setPixels (int x, int y, int width, int height,
          ColorModel model, int[] pixels, int offset, int scansize);
      public void setProperties (Hashtable properties);
      public synchronized void startGrabbing();
      public synchronized int status();
    }

## Constructors

### PixelGrabber

#### public PixelGrabber (Image img, int x, int y, int w, int h, boolean forceRGB)

Parameters

  img

    `Image` to use as source of pixel data.

  x

    x-coordinate of top-left corner of pixel data.

  y

    y-coordinate of top-left corner of pixel data.

  w

    Width of pixel data.

  h

    Height of pixel data.

  forceRGB

    `true` to force the use of the RGB color model; `false` otherwise.

Description

  Constructs a `PixelGrabber` instance to grab the specified area of the image.

#### public PixelGrabber (Image image, int x, int y, int width, int height, int[] pixels, int offset, int scansize)

Parameters

  image

    `Image` to use as source of pixel data.

  x

    x-coordinate of top-left corner of pixel data.

  y

    y-coordinate of top-left corner of pixel data.

  width

    Width of pixel data.

  height

    Height of pixel data.

  pixels

    Where to store pixel data when `grabPixels()` called.

  offset

    Offset from beginning of each line in pixels array.

  scansize

    Size of each line of data in pixels array.

Description

  Constructs a `PixelGrabber` instance to grab the specified area of the image and store the pixel data from this area in the array `pixels[]`.

#### public PixelGrabber (ImageProducer ip, int x, int y, int width, int height, int[] pixels, int offset, int scansize)

Parameters

  ip

    `ImageProducer` to use as source of pixel data.

  x

    x-coordinate of top-left corner of pixel data.

  y

    y-coordinate of top-left corner of pixel data.

  width

    Width of pixel data.

  height

    Height of pixel data.

  pixels

    Where to store pixel data when `grabPixels()` called.

  offset

    Offset from beginning of each line in pixels array.

  scansize

    Size of each line of data in pixels array.

Description

  Constructs a `PixelGrabber` instance to grab data from the specified area of the image generated by an `ImageProducer` and store the pixel data from this area in the array `pixels[]`.

## Instance Methods

### abortGrabbing

#### public synchronized void abortGrabbing()

Description

  Stops the `PixelGrabber`'s image-grabbing process.

### getColorModel

#### public synchronized ColorModel getColorModel()

Returns

  The color model the `PixelGrabber` is using for its array.

### getHeight

#### public synchronized int getHeight()

Returns

  The height of the grabbed image, or -1 if the height is not known.

### getPixels

#### public synchronized Object getPixels()

Returns

  The array of pixels.

Description

  Either a byte array or an integer array is returned, or `null` if the size and format of the image are not yet known. Because the `PixelGrabber` may change its mind about what `ColorModel` it's using, different calls to this method may return different arrays until the image acquisition is complete.

### getStatus

#### public synchronized int getStatus()

Returns

  A combination of `ImageObserver` flags indicating what data is available.

### getWidth

#### public synchronized int getWidth()

Returns

  The width of the grabbed image, or -1 if the width is not known.

### grabPixels

#### public boolean grabPixels() throws InterruptedException

Throws

  `InterruptedException`

    If image grabbing is interrupted before completion.

Returns

  `true` if the image has completed loading, `false` if the loading process aborted or an error occurred.

Description

  Starts the process of grabbing the pixel data from the source and storing it in the array `pixels[]` from constructor. Returns when the image is complete, loading aborts, or an error occurs.

#### public synchronized boolean grabPixels (long ms) throws InterruptedException

Parameters

  ms

    Milliseconds to wait for completion.

Returns

  `true` if image has completed loading, `false` if the loading process aborted, or an error or a timeout occurred.

Throws

  `InterruptedException`

    If image grabbing is interrupted before completion.

Description

  Starts the process of grabbing the pixel data from the source and storing it in the array `pixels[]` from constructor. Returns when the image is complete, loading aborts, an error occurs, or a timeout occurs.

### imageComplete

#### public synchronized void imageComplete (int status)

Parameters

  status

    Image loading completion status flags.

Implements

  `ImageConsumer.imageComplete(``int``)`

Description

  Called by the `ImageProducer` to indicate that the image has been delivered.

### setColorModel

#### void setColorModel (ColorModel model)

Parameters

  model

    The color model for the image.

Implements

  `ImageConsumer.setColorModel(``ColorModel``)`

Description

  Does nothing.

### setDimensions

#### void setDimensions (int width, int height)

Parameters

  width

    Width for image.

  height

    Height for image.

Implements

  `ImageConsumer.setDimensions(``int, int``)`

Description

  Does nothing.

### setHints

#### void setHints (int hints)

Parameters

  hints

    Image consumption hints.

Implements

  `ImageConsumer.setHints(``int``)`

Description

  Does nothing.

### setPixels

#### void setPixels (int x, int y, int width, int height, ColorModel model, byte[] pixels, int offset, int scansize)

Parameters

  x

    x-coordinate of top-left corner of pixel data delivered with this method call.

  y

    y-coordinate of top-left corner of pixel data delivered with this method call.

  width

    Width of the rectangle of pixel data delivered with this method call.

  height

    Height of the rectangle of pixel data delivered with this method call.

  model

    Color model of image data.

  pixels

    Image data.

  offset

    Offset from beginning of the pixels array.

  scansize

    Size of each line of data in pixels array.

Implements

  `ImageConsumer.setPixels(``int, int, int, int, ColorModel, byte[], int, int``)`

Description

  Called by the `ImageProducer` to deliver pixel data from the image.

#### void setPixels (int x, int y, int width, int height, ColorModel model, int[] pixels, int offset, int scansize)

Parameters

  x

    x-coordinate of top-left corner of pixel data delivered with this method call.

  y

    y-coordinate of top-left corner of pixel data delivered with this method call.

  width

    Width of the rectangle of pixel data delivered with this method call.

  height

    Height of the rectangle of pixel data delivered with this method call.

  model

    Color model of image data.

  pixels

    Image data.

  offset

    Offset from beginning of the pixels array.

  scansize

    Size of each line of data in pixels array.

Implements

  `ImageConsumer.setPixels(``int, int, int, int, ColorModel, int[], int, int``)`

Description

  Called by the `ImageProducer` to deliver pixel data from the image.

### setProperties

#### void setProperties (Hashtable properties)

Parameters

  properties

    The properties for the image.

Implements

  `ImageConsumer.setProperties(``Hashtable``)`

Description

  Does nothing.

### startGrabbing

#### public synchronized void startGrabbing()

Description

  Starts the `PixelGrabber`'s image-grabbing process.

### status

#### public synchronized int status ()

Returns

  The `ImageObserver` flags OR'ed together representing the available information about the image. Replaced by `getStatus()`.

## See Also

`ColorModel`, `Hashtable`, `Image`, `ImageConsumer`, `ImageProducer`, `I` `nterruptedException`, `MemoryImageSource`, `Object`

MemoryImageSource |  | ReplicateScaleFilter