Package java.awt.image

Previous

Java API

Index

Next

Interface ImageConsumer

public  interface  java.awt.image.ImageConsumer
{
          // status value for the imageComplete method
        public final static int IMAGEABORTED;	
        public final static int IMAGEERROR;	
        public final static int SINGLEFRAMEDONE;	
        public final static int STATICIMAGEDONE;	

          // hints used by the setHints method
        public final static int COMPLETESCANLINES;	
        public final static int RANDOMPIXELORDER;	
        public final static int SINGLEFRAME;	
        public final static int SINGLEPASS;	
        public final static int TOPDOWNLEFTRIGHT;	

          // Methods
        public abstract void imageComplete(int  status);	
        public abstract void setColorModel(ColorModel  model);	
        public abstract void	
             setDimensions(int  width, int  height);
        public abstract void setHints(int  hintflags);	
        public abstract void 	
             setPixels(int  x, int  y, int  w, int  h,
                            ColorModel  model, byte  pixels[],
                            int  off, int  scansize);
        public abstract void	
             setPixels(int  x, int  y, int  w, int  h,
                            ColorModel  model, int  pixels[],
                            int  off, int  scansize);
        public abstract void setProperties(Hashtable  props); 
}

The image consumer interface specifies the methods that all image consumers must implement. An image consumer is an object interested in data produced by the image producers .

When a consumer is added to an image producer, the producer delivers all the data about the image using the method calls defined in this interface.

Fields

IMAGEABORTED

public final static int IMAGEABORTED = 4 

Argument to the imageComplete method indicating that the image creation process was deliberately aborted.

IMAGEERROR

public final static int IMAGEERROR = 1 

Argument to the imageComplete method indicating that an error was encountered while producing the image.

SINGLEFRAMEDONE

public final static int SINGLEFRAMEDONE = 2 

Argument to the imageComplete method indicating that one frame of the image is complete but there are more frames to be delivered.

STATICIMAGEDONE

public final static int STATICIMAGEDONE = 3 

Argument to the imageComplete method indicating that the image is complete and there are no more pixels or frames to be delivered.

COMPLETESCANLINES

public final static int COMPLETESCANLINES = 4 

Flag in the setHints method indicating that the pixels will be delivered in (multiples of) complete scanlines at a time..

RANDOMPIXELORDER

public final static int RANDOMPIXELORDER = 1 

Flag in the setHints method indicating that the pixels will be delivered in a random order.

The image consumer should not use any optimizations that depend on the order of pixel delivery. If the image producer doesn't call the setHints method, the image consumer should assume that the bits are being delivered in a random order..

SINGLEFRAME

public final static int SINGLEFRAME = 8 

Flag in the setHints method indicating that the image contains a single static image. The pixels will be defined in calls to the setPixels methods; the image producer then calls the imageComplete method with the STATICIMAGEDONE flag after which no more image data is delivered.

Examples of image types that do not meet these criteria include the output of a video feed, or the representation of a 3D rendering being manipulated by the user. The end of each frame of those types of images is indicated by the image producer calling the imageComplete method with the SINGLEFRAMEDONE flag .

SINGLEPASS

public final static int SINGLEPASS = 8 

Flag in the setHints method indicating that each pixel will be delivered only once.

An image type that does not meet this criterion is a progressive JPEG image which defines pixels in multple passes, each more refined than the previous.

TOPDOWNLEFTRIGHT = 2

public final static int TOPDOWNLEFTRIGHT 

Flag in the setHints method indicating that the pixels will be delivered in a top-down, left-to-right order.

Methods

imageComplete

public abstract void imageComplete(int  status) 

The image producer calls the imageComplete method when one of the following conditions has occurred:

• it has delivered all the pixels that the source image contains,

• a single frame of a multi-frame animation has been completed,
• an error in loading or producing the image has occurred.
• the image production was explicitly aborted by the application.

The image consumer should remove itself from the list of consumers registered with the image producer , unless it is interested in subsequent frames.

The status is one of the following values: ImageConsumer.IMAGEERROR ImageConsumer.SINGLEFRAMEDONE ImageConsumer.STATICIMAGEDONE ImageConsumer.IMAGEABORTED

Parameter	Description
status	the status of the image

setColorModel

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

Each set of pixels delivered using the setPixels method includes its own color model, so the image consumer should not assume that the model argument is the color model argument in every subsequent setPixels method call.

A notable case where multiple ColorModel objects may be seen is a filtered image where for each set of pixels that it filters, the filter determines whether the pixels can be sent on untouched, using the original ColorModel, or should be modified (filtered) and passed on using a ColorModel more convenient for the filtering process.

Parameter	Description
model	a color map used in subsequent setPixel calls

setDimensions

public abstract void
setDimensions(int  width, int  height) 

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

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

setHints

public abstract void setHints(int  hintflags) 

The image producer calls the setHints method of the image consumer to indicate the order in which the bits will be delivered.

The image producer is allowed to deliver the pixels in any order, but the image consumer may be able to scale or convert the pixels more efficiently or with higher quality if it knows some information about how the pixels will be presented.

The image producer should call the setHints method before any calls to the image consumer's setPixels method.

The hintflags agument is a bit mask of hints about the manner in which the pixels are delivered.

The possible hint flags are: COMPLETESCANLINES RANDOMPIXELORDER SINGLEFRAME SINGLEPASS TOPDOWNLEFTRIGHT

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

setPixels

public abstract void
setPixels(int  x, int  y, int  w, int  h, ColorModel model, 
                    byte  pixels[], int  off,  int  scansize) 

The image producer calls the setPixels method of the image consumer one or more times to deliver the pixels of the image. Each call specifies the location and size of the rectangle of source pixels contained in the array of pixels.

The specified color model object should be used to convert the pixels into their corresponding color and alpha components. The pixel at coordinate (i,j) is stored in the pixel array at index

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

The pixels delivered using this method are all stored as bytes.

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 abstract void
setPixels(int  x, int  y, int  w, int  h, ColorModel model, 
                    int  pixels[], int  off, int  scansize) 

The image producer calls the setPixels method of the image consumer one or more times to deliver the pixels of the image. Each call specifies the location and size of the rectangle of source pixels that are contained in the array of pixels.

The specified color model object should be used to convert the pixels into their corresponding color and alpha components. The pixel at coordinate (i,j) is stored in the pixel array at index

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

The pixels delivered using this method are all stored as integers.

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

setProperties

public abstract void setProperties(Hashtable  props) 

The image producer calls the setProperties method of the image consumer to indicate additional properties of the image.

All keys to the hash table are strings. The corresponding values depend on the string.

Parameter	Description
props	a hashtable of properties

See Also: getProperty in class Image .