Package resources
Class StrangeImage
- java.lang.Object
-
- resources.StrangeImage
-
public abstract class StrangeImage extends java.lang.Object
A high-level representation of a drawable graphic that can be used by Strange Eons in various contexts. This class is often the starting point when working with images selected by the user. The class provides a common interface that can be used to work with both bitmap and vector images transparently.For drawing purposes, a
StrangeImage
can be treated as either a bitmap or vector image regardless of the original format. It can also be painted directly.A
StrangeImage
must have a positive width and height. Breaking this condition will lead to bugs that may be hard to detect. If you must return a representation of an image with a zero width or height, return an invisible image instead.- Since:
- 3.0.3695
- Author:
- Chris Jennings
-
-
Constructor Summary
Constructors Constructor Description StrangeImage()
Constructs a newStrangeImage
.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract java.awt.image.BufferedImage
asBufferedImage()
Returns a version of the image as aBufferedImage
image.abstract VectorImage
asVectorImage()
Returns a version of the image as aVectorImage
image.static StrangeImage
create(VectorImage source)
Creates a newStrangeImage
from the specified vector image source.static StrangeImage
create(java.awt.Image source)
Creates a newStrangeImage
from the specified bitmap image source.static boolean
exists(java.lang.String identifier)
Returns whether or not an identifier refers to a valid image.static StrangeImage
get(java.lang.String identifier)
Returns aStrangeImage
for the given identifier.static java.awt.image.BufferedImage
getAsBufferedImage(java.lang.String identifier)
Returns aBufferedImage
for the given identifier.double
getAspectRatio()
Returns the aspect ratio of the image, that is, the width divided by the height.abstract int
getHeight()
Returns a typical pixel height for the image.abstract double
getHeight2D()
Returns the image height as adouble
value.static StrangeImage
getInvisibleImage()
Returns aStrangeImage
that is completely invisible.static StrangeImage
getMissingImage()
Returns a standard image returned fromget(java.lang.String)
when an image cannot be obtained from the specified identifier.abstract int
getWidth()
Returns a typical pixel width for the image.abstract double
getWidth2D()
Returns the image width as adouble
value.static java.net.URL
identifierToURL(java.lang.String identifier)
Returns a URL for a user image identifier, ornull
.static boolean
isFileIdentifier(java.lang.String identifier)
Returnstrue
if the image identifier names a local file, as opposed to a special URL.boolean
isTransparent()
Returnstrue
if some parts of the image may not be opaque.boolean
isVectorFormat()
Returnstrue
if the underlying image is a vector image.void
paint(java.awt.Graphics2D g, double x, double y, double width, double height, boolean fitToSize)
Paints the image to a graphics context at the specified location and dimensions.abstract void
paint(java.awt.Graphics2D g, int x, int y, int width, int height, boolean fitToSize)
Paints the image to a graphics context at the specified location and dimensions.void
paint(java.awt.Graphics2D g, java.awt.geom.Rectangle2D rect, boolean fitToSize)
Paints the image to a graphics context within the bounds of the specified rectangle.java.awt.image.BufferedImage
toBufferedImage(int width, int height, boolean fitToSize)
Returns a new buffered image representing the image content.
-
-
-
Method Detail
-
paint
public abstract void paint(java.awt.Graphics2D g, int x, int y, int width, int height, boolean fitToSize)
Paints the image to a graphics context at the specified location and dimensions.- Parameters:
g
- the graphics context to use for paintingx
- the x-coordinate of the upper-left corner of the imagey
- the y-coordinate of the upper-left corner of the imagewidth
- the width of the imageheight
- the height of the imagefitToSize
- iftrue
, the image's original aspect ratio will be maintained
-
paint
public void paint(java.awt.Graphics2D g, double x, double y, double width, double height, boolean fitToSize)
Paints the image to a graphics context at the specified location and dimensions. The location and size are specified using double precision floating point values; depending on the underlying implementation, these coordinates may be rounded to a less accurate form before painting.- Parameters:
g
- the graphics context to use for paintingx
- the x-coordinate of the upper-left corner of the imagey
- the y-coordinate of the upper-left corner of the imagewidth
- the width of the imageheight
- the height of the imagefitToSize
- iftrue
, the image's original aspect ratio will be maintained
-
paint
public final void paint(java.awt.Graphics2D g, java.awt.geom.Rectangle2D rect, boolean fitToSize)
Paints the image to a graphics context within the bounds of the specified rectangle.- Parameters:
g
- the graphics contextrect
- the rectangle defining the upper-left corner and dimensions of the imagefitToSize
- iftrue
, the image's original aspect ratio will be maintained
-
asBufferedImage
public abstract java.awt.image.BufferedImage asBufferedImage()
Returns a version of the image as aBufferedImage
image. The returned value may be shared, so the image must not be modified. If the underlying image type is a bitmap image, then the returned image will be the same size as the original image. The returned image is guaranteed to use an RGB or ARGB pixel format.- Returns:
- a bitmap version of the image
-
asVectorImage
public abstract VectorImage asVectorImage()
Returns a version of the image as aVectorImage
image. Note that if the underlying image is a bitmap image, this will not convert the image into a true vector format (for example, by applying a tracing algorithm). It simply provides aVectorImage
interface to the underlying bitmap data.- Returns:
- a vector version of the image
-
toBufferedImage
public java.awt.image.BufferedImage toBufferedImage(int width, int height, boolean fitToSize)
Returns a new buffered image representing the image content. The image will be resized, if necessary, to the specified size. IffitToSize
istrue
, then the original aspect ratio of the image will be maintained. The returned image is guaranteed to use an RGB or ARGB pixel format.- Parameters:
width
- the image widthheight
- the image heightfitToSize
- iftrue
, the original aspect ratio will be maintained- Returns:
- a version of the image as a bitmap
-
getWidth
public abstract int getWidth()
Returns a typical pixel width for the image. If the underlying image is a bitmap image, this will return the true pixel width of that image.- Returns:
- a width for the image, in pixels
-
getHeight
public abstract int getHeight()
Returns a typical pixel height for the image. If the underlying image is a bitmap image, this will return the true pixel height of that image.- Returns:
- a height for the image, in pixels
-
getWidth2D
public abstract double getWidth2D()
Returns the image width as adouble
value. Depending on the underlying image, this may return a more accurate measure of the true image width thangetWidth()
.- Returns:
- a width for the image, in pixels
-
getHeight2D
public abstract double getHeight2D()
Returns the image height as adouble
value. Depending on the underlying image, this may return a more accurate measure of the true image height thangetHeight()
.- Returns:
- a height for the image, in pixels
-
getAspectRatio
public double getAspectRatio()
Returns the aspect ratio of the image, that is, the width divided by the height. When painting the image at a particular width or height, one can calculate the value for other dimension that will maintain the same image shape using the aspect ratio:Compute size from aspect ratio Known Dimension: Other Dimension Calculated Using: width height = width / aspectRatio height width = height * aspectRatio - Returns:
- the image aspect ratio
-
isTransparent
public boolean isTransparent()
Returnstrue
if some parts of the image may not be opaque. If this returnsfalse
, then it is guaranteed that the image completely covers a rectangular area described by the specified width and height when painted. If this method returnstrue
, then some parts of the painted area may not be completely covered.- Returns:
true
if the image may have transparent areas;false
if the image is known with certainly to be completely opaque
-
isVectorFormat
public boolean isVectorFormat()
Returnstrue
if the underlying image is a vector image. If you wish to work with the original image in its underlying form, you can use code like the following:if( si.isVectorFormat() ) { VectorImage vi = si.asVectorImage(); // ... } else { BufferedImage bi = si.asBufferedImage(); // ... }
- Returns:
true
if the underlying image is a vector image;false
if it is a bitmap image
-
create
public static StrangeImage create(java.awt.Image source)
Creates a newStrangeImage
from the specified bitmap image source.- Parameters:
source
- the source image- Returns:
- a view of the source image as a
StrangeImage
instance
-
create
public static StrangeImage create(VectorImage source)
Creates a newStrangeImage
from the specified vector image source.- Parameters:
source
- the source image- Returns:
- a view of the source image as a
StrangeImage
instance
-
get
public static StrangeImage get(java.lang.String identifier)
Returns aStrangeImage
for the given identifier. The identifier can be a local file path or afile:
,http:
,res:
, orproject:
URL. Any string that is valid in a portrait panel will produce the same image here, except for the empty string that produce's the component-specific default portrait.- Parameters:
identifier
- the identifier to use to locate the file- Returns:
- the identified image, or a "missing image" stand-in
-
getAsBufferedImage
public static java.awt.image.BufferedImage getAsBufferedImage(java.lang.String identifier)
Returns aBufferedImage
for the given identifier. The identifier can be a local file path or afile:
,http:
,res:
, orproject:
URL. Any string that is valid in a portrait panel will produce the same image here, except for the empty string that produce's the component-specific default portrait.This method is similar to
get(java.lang.String)
, but ensures that the returned image is aBufferedImage
bitmap. Vector images will be converted to bitmaps automatically. Where possible, prefer code that works with both bitmaps and vectors transparently by usingget(java.lang.String)
instead.- Parameters:
identifier
- the identifier to use to locate the file- Returns:
- the identified image, or a "missing image" stand-in
- Since:
- 3.2
-
exists
public static boolean exists(java.lang.String identifier)
Returns whether or not an identifier refers to a valid image. For example, passing a file identifier for a file that does not exist would return false. Note that this will load (and cache) the image if it is not already loaded.- Parameters:
identifier
- the identifier to use to locate the file- Returns:
- true if the identifier points to a valid image, false otherwise
- Since:
- 3.2
-
identifierToURL
public static java.net.URL identifierToURL(java.lang.String identifier)
Returns a URL for a user image identifier, ornull
. If the identifier isnull
or empty, thennull
is returned. (An empty string is typically used to indicate that a default image should be used.)- Parameters:
identifier
- an identifier string containing a local file path or URL- Returns:
- a URL that can be used to read the identified content
-
isFileIdentifier
public static boolean isFileIdentifier(java.lang.String identifier)
Returnstrue
if the image identifier names a local file, as opposed to a special URL.- Parameters:
identifier
- the identifier to locate- Returns:
true
if the identifier is for a local file- See Also:
get(java.lang.String)
-
getInvisibleImage
public static StrangeImage getInvisibleImage()
Returns aStrangeImage
that is completely invisible. This can be used as a stand-in image for an image with a zero width or height, sinceStrangeImage
s must have a non-zero area.- Returns:
- a completely transparent image
-
getMissingImage
public static StrangeImage getMissingImage()
Returns a standard image returned fromget(java.lang.String)
when an image cannot be obtained from the specified identifier.- Returns:
- the shared missing image
-
-