public final class BufferedImage
extends java.awt.Image
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
.
ColorModel
,
Raster
,
WritableRaster
Modifier and Type | Field and Description |
---|---|
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.
|
Modifier and Type | Method and Description |
---|---|
java.awt.Graphics2D |
createGraphics()
Creates a
Graphics2D , which can be used to draw into
this BufferedImage . |
void |
flush() |
ColorModel |
getColorModel()
Returns the
ColorModel . |
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(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 width,
int height,
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.
|
public static final int TYPE_CUSTOM
public static final int TYPE_INT_RGB
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
AlphaComposite
documentation.public static final int TYPE_INT_ARGB
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
DirectColorModel
with alpha. The color data in this image is considered to be
premultiplied with alpha.public static final int TYPE_INT_BGR
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
AlphaComposite
documentation.public static final int TYPE_USHORT_565_RGB
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
AlphaComposite
documentation.public static final int TYPE_USHORT_555_RGB
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
AlphaComposite
documentation.public static final int TYPE_BYTE_BINARY
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
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.
public int getType()
BufferedImage
.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
public ColorModel getColorModel()
ColorModel
.ColorModel
of this
BufferedImage
.public int getRGB(int x, int y)
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.
x
- the X coordinate of the pixel from which to get
the pixel in the default RGB color model and sRGB
color spacey
- the Y coordinate of the pixel from which to get
the pixel in the default RGB color model and sRGB
color spacesetRGB(int, int, int)
,
setRGB(int, int, int, int, int[], int, int)
public int[] getRGB(int startX, int startY, int width, int height, int[] rgbArray, int offset, int scansize)
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.
startX
- the starting X coordinatestartY
- the starting Y coordinatew
- width of regionh
- height of regionrgbArray
- if not null
, the rgb pixels are
written hereoffset
- offset into the rgbArray
scansize
- scanline stride for the rgbArray
setRGB(int, int, int)
,
setRGB(int, int, int, int, int[], int, int)
public void setRGB(int x, int y, int rgb)
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.
x
- the X coordinate of the pixel to sety
- the Y coordinate of the pixel to setrgb
- the RGB valuegetRGB(int, int)
,
getRGB(int, int, int, int, int[], int, int)
public void setRGB(int startX, int startY, int w, int h, int[] rgbArray, int offset, int scansize)
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.
startX
- the starting X coordinatestartY
- the starting Y coordinatew
- width of the regionh
- height of the regionrgbArray
- the rgb pixelsoffset
- offset into the rgbArray
scansize
- scanline stride for the rgbArray
getRGB(int, int)
,
getRGB(int, int, int, int, int[], int, int)
public int getWidth()
BufferedImage
.BufferedImage
public int getHeight()
BufferedImage
.BufferedImage
public int getWidth(ImageObserver observer)
BufferedImage
.getWidth
in class java.awt.Image
observer
- ignoredBufferedImage
public int getHeight(ImageObserver observer)
BufferedImage
.getHeight
in class java.awt.Image
observer
- ignoredBufferedImage
public ImageProducer getSource()
getSource
in class java.awt.Image
ImageProducer
that is used to produce the
pixels for this image.ImageProducer
public Object getProperty(String name, ImageObserver observer)
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.getProperty
in class java.awt.Image
name
- the property nameobserver
- the ImageObserver
that receives
notification regarding image informationObject
that is the property referred to by the
specified name
or null
if the
properties of this image are not yet known.NullPointerException
- if the property name is null.ImageObserver
,
Image.UndefinedProperty
public Object getProperty(String name)
name
- the property nameObject
that is the property referred to by
the specified name
.NullPointerException
- if the property name is null.public java.awt.Graphics getGraphics()
Graphics2D
, but is here
for backwards compatibility. createGraphics
is more
convenient, since it is declared to return a
Graphics2D
.getGraphics
in class java.awt.Image
Graphics2D
, which can be used to draw into
this image.public java.awt.Graphics2D createGraphics()
Graphics2D
, which can be used to draw into
this BufferedImage
.Graphics2D
, used for drawing into this
image.public BufferedImage getSubimage(int x, int y, int w, int h)
BufferedImage
shares the same
data array as the original image.x
- the X coordinate of the upper-left corner of the
specified rectangular regiony
- the Y coordinate of the upper-left corner of the
specified rectangular regionw
- the width of the specified rectangular regionh
- the height of the specified rectangular regionBufferedImage
that is the subimage of this
BufferedImage
.RasterFormatException
- if the specified
area is not contained within this BufferedImage
.public String[] getPropertyNames()
getProperty(String)
or null
, if no property names are recognized.String
array containing all of the property
names that getProperty(String)
recognizes;
or null
if no property names are recognized.public void flush()
flush
in class java.awt.Image