Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

java.awt.image
Class BufferedImage

java.lang.Object
  java.awt.Image
      java.awt.image.BufferedImage

public class BufferedImage

extends Image

The BufferedImage subclass describes an Image with an accessible buffer of image data. All BufferedImage objects have an upper left corner coordinate of (0, 0).

See Also:

ColorModel

Field Summary

static int	TYPE_BYTE_BINARY Represents an opaque byte-packed 1, 2, or 4 bit image.
static int	TYPE_BYTE_INDEXED Represents an indexed byte image.
static int	TYPE_CUSTOM Image type is not recognized so it must be a customized image.
static int	TYPE_INT_ARGB Represents an image with 8-bit RGBA color components packed into integer pixels.
static int	TYPE_INT_ARGB_PRE Represents an image with 8-bit RGBA color components packed into integer pixels.
static int	TYPE_INT_BGR Represents an image with 8-bit RGB color components, corresponding to a Windows- or Solaris- style BGR color model, with the colors Blue, Green, and Red packed into integer pixels.
static int	TYPE_INT_RGB Represents an image with 8-bit RGB color components packed into integer pixels.
static int	TYPE_USHORT_555_RGB Represents an image with 5-5-5 RGB color components (5-bits red, 5-bits green, 5-bits blue) with no alpha.
static int	TYPE_USHORT_565_RGB Represents an image with 5-6-5 RGB color components (5-bits red, 6-bits green, 5-bits blue) with no alpha.

Fields inherited from class java.awt.Image

SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty

Method Summary

Graphics2D	createGraphics() Creates a Graphics2D, which can be used to draw into this BufferedImage.
void	flush() Flushes all resources being used to cache optimization information.
ColorModel	getColorModel() Returns the ColorModel.
Graphics	getGraphics() This method returns a Graphics2D, but is here for backwards compatibility.
int	getHeight() Returns the height of the BufferedImage.
int	getHeight(ImageObserver observer) Returns the height of the BufferedImage.
Object	getProperty(String name) Returns a property of the image by name.
Object	getProperty(String name, ImageObserver observer) Returns a property of the image by name.
String[]	getPropertyNames() Returns an array of names recognized by getProperty(String) or null, if no property names are recognized.
int	getRGB(int x, int y) Returns an integer pixel in the default RGB color model (TYPE_INT_ARGB) and default sRGB colorspace.
int[]	getRGB(int startX, int startY, int w, int h, int[] rgbArray, int offset, int scansize) Returns an array of integer pixels in the default RGB color model (TYPE_INT_ARGB) and default sRGB color space, from a portion of the image data.
ImageProducer	getSource() Returns the object that produces the pixels for the image.
BufferedImage	getSubimage(int x, int y, int w, int h) Returns a subimage defined by a specified rectangular region.
int	getType() Returns the image type.
int	getWidth() Returns the width of the BufferedImage.
int	getWidth(ImageObserver observer) Returns the width of the BufferedImage.
void	setRGB(int x, int y, int rgb) Sets a pixel in this BufferedImage to the specified RGB value.
void	setRGB(int startX, int startY, int w, int h, int[] rgbArray, int offset, int scansize) Sets an array of integer pixels in the default RGB color model (TYPE_INT_ARGB) and default sRGB color space, into a portion of the image data.
String	toString() Returns a String representation of this BufferedImage object and its values.

Methods inherited from class java.awt.Image

getScaledInstance

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE_CUSTOM

public static final int TYPE_CUSTOM

Image type is not recognized so it must be a customized image. This type is only used as a return value for the getType() method.

See Also:

Constant Field Values

TYPE_INT_RGB

public static final int TYPE_INT_RGB

Represents an image with 8-bit RGB color components packed into integer pixels. The image has a DirectColorModel without alpha.

See Also:

Constant Field Values

TYPE_INT_ARGB

public static final int TYPE_INT_ARGB

Represents an image with 8-bit RGBA color components packed into integer pixels. The image has a DirectColorModel with alpha. The color data in this image is considered not to be premultiplied with alpha.

See Also:

Constant Field Values

TYPE_INT_ARGB_PRE

public static final int TYPE_INT_ARGB_PRE

Represents an image with 8-bit RGBA color components packed into integer pixels. The image has a DirectColorModel with alpha. The color data in this image is considered to be premultiplied with alpha.

See Also:

Constant Field Values

TYPE_INT_BGR

public static final int TYPE_INT_BGR

Represents an image with 8-bit RGB color components, corresponding to a Windows- or Solaris- style BGR color model, with the colors Blue, Green, and Red packed into integer pixels. There is no alpha. The image has a DirectColorModel.

See Also:

Constant Field Values

TYPE_USHORT_565_RGB

public static final int TYPE_USHORT_565_RGB

Represents an image with 5-6-5 RGB color components (5-bits red, 6-bits green, 5-bits blue) with no alpha. This image has a DirectColorModel.

See Also:

Constant Field Values

TYPE_USHORT_555_RGB

public static final int TYPE_USHORT_555_RGB

Represents an image with 5-5-5 RGB color components (5-bits red, 5-bits green, 5-bits blue) with no alpha. This image has a DirectColorModel.

See Also:

Constant Field Values

TYPE_BYTE_BINARY

public static final int TYPE_BYTE_BINARY

Represents an opaque byte-packed 1, 2, or 4 bit image. The image has an IndexColorModel without alpha.

Images with 8 bits per pixel should use the image type TYPE_BYTE_INDEXED.

See Also:

Constant Field Values

TYPE_BYTE_INDEXED

public static final int TYPE_BYTE_INDEXED

Represents an indexed byte image.

See Also:

Constant Field Values

Method Detail

getType

public int getType()

Returns the image type. If it is not one of the known types, TYPE_CUSTOM is returned.

Returns:

the image type of this BufferedImage.

See Also:

TYPE_INT_RGB, TYPE_INT_ARGB, TYPE_INT_ARGB_PRE, TYPE_INT_BGR, TYPE_BYTE_BINARY, TYPE_BYTE_INDEXED, TYPE_USHORT_565_RGB, TYPE_USHORT_555_RGB, TYPE_CUSTOM

getColorModel

public ColorModel getColorModel()

Returns the ColorModel.

Returns:

the ColorModel of this BufferedImage.

getRGB

public int getRGB(int x,
                  int y)

Returns an integer pixel in the default RGB color model (TYPE_INT_ARGB) and default sRGB colorspace. Color conversion takes place if this default model does not match the image ColorModel. There are only 8-bits of precision for each color component in the returned data when using this method.

Returns:

an integer pixel in the default RGB color model and default sRGB colorspace.

See Also:

setRGB(int, int, int), setRGB(int, int, int, int, int[], int, int)

getRGB

public int[] getRGB(int startX,
                    int startY,
                    int w,
                    int h,
                    int[] rgbArray,
                    int offset,
                    int scansize)

Returns an array of integer pixels in the default RGB color model (TYPE_INT_ARGB) and default sRGB color space, from a portion of the image data. Color conversion takes place if the default model does not match the image ColorModel. There are only 8-bits of precision for each color component in the returned data when using this method. With a specified coordinate (x, y) in the image, the ARGB pixel can be accessed in this way:

    pixel   = rgbArray[offset + (y-startY)*scansize + (x-startX)];
 

Parameters:

w - width of region

h - height of region

rgbArray - if not null, the rgb pixels are written here

offset - offset into the rgbArray

scansize - scanline stride for the rgbArray

Returns:

array of RGB pixels.

Throws:

IllegalArgumentException - if an unknown datatype is specified

See Also:

setRGB(int, int, int), setRGB(int, int, int, int, int[], int, int)

setRGB

public void setRGB(int x,
                   int y,
                   int rgb)

Sets a pixel in this BufferedImage to the specified RGB value. The pixel is assumed to be in the default RGB color model, TYPE_INT_ARGB, and default sRGB color space. For images with an IndexColorModel, the index with the nearest color is chosen.

Parameters:

rgb - the RGB value

See Also:

getRGB(int, int), getRGB(int, int, int, int, int[], int, int)

setRGB

public void setRGB(int startX,
                   int startY,
                   int w,
                   int h,
                   int[] rgbArray,
                   int offset,
                   int scansize)

Sets an array of integer pixels in the default RGB color model (TYPE_INT_ARGB) and default sRGB color space, into a portion of the image data. Color conversion takes place if the default model does not match the image ColorModel. There are only 8-bits of precision for each color component in the returned data when using this method. With a specified coordinate (x, y) in the this image, the ARGB pixel can be accessed in this way:

    pixel   = rgbArray[offset + (y-startY)*scansize + (x-startX)];
 

WARNING: No dithering takes place.

Parameters:

w - width of the region

h - height of the region

rgbArray - the rgb pixels

offset - offset into the rgbArray

scansize - scanline stride for the rgbArray

See Also:

getRGB(int, int), getRGB(int, int, int, int, int[], int, int)

getWidth

public int getWidth()

Returns the width of the BufferedImage.

Returns:

the width of this BufferedImage

getHeight

public int getHeight()

Returns the height of the BufferedImage.

Returns:

the height of this BufferedImage

getWidth

public int getWidth(ImageObserver observer)

Returns the width of the BufferedImage.

Specified by:

getWidth in class Image

Parameters:

observer - ignored

Returns:

the width of this BufferedImage

See Also:

Image.getHeight(java.awt.image.ImageObserver), ImageObserver

getHeight

public int getHeight(ImageObserver observer)

Returns the height of the BufferedImage.

Specified by:

getHeight in class Image

Parameters:

observer - ignored

Returns:

the height of this BufferedImage

See Also:

Image.getWidth(java.awt.image.ImageObserver), ImageObserver

getSource

public ImageProducer getSource()

Returns the object that produces the pixels for the image.

Specified by:

getSource in class Image

Returns:

the ImageProducer that is used to produce the pixels for this image.

See Also:

ImageProducer

getProperty

public Object getProperty(String name,
                          ImageObserver observer)

Returns a property of the image by name. Individual property names are defined by the various image formats. If a property is not defined for a particular image, this method returns the UndefinedProperty field. If the properties for this image are not yet known, then this method returns null and the ImageObserver object is notified later. The property name "comment" should be used to store an optional comment that can be presented to the user as a description of the image, its source, or its author.

Specified by:

getProperty in class Image

Parameters:

name - the property name

observer - the ImageObserver that receives notification regarding image information

Returns:

an Object that is the property referred to by the specified name or null if the properties of this image are not yet known.

See Also:

ImageObserver, Image.UndefinedProperty

getProperty

public Object getProperty(String name)

Returns a property of the image by name.

Parameters:

name - the property name

Returns:

an Object that is the property referred to by the specified name.

flush

public void flush()

Flushes all resources being used to cache optimization information. The underlying pixel data is unaffected.

Specified by:

flush in class Image

getGraphics

public Graphics getGraphics()

This method returns a Graphics2D, but is here for backwards compatibility. createGraphics is more convenient, since it is declared to return a Graphics2D.

Specified by:

getGraphics in class Image

Returns:

a Graphics2D, which can be used to draw into this image.

See Also:

Graphics, Component.createImage(int, int)

createGraphics

public Graphics2D createGraphics()

Creates a Graphics2D, which can be used to draw into this BufferedImage.

Returns:

a Graphics2D, used for drawing into this image.

getSubimage

public BufferedImage getSubimage(int x,
                                 int y,
                                 int w,
                                 int h)

Returns a subimage defined by a specified rectangular region. The returned BufferedImage shares the same data array as the original image.

Parameters:

w - the width of the specified rectangular region

h - the height of the specified rectangular region

Returns:

a BufferedImage that is the subimage of this BufferedImage.

Throws:

RasterFormatException - if the specified area is not contained within this BufferedImage.

toString

public String toString()

Returns a String representation of this BufferedImage object and its values.

Overrides:

toString in class Object

Returns:

a String representing this BufferedImage.

getPropertyNames

public String[] getPropertyNames()

Returns an array of names recognized by getProperty(String) or null, if no property names are recognized.

Returns:

a String array containing all of the property names that getProperty(String) recognizes; or null if no property names are recognized.