Class GraphicsUtilities
GraphicsUtilities
contains a set of tools to perform
common graphics operations easily. These operations are divided into
several themes, listed below.
Compatible Images
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.
Creating Thumbnails
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.
Image Manipulation
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.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic void
Clears the data from the image.static BufferedImage
Converts the specified image into a compatible buffered image.static BufferedImage
Returns a newBufferedImage
using the same color model as the image passed as a parameter.static BufferedImage
createCompatibleImage
(int width, int height) Returns a new opaque compatible image of the specified width and height.static BufferedImage
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
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
static int[]
getPixels
(BufferedImage img, int x, int y, int w, int h, int[] pixels) Returns an array of pixels, stored as integers, from aBufferedImage
.private static boolean
static BufferedImage
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 destinationBufferedImage
.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.
-
Constructor Details
-
GraphicsUtilities
private GraphicsUtilities()
-
-
Method Details
-
getGraphicsConfiguration
-
isHeadless
private static boolean isHeadless() -
convertToBufferedImage
Converts the specified image into a compatible buffered image.- Parameters:
img
- the image to convert- Returns:
- a compatible buffered image of the input
-
createColorModelCompatibleImage
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.- Parameters:
image
- the reference image from which the color model of the new image is obtained- Returns:
- a new
BufferedImage
, compatible with the color model ofimage
-
createCompatibleImage
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.
- Parameters:
image
- the reference image from which the dimension and the transparency of the new image are obtained- Returns:
- a new compatible
BufferedImage
with the same dimension and transparency asimage
- See Also:
-
createCompatibleImage
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.- Parameters:
image
- the reference image from which the transparency of the new image is obtainedwidth
- the width of the new imageheight
- the height of the new image- Returns:
- a new compatible
BufferedImage
with the same transparency asimage
and the specified dimension - See Also:
-
createCompatibleImage
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.- Parameters:
width
- the width of the new imageheight
- the height of the new image- Returns:
- a new opaque compatible
BufferedImage
of the specified width and height - See Also:
-
createCompatibleTranslucentImage
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.- Parameters:
width
- the width of the new imageheight
- the height of the new image- Returns:
- a new translucent compatible
BufferedImage
of the specified width and height - See Also:
-
loadCompatibleImage
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.
- Parameters:
in
- the stream of the picture to load as a compatible image- Returns:
- a new translucent compatible
BufferedImage
of the specified width and height - Throws:
IOException
- if the image cannot be read or loaded- See Also:
-
loadCompatibleImage
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.
- Parameters:
resource
- the URL of the picture to load as a compatible image- Returns:
- a new translucent compatible
BufferedImage
of the specified width and height - Throws:
IOException
- if the image cannot be read or loaded- See Also:
-
toCompatibleImage
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.- Parameters:
image
- the image to copy into a new compatible image- Returns:
- a new compatible copy, with the
same width and height and transparency and content, of
image
- See Also:
-
createThumbnailFast
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)
orcreateThumbnail(BufferedImage, int, int)
should be used instead to ensure the quality of the result without sacrificing too much performance.- Parameters:
image
- the source imagenewSize
- the length of the largest dimension of the thumbnail- Returns:
- a new compatible
BufferedImage
containing a thumbnail ofimage
- Throws:
IllegalArgumentException
- ifnewSize
is larger than the largest dimension ofimage
or <= 0- See Also:
-
createThumbnailFast
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)
orcreateThumbnail(BufferedImage, int, int)
should be used instead to ensure the quality of the result without sacrificing too much performance.- Parameters:
image
- the source imagenewWidth
- the width of the thumbnailnewHeight
- the height of the thumbnail- Returns:
- a new compatible
BufferedImage
containing a thumbnail ofimage
- Throws:
IllegalArgumentException
- ifnewWidth
is larger than the width ofimage
or if code>newHeight is larger than the height ofimage
or if one of the dimensions is <= 0- See Also:
-
createThumbnail
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.- Parameters:
image
- the source imagenewSize
- the length of the largest dimension of the thumbnail- Returns:
- a new compatible
BufferedImage
containing a thumbnail ofimage
- Throws:
IllegalArgumentException
- ifnewSize
is larger than the largest dimension ofimage
or <= 0- See Also:
-
createThumbnail
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.- Parameters:
image
- the source imagenewWidth
- the width of the thumbnailnewHeight
- the height of the thumbnail- Returns:
- a new compatible
BufferedImage
containing a thumbnail ofimage
- Throws:
IllegalArgumentException
- ifnewWidth
is larger than the width ofimage
or if code>newHeight is larger than the height ofimage or if one the dimensions is not > 0
- See Also:
-
getPixels
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 fromBufferedImage.TYPE_INT_ARGB
andBufferedImage.TYPE_INT_RGB
will unmanage the image.- Parameters:
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 null- Returns:
pixels
if non-null, a new array of integers otherwise- Throws:
IllegalArgumentException
- ispixels
is non-null and of length < w*h
-
setPixels
Writes a rectangular area of pixels in the destination
BufferedImage
. Calling this method on an image of type different fromBufferedImage.TYPE_INT_ARGB
andBufferedImage.TYPE_INT_RGB
will unmanage the image.- Parameters:
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 integers- Throws:
IllegalArgumentException
- ispixels
is non-null and of length < w*h
-
clear
Clears the data from the image.- Parameters:
img
- the image to erase
-
tileStretchPaint
Draws an image on top of a component by doing a 3x3 grid stretch of the image using the specified insets.
-