public class GraphicsUtilities extends Object
GraphicsUtilities
contains a set of tools to perform
common graphics operations easily. These operations are divided into
several themes, listed below.
Compatible images can, and should, be used to increase drawing performance. This class provides a number of methods to load compatible images directly from files or to convert existing images to compatibles images.
This class provides a number of methods to easily scale down images. Some of these methods offer a trade-off between speed and result quality and should be used all the time. They also offer the advantage of producing compatible images, thus automatically resulting into better runtime performance.
All these methods are both faster than
Image.getScaledInstance(int, int, int)
and produce
better-looking results than the various drawImage()
methods
in Graphics
, which can be used for image scaling.
This class provides two methods to get and set pixels in a buffered image. These methods try to avoid unmanaging the image in order to keep good performance.
Modifier | Constructor and Description |
---|---|
private |
GraphicsUtilities() |
Modifier and Type | Method and Description |
---|---|
static void |
clear(Image img)
Clears the data from the image.
|
static BufferedImage |
convertToBufferedImage(Image img)
Converts the specified image into a compatible buffered image.
|
static BufferedImage |
createColorModelCompatibleImage(BufferedImage image)
Returns a new
BufferedImage using the same color model
as the image passed as a parameter. |
static BufferedImage |
createCompatibleImage(BufferedImage image)
Returns a new compatible image with the same width, height and
transparency as the image specified as a parameter.
|
static BufferedImage |
createCompatibleImage(BufferedImage image,
int width,
int height)
Returns a new compatible image of the specified width and height, and
the same transparency setting as the image specified as a parameter.
|
static BufferedImage |
createCompatibleImage(int width,
int height)
Returns a new opaque compatible image of the specified width and
height.
|
static BufferedImage |
createCompatibleTranslucentImage(int width,
int height)
Returns a new translucent compatible image of the specified width and
height.
|
static BufferedImage |
createThumbnail(BufferedImage image,
int newSize)
Returns a thumbnail of a source image.
|
static BufferedImage |
createThumbnail(BufferedImage image,
int newWidth,
int newHeight)
Returns a thumbnail of a source image.
|
static BufferedImage |
createThumbnailFast(BufferedImage image,
int newSize)
Returns a thumbnail of a source image.
|
static BufferedImage |
createThumbnailFast(BufferedImage image,
int newWidth,
int newHeight)
Returns a thumbnail of a source image.
|
private static GraphicsConfiguration |
getGraphicsConfiguration() |
static int[] |
getPixels(BufferedImage img,
int x,
int y,
int w,
int h,
int[] pixels)
Returns an array of pixels, stored as integers, from a
BufferedImage . |
private static boolean |
isHeadless() |
static BufferedImage |
loadCompatibleImage(InputStream in)
Returns a new compatible image from a stream.
|
static BufferedImage |
loadCompatibleImage(URL resource)
Returns a new compatible image from a URL.
|
static void |
setPixels(BufferedImage img,
int x,
int y,
int w,
int h,
int[] pixels)
Writes a rectangular area of pixels in the destination
BufferedImage . |
static void |
tileStretchPaint(Graphics g,
JComponent comp,
BufferedImage img,
Insets ins)
Draws an image on top of a component by doing a 3x3 grid stretch of the image
using the specified insets.
|
static BufferedImage |
toCompatibleImage(BufferedImage image)
Return a new compatible image that contains a copy of the specified
image.
|
private GraphicsUtilities()
private static GraphicsConfiguration getGraphicsConfiguration()
private static boolean isHeadless()
public static BufferedImage convertToBufferedImage(Image img)
img
- the image to convertpublic static BufferedImage createColorModelCompatibleImage(BufferedImage image)
Returns a new BufferedImage
using the same color model
as the image passed as a parameter. The returned image is only compatible
with the image passed as a parameter. This does not mean the returned
image is compatible with the hardware.
image
- the reference image from which the color model of the new
image is obtainedBufferedImage
, compatible with the color model
of image
public static BufferedImage createCompatibleImage(BufferedImage image)
Returns a new compatible image with the same width, height and transparency as the image specified as a parameter. That is, the returned BufferedImage will be compatible with the graphics hardware. If this method is called in a headless environment, then the returned BufferedImage will be compatible with the source image.
image
- the reference image from which the dimension and the
transparency of the new image are obtainedBufferedImage
with the same
dimension and transparency as image
Transparency
,
createCompatibleImage(int, int)
,
createCompatibleImage(java.awt.image.BufferedImage, int, int)
,
createCompatibleTranslucentImage(int, int)
,
loadCompatibleImage(java.net.URL)
,
toCompatibleImage(java.awt.image.BufferedImage)
public static BufferedImage createCompatibleImage(BufferedImage image, int width, int height)
Returns a new compatible image of the specified width and height, and
the same transparency setting as the image specified as a parameter.
That is, the returned BufferedImage
is compatible with
the graphics hardware. If the method is called in a headless
environment, then the returned BufferedImage will be compatible with
the source image.
width
- the width of the new imageheight
- the height of the new imageimage
- the reference image from which the transparency of the new
image is obtainedBufferedImage
with the same
transparency as image
and the specified dimensionTransparency
,
createCompatibleImage(java.awt.image.BufferedImage)
,
createCompatibleImage(int, int)
,
createCompatibleTranslucentImage(int, int)
,
loadCompatibleImage(java.net.URL)
,
toCompatibleImage(java.awt.image.BufferedImage)
public static BufferedImage createCompatibleImage(int width, int height)
Returns a new opaque compatible image of the specified width and
height. That is, the returned BufferedImage
is compatible with
the graphics hardware. If the method is called in a headless
environment, then the returned BufferedImage will be compatible with
the source image.
width
- the width of the new imageheight
- the height of the new imageBufferedImage
of the
specified width and heightcreateCompatibleImage(java.awt.image.BufferedImage)
,
createCompatibleImage(java.awt.image.BufferedImage, int, int)
,
createCompatibleTranslucentImage(int, int)
,
loadCompatibleImage(java.net.URL)
,
toCompatibleImage(java.awt.image.BufferedImage)
public static BufferedImage createCompatibleTranslucentImage(int width, int height)
Returns a new translucent compatible image of the specified width and
height. That is, the returned BufferedImage
is compatible with
the graphics hardware. If the method is called in a headless
environment, then the returned BufferedImage will be compatible with
the source image.
width
- the width of the new imageheight
- the height of the new imageBufferedImage
of the
specified width and heightcreateCompatibleImage(java.awt.image.BufferedImage)
,
createCompatibleImage(java.awt.image.BufferedImage, int, int)
,
createCompatibleImage(int, int)
,
loadCompatibleImage(java.net.URL)
,
toCompatibleImage(java.awt.image.BufferedImage)
public static BufferedImage loadCompatibleImage(InputStream in) throws IOException
Returns a new compatible image from a stream. The image is loaded from the specified stream and then turned, if necessary into a compatible image.
in
- the stream of the picture to load as a compatible imageBufferedImage
of the
specified width and heightIOException
- if the image cannot be read or loadedcreateCompatibleImage(java.awt.image.BufferedImage)
,
createCompatibleImage(java.awt.image.BufferedImage, int, int)
,
createCompatibleImage(int, int)
,
createCompatibleTranslucentImage(int, int)
,
toCompatibleImage(java.awt.image.BufferedImage)
public static BufferedImage loadCompatibleImage(URL resource) throws IOException
Returns a new compatible image from a URL. The image is loaded from the specified location and then turned, if necessary into a compatible image.
resource
- the URL of the picture to load as a compatible imageBufferedImage
of the
specified width and heightIOException
- if the image cannot be read or loadedcreateCompatibleImage(java.awt.image.BufferedImage)
,
createCompatibleImage(java.awt.image.BufferedImage, int, int)
,
createCompatibleImage(int, int)
,
createCompatibleTranslucentImage(int, int)
,
toCompatibleImage(java.awt.image.BufferedImage)
public static BufferedImage toCompatibleImage(BufferedImage image)
Return a new compatible image that contains a copy of the specified image. This method ensures an image is compatible with the hardware, and therefore optimized for fast blitting operations.
If the method is called in a headless environment, then the returned
BufferedImage
will be the source image.
image
- the image to copy into a new compatible imageimage
createCompatibleImage(java.awt.image.BufferedImage)
,
createCompatibleImage(java.awt.image.BufferedImage, int, int)
,
createCompatibleImage(int, int)
,
createCompatibleTranslucentImage(int, int)
,
loadCompatibleImage(java.net.URL)
public static BufferedImage createThumbnailFast(BufferedImage image, int newSize)
Returns a thumbnail of a source image. newSize
defines
the length of the longest dimension of the thumbnail. The other
dimension is then computed according to the dimensions ratio of the
original picture.
This method favors speed over quality. When the new size is less than
half the longest dimension of the source image,
createThumbnail(BufferedImage, int)
or
createThumbnail(BufferedImage, int, int)
should be used instead
to ensure the quality of the result without sacrificing too much
performance.
image
- the source imagenewSize
- the length of the largest dimension of the thumbnailBufferedImage
containing a
thumbnail of image
IllegalArgumentException
- if newSize
is larger than
the largest dimension of image
or <= 0createThumbnailFast(java.awt.image.BufferedImage, int, int)
,
createThumbnail(java.awt.image.BufferedImage, int)
,
createThumbnail(java.awt.image.BufferedImage, int, int)
public static BufferedImage createThumbnailFast(BufferedImage image, int newWidth, int newHeight)
Returns a thumbnail of a source image.
This method favors speed over quality. When the new size is less than
half the longest dimension of the source image,
createThumbnail(BufferedImage, int)
or
createThumbnail(BufferedImage, int, int)
should be used instead
to ensure the quality of the result without sacrificing too much
performance.
image
- the source imagenewWidth
- the width of the thumbnailnewHeight
- the height of the thumbnailBufferedImage
containing a
thumbnail of image
IllegalArgumentException
- if newWidth
is larger than
the width of image
or if code>newHeight is larger
than the height of image
or if one of the dimensions
is <= 0createThumbnailFast(java.awt.image.BufferedImage, int)
,
createThumbnail(java.awt.image.BufferedImage, int)
,
createThumbnail(java.awt.image.BufferedImage, int, int)
public static BufferedImage createThumbnail(BufferedImage image, int newSize)
Returns a thumbnail of a source image. newSize
defines
the length of the longest dimension of the thumbnail. The other
dimension is then computed according to the dimensions ratio of the
original picture.
This method offers a good trade-off between speed and quality.
The result looks better than
createThumbnailFast(java.awt.image.BufferedImage, int)
when
the new size is less than half the longest dimension of the source
image, yet the rendering speed is almost similar.
image
- the source imagenewSize
- the length of the largest dimension of the thumbnailBufferedImage
containing a
thumbnail of image
IllegalArgumentException
- if newSize
is larger than
the largest dimension of image
or <= 0createThumbnailFast(java.awt.image.BufferedImage, int, int)
,
createThumbnailFast(java.awt.image.BufferedImage, int)
,
createThumbnail(java.awt.image.BufferedImage, int, int)
public static BufferedImage createThumbnail(BufferedImage image, int newWidth, int newHeight)
Returns a thumbnail of a source image.
This method offers a good trade-off between speed and quality.
The result looks better than
createThumbnailFast(java.awt.image.BufferedImage, int)
when
the new size is less than half the longest dimension of the source
image, yet the rendering speed is almost similar.
image
- the source imagenewWidth
- the width of the thumbnailnewHeight
- the height of the thumbnailBufferedImage
containing a
thumbnail of image
IllegalArgumentException
- if newWidth
is larger than
the width of image
or if code>newHeight is larger
than the height of image or if one the dimensions is not > 0
createThumbnailFast(java.awt.image.BufferedImage, int)
,
createThumbnailFast(java.awt.image.BufferedImage, int, int)
,
createThumbnail(java.awt.image.BufferedImage, int)
public static int[] getPixels(BufferedImage img, int x, int y, int w, int h, int[] pixels)
Returns an array of pixels, stored as integers, from a
BufferedImage
. The pixels are grabbed from a rectangular
area defined by a location and two dimensions. Calling this method on
an image of type different from BufferedImage.TYPE_INT_ARGB
and BufferedImage.TYPE_INT_RGB
will unmanage the image.
img
- the source imagex
- the x location at which to start grabbing pixelsy
- the y location at which to start grabbing pixelsw
- the width of the rectangle of pixels to grabh
- the height of the rectangle of pixels to grabpixels
- a pre-allocated array of pixels of size w*h; can be nullpixels
if non-null, a new array of integers
otherwiseIllegalArgumentException
- is pixels
is non-null and
of length < w*hpublic static void setPixels(BufferedImage img, int x, int y, int w, int h, int[] pixels)
Writes a rectangular area of pixels in the destination
BufferedImage
. Calling this method on
an image of type different from BufferedImage.TYPE_INT_ARGB
and BufferedImage.TYPE_INT_RGB
will unmanage the image.
img
- the destination imagex
- the x location at which to start storing pixelsy
- the y location at which to start storing pixelsw
- the width of the rectangle of pixels to storeh
- the height of the rectangle of pixels to storepixels
- an array of pixels, stored as integersIllegalArgumentException
- is pixels
is non-null and
of length < w*hpublic static void clear(Image img)
img
- the image to erasepublic static void tileStretchPaint(Graphics g, JComponent comp, BufferedImage img, Insets ins)
WebARTS Library Licensed Under the GNU - General Public License. Other Libraries licensed under their respective Open Source Licenses