java.awt.image
Class BufferedImage
- public class BufferedImage
- extends Image
- implements WritableRenderedImage
- The
BufferedImage
subclass describes an {@link Image} with an accessible buffer of image data. A BufferedImage
is comprised of a {@link ColorModel} and a {@link Raster} of image data. The number and types of bands in the {@link 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.
- Version:
- 10 Feb 1997
- See Also:
- ColorModel
- Raster
- WritableRaster
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.
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 {@link DirectColorModel} without alpha.
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.
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.
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 {@link ComponentColorModel}.
TYPE_3BYTE_BGR
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
.
TYPE_4BYTE_ABGR
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.
TYPE_4BYTE_ABGR_PRE
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.
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
.
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
.
TYPE_BYTE_GRAY
public static final int TYPE_BYTE_GRAY
- Represents a unsigned byte grayscale image, non-indexed. This image has a
ComponentColorModel
with a CS_GRAY {@link ColorSpace}.
TYPE_USHORT_GRAY
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
.
TYPE_BYTE_BINARY
public static final int TYPE_BYTE_BINARY
- Represents an opaque byte-packed binary image. The image has an {@link 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, an IndexColorModel
is created with two colors in the default sRGB ColorSpace
: {0, 0, 0} and {255, 255, 255}.
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.
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.
- Parameters:
width
- width of the created image
height
- height of the created image
imageType
- type of the created image
- 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
BufferedImage
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
- 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
- See Also:
- #TYPE_BYTE_BINARY
- #TYPE_BYTE_INDEXED
BufferedImage
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 {@link 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 {@link Hashtable} of String
/Object
pairs.
- Parameters:
ColorModel
- 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:
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.
IllegalArgumentException
- if raster
is incompatible with cm
- See Also:
- ColorModel
- Raster
- WritableRaster
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 ColorModel getColorModel()
- Returns the
ColorModel
.
- Returns:
- the
ColorModel
of this BufferedImage
.
getRaster
public WritableRaster getRaster()
- Returns the {@link WritableRaster}.
- Returns:
- the
WriteableRaster
of this BufferedImage
.
getAlphaRaster
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.
- Returns:
- a
WritableRaster
or null
if this BufferedImage
has no alpha channel associated with its ColorModel
.
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.
- Parameters:
x, y
- the coordinates of the pixel from which to get the pixel in the default RGB color model and sRGB color space
- Returns:
- an integer pixel in the default RGB color model and default sRGB colorspace.
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:
startX,
- startY the starting coordinates
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
setRGB
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.
- Parameters:
x, y
- the coordinates of the pixel to set
rgb
- the RGB value
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:
startX, startY
- the starting coordinates
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
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 actual width of the image. If the width is not known yet then the {@link ImageObserver} is notified later and
-1
is returned.
- Parameters:
observer
- the ImageObserver
that receives information about the image
- Returns:
- the width of the image or
-1
if the width is not yet known.
- See Also:
- java.awt.Image#getHeight(ImageObserver)
- ImageObserver
getHeight
public int getHeight(ImageObserver observer)
- Returns the actual height of the image. If the height is not known yet then the
ImageObserver
is notified later and -1
is returned.
- Parameters:
observer
- the ImageObserver
that receives information about the image
- Returns:
- the height of the image or
-1
if the height is not yet known.
- See Also:
- java.awt.Image#getWidth(ImageObserver)
- ImageObserver
getSource
public ImageProducer getSource()
- Returns the object that produces the pixels for the image.
- Returns:
- the {@link 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.
- Parameters:
name
- the property name
observer
- the ImageObserver
that receives notification regarding image information
- Returns:
- an {@link 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
- java.awt.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.
getGraphics
public Graphics getGraphics()
- This method returns a {@link Graphics2D}, but is here for backwards compatibility. {@link #createGraphics() 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:
x, y
- the coordinates of the upper-left corner of the specified rectangular region
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
.
isAlphaPremultiplied
public boolean isAlphaPremultiplied()
- Returns whether or not the alpha has been premultiplied. It returns
true
if there is no alpha since the default alpha is OPAQUE.
- Returns:
true
if the alpha has been premultiplied; false
otherwise.
coerceData
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.
- Parameters:
isAlphaPremultiplied
- true
if the alpha has been premultiplied; false
otherwise.
toString
public String toString()
- Returns a
String
representation of this BufferedImage
object and its values.
- Returns:
- a
String
representing this BufferedImage
.
getSources
public Vector getSources()
- Returns a {@link Vector} of {@link 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.
- 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 String[] getPropertyNames()
- Returns an array of names recognized by {@link #getProperty(String) 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.
getMinX
public int getMinX()
- Returns the minimum x coordinate of this
BufferedImage
. This is always zero.
- Returns:
- the minimum x coordinate of this
BufferedImage
.
getMinY
public int getMinY()
- Returns the minimum y coordinate of this
BufferedImage
. This is always zero.
- Returns:
- the minimum y coordinate of this
BufferedImage
.
getSampleModel
public SampleModel getSampleModel()
- Returns the
SampleModel
associated with this BufferedImage
.
- Returns:
- the
SampleModel
of this BufferedImage
.
getNumXTiles
public int getNumXTiles()
- Returns the number of tiles in the x direction. This is always one.
- Returns:
- the number of tiles in the x direction.
getNumYTiles
public int getNumYTiles()
- Returns the number of tiles in the y direction. This is always one.
- Returns:
- the number of tiles in the y direction.
getMinTileX
public int getMinTileX()
- Returns the minimum tile index in the x direction. This is always zero.
- Returns:
- the minimum tile index in the x direction.
getMinTileY
public int getMinTileY()
- Returns the minimum tile index in the y direction. This is always zero.
- Returns:
- the mininum tile index in the y direction.
getTileWidth
public int getTileWidth()
- Returns the tile width in pixels.
- Returns:
- the tile width in pixels.
getTileHeight
public int getTileHeight()
- Returns the tile height in pixels.
- Returns:
- the tile height in pixels.
getTileGridXOffset
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.
- Returns:
- the x offset of the tile grid.
getTileGridYOffset
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.
- Returns:
- the y offset of the tile grid.
getTile
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.
- Parameters:
tileX
- the x index of the requested tile in the tile array
tileY
- the y index of the requested tile in the tile array
- Returns:
- a
Raster
that is the tile defined by the arguments tileX
and tileY
.
- Throws:
ArrayIndexOutOfBoundsException
- if both tileX
and tileY
are not equal to 0
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.
- Returns:
- a
Raster
that is a copy of the image data.
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.
- 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
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.
- 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
addTileObserver
public void addTileObserver(TileObserver to)
- Adds a tile observer. If the observer is already present, it receives multiple notifications.
- Parameters:
to
- the specified {@link TileObserver}
removeTileObserver
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.
- Parameters:
to
- the specified TileObserver
.
isTileWritable
public boolean isTileWritable(int tileX,
int tileY)
- Returns whether or not a tile is currently checked out for writing.
- Parameters:
tileX
- the x index of the tile.
tileY
- the y index of the tile.
- Returns:
true
if the tile specified by the specified indices is checked out for writing; false
otherwise.
- Throws:
ArrayIndexOutOfBoundsException
- if both tileX
and tileY
are not equal to 0
getWritableTileIndices
public Point[] getWritableTileIndices()
- Returns an array of {@link Point} objects indicating which tiles are checked out for writing. Returns
null
if none are checked out.
- Returns:
- a
Point
array that indicates the tiles that are checked out for writing, or null
if no tiles are checked out for writing.
hasTileWriters
public boolean hasTileWriters()
- Returns whether or not any tile is checked out for writing. Semantically equivalent to
(getWritableTileIndices() != null).
- Returns:
true
if any tile is checked out for writing; false
otherwise.
getWritableTile
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.
- Parameters:
tileX
- the x index of the tile
tileY
- the y index of the tile
- Returns:
- a
WritableRaster
that is the tile, indicated by the specified indices, to be checked out for writing.
releaseWritableTile
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 {@link #getWritableTile(int, int) 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.
- Parameters:
tileX
- the x index of the tile
tileY
- the y index of the tile