BufferedImage (Advanced Graphics and User Interface (AGUI) Optional Package for Java Platform, Micro Edition, revision 060829)

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.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

JSR-209 (Final Approval Ballot)

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

java.awt.image
Class BufferedImage

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

All Implemented Interfaces:: RenderedImage

public class BufferedImage
extends java.awt.Image
implements RenderedImage

The BufferedImage subclass describes an Image with an accessible buffer of image data. A BufferedImage is comprised of a ColorModel and a Raster of image data. The number and types of bands in the SampleModel of the Raster must match the number and types required by the ColorModel to represent its color and alpha components. All BufferedImage objects have an upper left corner coordinate of (0, 0). Any Raster used to construct a BufferedImage must therefore have minX=0 and minY=0.

Restrictions

Implemenations of BufferedImage in this optional package exhibit certain restrictions, specifically:
For the BufferedImage constructor, the only valid imageType in AGUI implementations is TYPE_INT_ARGB_PRE. Specifying an imageType other than TYPE_INT_ARGB_PRE will result in an IllegalArgumentException. Note, however, that the AGUI implementation may create instances of BufferedImage with additional values of imageType; these instances may be returned to the application through other methdods. See:

BufferedImage(int, int, int)

See Also:: ColorModel, Raster, WritableRaster

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

Constructor Summary
`BufferedImage(int width, int height, int imageType)` Constructs a `BufferedImage` of one of the predefined image types.

Method Summary
`WritableRaster`	`copyData(WritableRaster outRaster)` Computes an arbitrary rectangular region of the `BufferedImage` and copies it into a specified `WritableRaster`.
`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.
`java.awt.image.ColorModel`	`getColorModel()` Returns the `ColorModel`.
`Raster`	`getData()` Returns the image as one large tile.
`Raster`	`getData(Rectangle rect)` Computes and returns an arbitrary region of the `BufferedImage`.
`java.awt.Graphics`	`getGraphics()` This method returns a `Graphics2D`, but is here for backwards compatibility.
`int`	`getHeight()` Returns the height of the `BufferedImage`.
`int`	`getHeight(java.awt.image.ImageObserver observer)` Returns the height of the `BufferedImage`.
`int`	`getMinX()` Returns the minimum x coordinate of this `BufferedImage`.
`int`	`getMinY()` Returns the minimum y coordinate of this `BufferedImage`.
`java.lang.Object`	`getProperty(java.lang.String name)` Returns a property of the image by name.
`java.lang.Object`	`getProperty(java.lang.String name, java.awt.image.ImageObserver observer)` Returns a property of the image by name.
`java.lang.String[]`	`getPropertyNames()` Returns an array of names recognized by `getProperty(String)` or `null`, if no property names are recognized.
`WritableRaster`	`getRaster()` Returns the `WritableRaster`.
`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.
`SampleModel`	`getSampleModel()` Returns the `SampleModel` associated with this `BufferedImage`.
`java.awt.image.ImageProducer`	`getSource()` Returns the object that produces the pixels for the image.
`java.util.Vector`	`getSources()` Returns a `Vector` of `RenderedImage` objects that are the immediate sources, not the sources of these immediate sources, of image data for this `BufferedImage`.
`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(java.awt.image.ImageObserver observer)` Returns the width of the `BufferedImage`.
`void`	`setData(Raster r)` Sets a rectangular region of the image to the contents of the specified `Raster` `r`, which is assumed to be in the same coordinate space as 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.
`java.lang.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. When this type is used as the imageType argument to a BufferedImage constructor, the created image is consistent with images created in the JDK1.1 and earlier releases.

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. When this type is used as the imageType argument to the BufferedImage constructor that takes an imageType argument but no ColorModel argument, a 1-bit image is created with an IndexColorModel with two colors in the default sRGB ColorSpace: {0, 0, 0} and {255, 255, 255}.

Images with 2 or 4 bits per pixel may be constructed via the BufferedImage constructor that takes a ColorModel argument by supplying a ColorModel with an appropriate map size.

Images with 8 bits per pixel should use the image types TYPE_BYTE_INDEXED or TYPE_BYTE_GRAY depending on their ColorModel.

See Also:: Constant Field Values

TYPE_BYTE_INDEXED

public static final int TYPE_BYTE_INDEXED

Represents an indexed byte image. When this type is used as the imageType argument to the BufferedImage constructor that takes an imageType argument but no ColorModel argument, an IndexColorModel is created with a 256-color 6/6/6 color cube palette with the rest of the colors from 216-255 populated by grayscale values in the default sRGB ColorSpace.

See Also:: Constant Field Values

Constructor Detail

BufferedImage

public BufferedImage(int width,
                     int height,
                     int imageType)

Constructs a BufferedImage of one of the predefined image types. The ColorSpace for the image is the default sRGB space.

Note:

Implementations of this constructor in AGUI only allow the creation of BufferedImage objects of type TYPE_INT_ARGB_PRE.

Parameters:

width - width of the created image

height - height of the created image

imageType - type of the created image

Throws:

java.lang.IllegalArgumentException - if imageType is not TYPE_INT_ARGB_PRE

See Also:

ColorSpace, TYPE_INT_RGB, TYPE_INT_ARGB, TYPE_INT_ARGB_PRE, TYPE_INT_BGR, #TYPE_3BYTE_BGR, #TYPE_4BYTE_ABGR, #TYPE_4BYTE_ABGR_PRE, #TYPE_BYTE_GRAY, #TYPE_USHORT_GRAY, TYPE_BYTE_BINARY, TYPE_BYTE_INDEXED, TYPE_USHORT_565_RGB, TYPE_USHORT_555_RGB

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_3BYTE_BGR, #TYPE_4BYTE_ABGR, #TYPE_4BYTE_ABGR_PRE, #TYPE_BYTE_GRAY, TYPE_BYTE_BINARY, TYPE_BYTE_INDEXED, #TYPE_USHORT_GRAY, TYPE_USHORT_565_RGB, TYPE_USHORT_555_RGB, TYPE_CUSTOM

getColorModel

public java.awt.image.ColorModel getColorModel()

Returns the ColorModel.

Specified by:: getColorModel in interface RenderedImage

Returns:: the ColorModel of this BufferedImage.

getRaster

public WritableRaster getRaster()

Returns the WritableRaster.

Returns:: the WriteableRaster 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.

Specified by:: getWidth in interface RenderedImage

Returns:: the width of this BufferedImage

getHeight

public int getHeight()

Returns the height of the BufferedImage.

Specified by:: getHeight in interface RenderedImage

Returns:: the height of this BufferedImage

getWidth

public int getWidth(java.awt.image.ImageObserver observer)

Returns the width of the BufferedImage.

Parameters:: observer - ignored
Returns:: the width of this BufferedImage

getHeight

public int getHeight(java.awt.image.ImageObserver observer)

Returns the height of the BufferedImage.

Parameters:: observer - ignored
Returns:: the height of this BufferedImage

getSource

public java.awt.image.ImageProducer getSource()

Returns the object that produces the pixels for the image.

Returns:: the ImageProducer that is used to produce the pixels for this image.
See Also:: ImageProducer

getProperty

public java.lang.Object getProperty(java.lang.String name,
                                    java.awt.image.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.

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 java.lang.Object getProperty(java.lang.String name)

Returns a property of the image by name.

Specified by:: getProperty in interface RenderedImage

Parameters:: name - the property name
Returns:: an Object that is the property referred to by the specified name.
See Also:: Image.UndefinedProperty

flush

public void flush()

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

getGraphics

public java.awt.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.

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

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 java.lang.String toString()

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

Returns:: a String representing this BufferedImage.

getSources

public java.util.Vector getSources()

Returns a Vector of RenderedImage objects that are the immediate sources, not the sources of these immediate sources, of image data for this BufferedImage. This method returns null if the BufferedImage has no information about its immediate sources. It returns an empty Vector if the BufferedImage has no immediate sources.

Specified by:: getSources in interface RenderedImage

Returns:: a Vector containing immediate sources of this BufferedImage object's image date, or null if this BufferedImage has no information about its immediate sources, or an empty Vector if this BufferedImage has no immediate sources.

getPropertyNames

public java.lang.String[] getPropertyNames()

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

Specified by:: getPropertyNames in interface RenderedImage

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

getMinX

public int getMinX()

Returns the minimum x coordinate of this BufferedImage. This is always zero.

Specified by:: getMinX in interface RenderedImage

Returns:: the minimum x coordinate of this BufferedImage.

getMinY

public int getMinY()

Returns the minimum y coordinate of this BufferedImage. This is always zero.

Specified by:: getMinY in interface RenderedImage

Returns:: the minimum y coordinate of this BufferedImage.

getSampleModel

public SampleModel getSampleModel()

Returns the SampleModel associated with this BufferedImage.

Specified by:: getSampleModel in interface RenderedImage

Returns:: the SampleModel of this BufferedImage.

getData

public Raster getData()

Returns the image as one large tile. The Raster returned is a copy of the image data is not updated if the image is changed.

Specified by:: getData in interface RenderedImage

Returns:: a Raster that is a copy of the image data.
See Also:: setData(Raster)

getData

public Raster getData(Rectangle rect)

Computes and returns an arbitrary region of the BufferedImage. The Raster returned is a copy of the image data and is not updated if the image is changed.

Specified by:: getData in interface RenderedImage

Parameters:: rect - the region of the BufferedImage to be returned.
Returns:: a Raster that is a copy of the image data of the specified region of the BufferedImage
See Also:: setData(Raster)

copyData

public WritableRaster copyData(WritableRaster outRaster)

Computes an arbitrary rectangular region of the BufferedImage and copies it into a specified WritableRaster. The region to be computed is determined from the bounds of the specified WritableRaster. The specified WritableRaster must have a SampleModel that is compatible with this image. If outRaster is null, an appropriate WritableRaster is created.

Specified by:: copyData in interface RenderedImage

Parameters:: outRaster - a WritableRaster to hold the returned part of the image, or null
Returns:: a reference to the supplied or created WritableRaster.

setData

public void setData(Raster r)

Sets a rectangular region of the image to the contents of the specified Raster r, which is assumed to be in the same coordinate space as the BufferedImage. The operation is clipped to the bounds of the BufferedImage.

Parameters:: r - the specified Raster
See Also:: getData(), getData(Rectangle)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

JSR-209 (Final Approval Ballot)

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006 Sun Microsystems, Inc. All rights reserved. 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.

For more information, please consult the JSR 209 specification.

java.awt.image Class BufferedImage

Restrictions

TYPE_CUSTOM

TYPE_INT_RGB

TYPE_INT_ARGB

TYPE_INT_ARGB_PRE

TYPE_INT_BGR

TYPE_USHORT_565_RGB

TYPE_USHORT_555_RGB

TYPE_BYTE_BINARY

TYPE_BYTE_INDEXED

BufferedImage

getType

getColorModel

getRaster

getRGB

getRGB

setRGB

setRGB

getWidth

getHeight

getWidth

getHeight

getSource

getProperty

getProperty

flush

getGraphics

createGraphics

getSubimage

toString

getSources

getPropertyNames

getMinX

getMinY

getSampleModel

getData

getData

copyData

setData

java.awt.image
Class BufferedImage