Save This Page
Home » openjdk-7 » java » awt » image » [javadoc | source]
java.awt.image
public class: BufferedImage [javadoc | source] 
java.lang.Object
   java.awt.Image
      java.awt.image.BufferedImage

All Implemented Interfaces:
    Transparency, WritableRenderedImage

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.

This class relies on the data fetching and setting methods of Raster, and on the color characterization methods of ColorModel.

Field Summary
 int imageType     
 ColorModel colorModel     
 WritableRaster raster     
 OffScreenImageSource osis     
 Hashtable properties     
 boolean isAlphaPremultiplied     
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. 
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. When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
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. 
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. 
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 . When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
public static final  int TYPE_3BYTE_BGR    Represents an image with 8-bit RGB color components, corresponding to a Windows-style BGR color model) with the colors Blue, Green, and Red stored in 3 bytes. There is no alpha. The image has a ComponentColorModel. When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
public static final  int TYPE_4BYTE_ABGR    Represents an image with 8-bit RGBA color components with the colors Blue, Green, and Red stored in 3 bytes and 1 byte of alpha. The image has a ComponentColorModel with alpha. The color data in this image is considered not to be premultiplied with alpha. The byte data is interleaved in a single byte array in the order A, B, G, R from lower to higher byte addresses within each pixel. 
public static final  int TYPE_4BYTE_ABGR_PRE    Represents an image with 8-bit RGBA color components with the colors Blue, Green, and Red stored in 3 bytes and 1 byte of alpha. The image has a ComponentColorModel with alpha. The color data in this image is considered to be premultiplied with alpha. The byte data is interleaved in a single byte array in the order A, B, G, R from lower to higher byte addresses within each pixel. 
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. When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
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. When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
public static final  int TYPE_BYTE_GRAY    Represents a unsigned byte grayscale image, non-indexed. This image has a ComponentColorModel with a CS_GRAY ColorSpace . When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
public static final  int TYPE_USHORT_GRAY    Represents an unsigned short grayscale image, non-indexed). This image has a ComponentColorModel with a CS_GRAY ColorSpace. When data with non-opaque alpha is stored in an image of this type, the color data must be adjusted to a non-premultiplied form and the alpha discarded, as described in the java.awt.AlphaComposite documentation. 
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.

When color data is stored in an image of this type, the closest color in the colormap is determined by the IndexColorModel and the resulting index is stored. Approximation and loss of alpha or color components can result, depending on the colors in the IndexColorModel colormap. 

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.

When color data is stored in an image of this type, the closest color in the colormap is determined by the IndexColorModel and the resulting index is stored. Approximation and loss of alpha or color components can result, depending on the colors in the IndexColorModel colormap. 

Fields inherited from java.awt.Image:
accelerationPriority,  UndefinedProperty,  SCALE_DEFAULT,  SCALE_FAST,  SCALE_SMOOTH,  SCALE_REPLICATE,  SCALE_AREA_AVERAGING,  surfaceManager
Constructor:
 public BufferedImage(int width,
    int height,
    int imageType) 
 public BufferedImage(int width,
    int height,
    int imageType,
    IndexColorModel cm)
    Constructs a BufferedImage of one of the predefined image types: TYPE_BYTE_BINARY or TYPE_BYTE_INDEXED.

    If the image type is TYPE_BYTE_BINARY, the number of entries in the color model is used to determine whether the image should have 1, 2, or 4 bits per pixel. If the color model has 1 or 2 entries, the image will have 1 bit per pixel. If it has 3 or 4 entries, the image with have 2 bits per pixel. If it has between 5 and 16 entries, the image will have 4 bits per pixel. Otherwise, an IllegalArgumentException will be thrown.

    Parameters:
    width - width of the created image
    height - height of the created image
    imageType - type of the created image
    cm - IndexColorModel of the created image
    Throws:
    IllegalArgumentException - if the imageType is not TYPE_BYTE_BINARY or TYPE_BYTE_INDEXED or if the imageType is TYPE_BYTE_BINARY and the color map has more than 16 entries.
    Also see:
    TYPE_BYTE_BINARY
    TYPE_BYTE_INDEXED
 public BufferedImage(ColorModel cm,
    WritableRaster raster,
    boolean isRasterPremultiplied,
    Hashtable properties)
    Constructs a new BufferedImage with a specified ColorModel and Raster. If the number and types of bands in the SampleModel of the Raster do not match the number and types required by the ColorModel to represent its color and alpha components, a RasterFormatException is thrown. This method can multiply or divide the color Raster data by alpha to match the alphaPremultiplied state in the ColorModel. Properties for this BufferedImage can be established by passing in a Hashtable of String/Object pairs.
    Parameters:
    cm - ColorModel for the new image
    raster - Raster for the image data
    isRasterPremultiplied - if true, the data in the raster has been premultiplied with alpha.
    properties - Hashtable of String/Object pairs.
    Throws:
    < - code>RasterFormatException if the number and types of bands in the SampleModel of the Raster do not match the number and types required by the ColorModel to represent its color and alpha components.
    < - code>IllegalArgumentException if raster is incompatible with cm
    Also see:
    ColorModel
    Raster
    WritableRaster
    exception: < - code>RasterFormatException if the number and types of bands in the SampleModel of the Raster do not match the number and types required by the ColorModel to represent its color and alpha components.
    exception: < - code>IllegalArgumentException if raster is incompatible with cm
Method from java.awt.image.BufferedImage Summary:
addTileObserver,   coerceData,   copyData,   createGraphics,   getAlphaRaster,   getColorModel,   getData,   getData,   getGraphics,   getHeight,   getHeight,   getMinTileX,   getMinTileY,   getMinX,   getMinY,   getNumXTiles,   getNumYTiles,   getProperty,   getProperty,   getPropertyNames,   getRGB,   getRGB,   getRaster,   getSampleModel,   getSource,   getSources,   getSubimage,   getTile,   getTileGridXOffset,   getTileGridYOffset,   getTileHeight,   getTileWidth,   getTransparency,   getType,   getWidth,   getWidth,   getWritableTile,   getWritableTileIndices,   hasTileWriters,   isAlphaPremultiplied,   isTileWritable,   releaseWritableTile,   removeTileObserver,   setData,   setRGB,   setRGB,   toString
Methods from java.awt.Image:
flush,   getAccelerationPriority,   getCapabilities,   getGraphics,   getHeight,   getProperty,   getScaledInstance,   getSource,   getWidth,   setAccelerationPriority
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.awt.image.BufferedImage Detail:
 public  void addTileObserver(TileObserver to)
    Adds a tile observer. If the observer is already present, it receives multiple notifications.
 public  void coerceData(boolean isAlphaPremultiplied)
    Forces the data to match the state specified in the isAlphaPremultiplied variable. It may multiply or divide the color raster data by alpha, or do nothing if the data is in the correct state.
 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.
 public Graphics2D createGraphics()
    Creates a Graphics2D, which can be used to draw into this BufferedImage.
 public WritableRaster getAlphaRaster()
    Returns a WritableRaster representing the alpha channel for BufferedImage objects with ColorModel objects that support a separate spatial alpha channel, such as ComponentColorModel and DirectColorModel. Returns null if there is no alpha channel associated with the ColorModel in this image. This method assumes that for all ColorModel objects other than IndexColorModel, if the ColorModel supports alpha, there is a separate alpha channel which is stored as the last band of image data. If the image uses an IndexColorModel that has alpha in the lookup table, this method returns null since there is no spatially discrete alpha channel. This method creates a new WritableRaster, but shares the data array.
 public ColorModel getColorModel()
    Returns the ColorModel.
 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.
 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.
 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.
 public int getHeight()
    Returns the height of the BufferedImage.
 public int getHeight(ImageObserver observer)
    Returns the height of the BufferedImage.
 public int getMinTileX()
    Returns the minimum tile index in the x direction. This is always zero.
 public int getMinTileY()
    Returns the minimum tile index in the y direction. This is always zero.
 public int getMinX()
    Returns the minimum x coordinate of this BufferedImage. This is always zero.
 public int getMinY()
    Returns the minimum y coordinate of this BufferedImage. This is always zero.
 public int getNumXTiles()
    Returns the number of tiles in the x direction. This is always one.
 public int getNumYTiles()
    Returns the number of tiles in the y direction. This is always one.
 public Object getProperty(String name)
    Returns a property of the image by name.
 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.
 public String[] getPropertyNames()
    Returns an array of names recognized by getProperty(String) or null, if no property names are recognized.
 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.

    An ArrayOutOfBoundsException may be thrown if the coordinates are not in bounds. However, explicit bounds checking is not guaranteed.

 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)];

    An ArrayOutOfBoundsException may be thrown if the region is not in bounds. However, explicit bounds checking is not guaranteed.

 public WritableRaster getRaster() 
 public SampleModel getSampleModel()
    Returns the SampleModel associated with this BufferedImage.
 public ImageProducer getSource()
    Returns the object that produces the pixels for the image.
 public 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.
 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.
 public Raster getTile(int tileX,
    int tileY)
    Returns tile (tileX, tileY). Note that tileX and tileY are indices into the tile array, not pixel locations. The Raster that is returned is live, which means that it is updated if the image is changed.
 public int getTileGridXOffset()
    Returns the x offset of the tile grid relative to the origin, For example, the x coordinate of the location of tile (0, 0). This is always zero.
 public int getTileGridYOffset()
    Returns the y offset of the tile grid relative to the origin, For example, the y coordinate of the location of tile (0, 0). This is always zero.
 public int getTileHeight()
    Returns the tile height in pixels.
 public int getTileWidth()
    Returns the tile width in pixels.
 public int getTransparency()
    Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT.
 public int getType()
    Returns the image type. If it is not one of the known types, TYPE_CUSTOM is returned.
 public int getWidth()
    Returns the width of the BufferedImage.
 public int getWidth(ImageObserver observer)
    Returns the width of the BufferedImage.
 public WritableRaster getWritableTile(int tileX,
    int tileY)
    Checks out a tile for writing. All registered TileObservers are notified when a tile goes from having no writers to having one writer.
 public Point[] getWritableTileIndices()
    Returns an array of Point objects indicating which tiles are checked out for writing. Returns null if none are checked out.
 public boolean hasTileWriters()
    Returns whether or not any tile is checked out for writing. Semantically equivalent to 
    (getWritableTileIndices() != null).

 public boolean isAlphaPremultiplied()
    Returns whether or not the alpha has been premultiplied. It returns false if there is no alpha.
 public boolean isTileWritable(int tileX,
    int tileY)
    Returns whether or not a tile is currently checked out for writing.
 public  void releaseWritableTile(int tileX,
    int tileY)
    Relinquishes permission to write to a tile. If the caller continues to write to the tile, the results are undefined. Calls to this method should only appear in matching pairs with calls to getWritableTile(int, int) . Any other leads to undefined results. All registered TileObservers are notified when a tile goes from having one writer to having no writers.
 public  void removeTileObserver(TileObserver to)
    Removes a tile observer. If the observer was not registered, nothing happens. If the observer was registered for multiple notifications, it is now registered for one fewer notification.
 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.
 public synchronized  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.

    An ArrayOutOfBoundsException may be thrown if the coordinates are not in bounds. However, explicit bounds checking is not guaranteed.

 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.

    An ArrayOutOfBoundsException may be thrown if the region is not in bounds. However, explicit bounds checking is not guaranteed.

 public String toString()
    Returns a String representation of this BufferedImage object and its values.