|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--javax.media.jai.PlanarImage
A RenderedImage is expressed as a collection of pixels.
A pixel is defined as a 1-by-1 square; its origin is the top-left
corner of the square (0, 0), and its energy center is located at the
center of the square (0.5, 0.5).
This is the fundamental base class of Java Advanced Imaging (JAI)
that represents a two-dimensional RenderedImage.
This class provides a home for the information and functionalities
common to all the JAI classes that implement the
RenderedImage interface, such as the image's layout,
sources, properties, etc. The image layout, sources, and properties
may be set either at construction or subsequently using one of the
mutator methods supplied for the respective attribute. In general
this class does not perform sanity checking on the state of its
variables so it is very important that subclasses set them correctly.
This is of particular importance with respect to the image layout.
The layout of a PlanarImage is specified by variables
minX, minY, width,
height, tileGridXOffset,
tileGridYOffset, tileWidth,
tileHeight, sampleModel, and
colorModel. These variables do not have any default settings
so subclasses must set the appropriate ones at construction via the
ImageLayout argument or subsequently using
setImageLayout(). Otherwise, unexpected errors may occur.
Although these variables have protected access, it is
strongly recommended that subclasses not set the values of these variables
directly but rather via setImageLayout() which performs a
certain few initializations based on the layout values. The variables
are defined to have protected access for convenience.
A PlanarImage may have any number of
RenderedImage sources or no source at all.
All non-JAI RenderedImage instances must be
converted into PlanarImages by means of the
RenderedImageAdapter and
WritableRenderedImageAdapter classes. The
wrapRenderedImage method provides a convenient interface
to both add a wrapper and take a snapshot if the image is writable.
All of the PlanarImage constructors perform this wrapping
automatically. Images that already extend PlanarImage
will be returned unchanged by wrapRenderedImage; that
is, it is idempotent.
Going in the other direction, existing code that makes use of
the RenderedImage interface will be able to use
PlanarImages directly, without any changes or
recompilation. Therefore, within JAI, two-dimensional images are
returned from methods as PlanarImages, even though
incoming RenderedImages are accepted as arguments directly.
A PlanarImage may also have any number of properties
of any type. If or how a property is used depends on the individual
subclass. This class only stores the property information. If any
PropertyChangeListeners are registered they will receive
a PropertySourceChangeEvent for each change in an image
property.
In general, methods in this class are implemented such that they use any class variables directly instead of through their accessors for performance reasons. Subclasses need to be careful when overriding this class' variable accessors that other appropriate methods are overriden as well.
PlanarImage implements a createSnapshot
method that produces a new, immutable image with a copy of this
image's current contents. In practice, this snapshot is only a
virtual copy; it is managed by the SnapshotImage class
in such a way as to minimize copying and memory footprint generally.
Multiple calls to createSnapshot make use of a single
SnapshotImage per PlanarImage in order to
centralize version management. These mechanisms are transparent to
the API user and are discussed here only for edification.
The source and sink lists have the effect of creating a graph
structure between a set of PlanarImages. Note that
the practice of making such bidirectional connections between
images means that the garbage collector will not inform us when all
user references to a node are lost, since there will still be
internal references up until the point where the entire graph is
detached from user space. A solution is available in the form of
Reference Objects; see
http://java.sun.com/j2se/1.5.0/docs/guide/refobs/index.html for
more information. These classes include weak references
that allow the Garbage Collector (GC) to collect objects they
reference, setting the reference to null in the process.
The reference problem requires us to be careful about how we define the reachability of directed acyclic graph (DAG) nodes. If we were to allow nodes to be reached by arbitrary graph traversal, we would be unable to garbage collect any subgraphs of an active graph at all since any node may be reached from any other. Instead, we define the set of reachable nodes as those that may be accessed directly from a reference in user code, or that are the source (not sink) of a reachable node. Reachable nodes are always accessible, whether they are reached by traversing upwards or downwards in the DAG.
A DAG may also contain nodes that are not reachable, that is,
they require a downward traversal at some point. For example,
assume a node A is reachable, and a call to
A.getSinks() yields a Vector containing a
reference to a previously unreachable node B. The
node B naturally becomes reachable by virtue of the
new user reference pointing to it. However, if the user were to
relinquish that reference, the node might be garbage collected, and
a future call to A.getSinks() might no longer include
B in its return value.
Because the set of sinks of a node is inherently unstable, only
the getSinks method is provided for external access to
the sink vector at a node. A hypothetical method such as
getSink or getNumSinks would produce
confusing results should a sink be garbage collected between that
call and a subsequent call to getSinks.
RenderedImage,
Reference,
WeakReference,
ImageJAI,
OpImage,
RenderedImageAdapter,
SnapshotImage,
TiledImage| Field Summary | |
protected ColorModel |
colorModel
The image's ColorModel. |
protected PropertyChangeSupportJAI |
eventManager
A helper object to manage firing events. |
protected int |
height
The image's height in number of pixels. |
protected int |
minX
The X coordinate of the image's top-left pixel. |
protected int |
minY
The Y coordinate of the image's top-left pixel. |
protected WritablePropertySourceImpl |
properties
A helper object to manage the image properties. |
protected SampleModel |
sampleModel
The image's SampleModel. |
protected TileFactory |
tileFactory
A TileFactory for use in
createWritableRaster(SampleModel,Point). |
protected int |
tileGridXOffset
The X coordinate of the top-left pixel of tile (0, 0). |
protected int |
tileGridYOffset
The Y coordinate of the top-left pixel of tile (0, 0). |
protected int |
tileHeight
The height of a tile in number of pixels. |
protected int |
tileWidth
The width of a tile in number of pixels. |
protected int |
width
The image's width in number of pixels. |
| Constructor Summary | |
PlanarImage()
The default constructor. |
|
PlanarImage(ImageLayout layout,
Vector sources,
Map properties)
Constructor. |
|
| Method Summary | |
void |
addPropertyChangeListener(PropertyChangeListener listener)
Add a PropertyChangeListener to the listener list. |
void |
addPropertyChangeListener(String propertyName,
PropertyChangeListener listener)
Add a PropertyChangeListener for a specific property. |
boolean |
addSink(Object sink)
Adds an Object sink to the list of sinks. |
protected void |
addSink(PlanarImage sink)
Deprecated. as of JAI 1.1. Use addSink(Object) instead. |
protected void |
addSource(Object source)
Adds an Object source to the list of sources. |
void |
addTileComputationListener(TileComputationListener listener)
Adds a TileComputationListener to the list of
registered TileComputationListeners. |
void |
cancelTiles(TileRequest request,
Point[] tileIndices)
Issue an advisory cancellation request to nullify processing of the indicated tiles. |
WritableRaster |
copyData()
Copies the entire image into a single raster. |
WritableRaster |
copyData(WritableRaster raster)
Copies an arbitrary rectangular region of this image's pixel data into a caller-supplied WritableRaster. |
void |
copyExtendedData(WritableRaster dest,
BorderExtender extender)
Copies an arbitrary rectangular region of the RenderedImage into a caller-supplied
WritableRaster. |
static ColorModel |
createColorModel(SampleModel sm)
Creates a ColorModel that may be used with the
specified SampleModel. |
PlanarImage |
createSnapshot()
Creates a snapshot, that is, a virtual copy of the image's current contents. |
protected WritableRaster |
createWritableRaster(SampleModel sampleModel,
Point location)
Creates a WritableRaster with the specified
SampleModel and location. |
void |
dispose()
Provides a hint that an image will no longer be accessed from a reference in user space. |
protected void |
finalize()
Performs cleanup prior to garbage collection. |
BufferedImage |
getAsBufferedImage()
Returns a copy of the entire image as a BufferedImage. |
BufferedImage |
getAsBufferedImage(Rectangle rect,
ColorModel cm)
Returns a copy of this image as a BufferedImage. |
Rectangle |
getBounds()
Returns the image's bounds as a Rectangle. |
ColorModel |
getColorModel()
Returns the ColorModel of the image. |
Raster |
getData()
Returns the entire image in a single Raster. |
Raster |
getData(Rectangle region)
Returns a specified region of this image in a Raster. |
static ColorModel |
getDefaultColorModel(int dataType,
int numBands)
Returns a ComponentColorModel created based on
the indicated dataType and numBands. |
Raster |
getExtendedData(Rectangle region,
BorderExtender extender)
Returns a copy of an arbitrary rectangular region of this image in a Raster. |
Graphics |
getGraphics()
Returns a Graphics object that may be used to draw
into this image. |
int |
getHeight()
Returns the height of the image in number of pixels. |
Object |
getImageID()
Returns a unique identifier (UID) for this PlanarImage. |
int |
getMaxTileX()
Returns the horizontal index of the right-most column of tiles. |
int |
getMaxTileY()
Returns the vertical index of the bottom-most row of tiles. |
int |
getMaxX()
Returns the X coordinate of the column immediately to the right of the right-most column of the image. |
int |
getMaxY()
Returns the Y coordinate of the row immediately below the bottom-most row of the image. |
int |
getMinTileX()
Returns the horizontal index of the left-most column of tiles. |
int |
getMinTileY()
Returns the vertical index of the top-most row of tiles. |
int |
getMinX()
Returns the X coordinate of the left-most column of the image. |
int |
getMinY()
Returns the Y coordinate of the top-most row of the image. |
int |
getNumBands()
Retrieve the number of image bands. |
int |
getNumSources()
Returns the number of immediate PlanarImage sources
this image has. |
int |
getNumXTiles()
Returns the number of tiles along the tile grid in the horizontal direction. |
int |
getNumYTiles()
Returns the number of tiles along the tile grid in the vertical direction. |
protected Hashtable |
getProperties()
Returns the internal Hashtable containing the
image properties by reference. |
Object |
getProperty(String name)
Gets a property from the property set of this image. |
Class |
getPropertyClass(String name)
Returns the class expected to be returned by a request for the property with the specified name. |
String[] |
getPropertyNames()
Returns a list of property names that are recognized by this image or null if none are recognized. |
String[] |
getPropertyNames(String prefix)
Returns an array of Strings recognized as names by
this property source that begin with the supplied prefix. |
SampleModel |
getSampleModel()
Returns the SampleModel of the image. |
Vector |
getSinks()
Returns a Vector containing the currently available
PlanarImage sinks of this image (images for which
this image is a source), or null if no sinks are
present. |
PlanarImage |
getSource(int index)
Deprecated. as of JAI 1.1. Use getSourceImage(). |
PlanarImage |
getSourceImage(int index)
Returns the immediate source indicated by the index. |
Object |
getSourceObject(int index)
Returns the immediate source indicated by the index. |
Vector |
getSources()
Returns this image's immediate source(s) in a Vector. |
void |
getSplits(IntegerSequence xSplits,
IntegerSequence ySplits,
Rectangle rect)
Within a given rectangle, store the list of tile seams of both X and Y directions into the corresponding split sequence. |
abstract Raster |
getTile(int tileX,
int tileY)
Returns tile ( tileX, tileY) as a
Raster. |
TileComputationListener[] |
getTileComputationListeners()
Retrieves a snapshot of the set of all registered TileComputationListeners as of the moment this
method is invoked. |
TileFactory |
getTileFactory()
Returns the value of the instance variable tileFactory. |
int |
getTileGridXOffset()
Returns the X coordinate of the top-left pixel of tile (0, 0). |
int |
getTileGridYOffset()
Returns the Y coordinate of the top-left pixel of tile (0, 0). |
int |
getTileHeight()
Returns the height of a tile of this image in number of pixels. |
Point[] |
getTileIndices(Rectangle region)
Returns an array containing the indices of all tiles which overlap the specified Rectangle. |
Rectangle |
getTileRect(int tileX,
int tileY)
Returns a Rectangle indicating the active area of
a given tile. |
Raster[] |
getTiles()
Computes and returns all tiles in the image. |
Raster[] |
getTiles(Point[] tileIndices)
Returns the Rasters indicated by the
tileIndices array. |
int |
getTileWidth()
Returns the width of a tile of this image in number of pixels. |
int |
getWidth()
Returns the width of the image in number of pixels. |
boolean |
overlapsMultipleTiles(Rectangle rect)
Returns true if and only if the intersection of
the specified Rectangle with the image bounds
overlaps more than one tile. |
void |
prefetchTiles(Point[] tileIndices)
Hints that the given tiles might be needed in the near future. |
TileRequest |
queueTiles(Point[] tileIndices)
Queues a list of tiles for computation. |
void |
removeProperty(String name)
Removes the named property from the PlanarImage. |
void |
removePropertyChangeListener(PropertyChangeListener listener)
Remove a PropertyChangeListener from the listener list. |
void |
removePropertyChangeListener(String propertyName,
PropertyChangeListener listener)
Remove a PropertyChangeListener for a specific property. |
boolean |
removeSink(Object sink)
Removes an Object sink from the list of sinks. |
protected boolean |
removeSink(PlanarImage sink)
Deprecated. as of JAI 1.1. Use removeSink(Object) instead. |
void |
removeSinks()
Removes all the sinks of this image. |
protected boolean |
removeSource(Object source)
Removes an Object source from the list of sources. |
protected void |
removeSources()
Removes all the sources of this image. |
void |
removeTileComputationListener(TileComputationListener listener)
Removes a TileComputationListener from the list of
registered TileComputationListeners. |
protected void |
setImageLayout(ImageLayout layout)
Sets the image bounds, tile grid layout, SampleModel and ColorModel using
values from an ImageLayout object. |
protected void |
setProperties(Hashtable properties)
Sets the Hashtable containing the image properties
to a given Hashtable. |
void |
setProperty(String name,
Object value)
Sets a property on a PlanarImage. |
protected void |
setSource(Object source,
int index)
Sets an immediate source of this image. |
protected void |
setSources(List sourceList)
Sets the list of sources from a given List of
PlanarImages. |
int |
tileXToX(int tx)
Converts a horizontal tile index into the X coordinate of its upper left pixel. |
static int |
tileXToX(int tx,
int tileGridXOffset,
int tileWidth)
Converts a horizontal tile index into the X coordinate of its upper left pixel relative to a given tile grid layout specified by its X offset and tile width. |
int |
tileYToY(int ty)
Converts a vertical tile index into the Y coordinate of its upper left pixel. |
static int |
tileYToY(int ty,
int tileGridYOffset,
int tileHeight)
Converts a vertical tile index into the Y coordinate of its upper left pixel relative to a given tile grid layout specified by its Y offset and tile height. |
String |
toString()
Returns a String which includes the basic information
of this image. |
static PlanarImage |
wrapRenderedImage(RenderedImage image)
Wraps an arbitrary RenderedImage to produce a
PlanarImage. |
int |
XToTileX(int x)
Converts a pixel's X coordinate into a horizontal tile index. |
static int |
XToTileX(int x,
int tileGridXOffset,
int tileWidth)
Converts a pixel's X coordinate into a horizontal tile index relative to a given tile grid layout specified by its X offset and tile width. |
int |
YToTileY(int y)
Converts a pixel's Y coordinate into a vertical tile index. |
static int |
YToTileY(int y,
int tileGridYOffset,
int tileHeight)
Converts a pixel's Y coordinate into a vertical tile index relative to a given tile grid layout specified by its Y offset and tile height. |
| Methods inherited from class java.lang.Object |
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
protected int minX
protected int minY
protected int width
protected int height
protected int tileGridXOffset
protected int tileGridYOffset
protected int tileWidth
protected int tileHeight
protected SampleModel sampleModel
SampleModel.protected ColorModel colorModel
ColorModel.protected TileFactory tileFactory
TileFactory for use in
createWritableRaster(SampleModel,Point).
This field will be null unless initialized via the
configuration properties passed to
PlanarImage(ImageLayout,Vector,Map).protected PropertyChangeSupportJAI eventManager
protected WritablePropertySourceImpl properties
| Constructor Detail |
public PlanarImage()
The eventManager and properties
helper fields are initialized by this constructor; no other
non-private fields are set.
public PlanarImage(ImageLayout layout,
Vector sources,
Map properties)
The image's layout is encapsulated in the layout
argument. Note that no verification is performed to determine whether
the image layout has been set either at construction or subsequently.
This constructor does not provide any default settings for
the layout variables so all of those that will be used later must
be set in the layout argument or subsequently via
setImageLayout() before the values are used.
Otherwise, unexpected errors may occur.
If the SampleModel is non-null and the
supplied tile dimensions are positive, then if the dimensions of the
supplied SampleModel differ from the tile dimensions, a
new SampleModel will be created for the image from the
supplied SampleModel but with dimensions equal to those
of a tile.
If both the SampleModel and the ColorModel
in the supplied ImageLayout are non-null
they will be tested for compatibility. If the test fails an
exception will be thrown. The test is that
ColorModel.isCompatibleSampleModel() invoked on
the SampleModel must return true, and
ColorModel is a
ComponentColorModel then:
SampleModel must equal
the number of components of the ColorModel, and
SampleModel.getSampleSize(b) >= ColorModel.getComponentSize(b)
for all bands b.
The sources parameter contains a list of immediate
sources of this image none of which may be null. All
RenderedImages in the list are automatically converted
into PlanarImages when necessary. If this image has
no source, this argument should be null.
The properties parameter contains a mapping of image
properties. All map entries which have a key which is either a
String or a CaselessStringKey are interpreted
as image properties and will be copied to the property database of
this image. This parameter may be null.
If a TileFactory-valued mapping of the key
JAI.KEY_TILE_FACTORY is present in
properties, then set the instance variable
tileFactory to the specified TileFactory.
This TileFactory will be used by
createWritableRaster(SampleModel,Point) to create
Rasters, notably in getData(Rectangle),
copyData(WritableRaster), and
getExtendedData(Rectangle,BorderExtender).
The event and property helper fields are initialized by this constructor.
layout - The layout of this image or null.sources - The immediate sources of this image or
null.properties - A Map containing the properties of
this image or null.IllegalArgumentException - if a
ColorModel is specified in the layout and it is
incompatible with the SampleModelIllegalArgumentException - If sources
is non-null and any object in
sources is null.| Method Detail |
protected void setImageLayout(ImageLayout layout)
SampleModel and ColorModel using
values from an ImageLayout object.
If either of the tile dimensions is not set in the passed in
ImageLayout object, then the tile dimension in question
will be set to the corresponding image dimension.
If either of the tile grid offsets is not set in the passed in
ImageLayout object, then the tile grid offset in
question will be set to 0. The same is true for the minX
, minY, width and height
fields, if no value is set in the passed in ImageLayout
object, they will be set to 0.
If the SampleModel is non-null and the
supplied tile dimensions are positive, then if the dimensions of the
supplied SampleModel differ from the tile dimensions, a
new SampleModel will be created for the image from the
supplied SampleModel but with dimensions equal to those
of a tile.
If both the SampleModel and the ColorModel
in the supplied ImageLayout are non-null
they will be tested for compatibility. If the test fails an
exception will be thrown. The test is that
ColorModel.isCompatibleSampleModel() invoked on
the SampleModel must return true, and
ColorModel is a
ComponentColorModel then:
SampleModel must equal
the number of components of the ColorModel, and
SampleModel.getSampleSize(b) >= ColorModel.getComponentSize(b)
for all bands b.
layout - an ImageLayout that is used to selectively
override the image's layout, SampleModel,
and ColorModel. Only valid fields, i.e.,
those for which ImageLayout.isValid() returns
true for the appropriate mask, are used.IllegalArgumentExceptionlayout
is null.IllegalArgumentExceptionColorModel is specified in the layout and it is
incompatible with the SampleModelpublic static PlanarImage wrapRenderedImage(RenderedImage image)
RenderedImage to produce a
PlanarImage. PlanarImage adds
various properties to an image, such as source and sink vectors
and the ability to produce snapshots, that are necessary for
JAI.
If the image is already a PlanarImage, it is
simply returned unchanged. Otherwise, the image is wrapped in
a RenderedImageAdapter or
WritableRenderedImageAdapter as appropriate.
image - The RenderedImage to be converted into
a PlanarImage.PlanarImage containing image's
pixel data.IllegalArgumentException - If image is
null.public PlanarImage createSnapshot()
WritableRenderedImage, it is returned unchanged.
Otherwise, a SnapshotImage is created and the
result of calling its createSnapshot() is
returned.PlanarImage with immutable contents.public int getMinX()
getMinX in interface RenderedImagepublic int getMaxX()
This method is implemented in terms of getMinX()
and getWidth() so that subclasses which override
those methods do not need to override this one.
public int getMinY()
getMinY in interface RenderedImagepublic int getMaxY()
This method is implemented in terms of getMinY()
and getHeight() so that subclasses which override
those methods do not need to override this one.
public int getWidth()
getWidth in interface RenderedImagepublic int getHeight()
getHeight in interface RenderedImagepublic int getNumBands()
IndexColorModel. This is equivalent to calling
getSampleModel().getNumBands().public Rectangle getBounds()
Rectangle.
The image's bounds are defined by the values returned by
getMinX(), getMinY(),
getWidth(), and getHeight().
A Rectangle is created based on these four methods and
cached in this class. Each time that this method is invoked, the
bounds of this Rectangle are updated with the values
returned by the four aforementioned accessors.
Because this method returns the bounds variable
by reference, the caller should not change the settings of the
Rectangle. Otherwise, unexpected errors may occur.
Likewise, if the caller expects this variable to be immutable it
should clone the returned Rectangle if there is any
possibility that it might be changed by the PlanarImage.
This may generally occur only for instances of RenderedOp.
public int getTileGridXOffset()
getTileGridXOffset in interface RenderedImagepublic int getTileGridYOffset()
getTileGridYOffset in interface RenderedImagepublic int getTileWidth()
getTileWidth in interface RenderedImagepublic int getTileHeight()
getTileHeight in interface RenderedImagepublic int getMinTileX()
This method is implemented in terms of the static method
XToTileX() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
getMinTileX in interface RenderedImagepublic int getMaxTileX()
This method is implemented in terms of the static method
XToTileX() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
public int getNumXTiles()
This method is implemented in terms of the static method
XToTileX() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
getNumXTiles in interface RenderedImagepublic int getMinTileY()
This method is implemented in terms of the static method
YToTileY() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
getMinTileY in interface RenderedImagepublic int getMaxTileY()
This method is implemented in terms of the static method
YToTileY() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
public int getNumYTiles()
This method is implemented in terms of the static method
YToTileY() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
getNumYTiles in interface RenderedImage
public static int XToTileX(int x,
int tileGridXOffset,
int tileWidth)
If tileWidth < 0, the results of this method
are undefined. If tileWidth == 0, an
ArithmeticException will be thrown.
ArithmeticException - If tileWidth == 0.
public static int YToTileY(int y,
int tileGridYOffset,
int tileHeight)
If tileHeight < 0, the results of this method
are undefined. If tileHeight == 0, an
ArithmeticException will be thrown.
ArithmeticException - If tileHeight == 0.public int XToTileX(int x)
This method is implemented in terms of the static method
XToTileX() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
x - the X coordinate of a pixel.ArithmeticException - If the tile width of this image is 0.public int YToTileY(int y)
This method is implemented in terms of the static method
YToTileY() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
y - the Y coordinate of a pixel.ArithmeticException - If the tile height of this image is 0.
public static int tileXToX(int tx,
int tileGridXOffset,
int tileWidth)
public static int tileYToY(int ty,
int tileGridYOffset,
int tileHeight)
public int tileXToX(int tx)
This method is implemented in terms of the static method
tileXToX() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
tx - the horizontal index of a tile.public int tileYToY(int ty)
This method is implemented in terms of the static method
tileYToY() applied to the values returned by primitive
layout accessors and so does not need to be implemented by subclasses.
ty - the vertical index of a tile.
public Rectangle getTileRect(int tileX,
int tileY)
Rectangle indicating the active area of
a given tile. The Rectangle is defined as the
intersection of the tile area and the image bounds. No attempt
is made to detect out-of-range indices; tile indices lying
completely outside of the image will result in returning an
empty Rectangle (width and/or height less than or
equal to 0).
This method is implemented in terms of the primitive layout accessors and so does not need to be implemented by subclasses.
tileX - The X index of the tile.tileY - The Y index of the tile.Rectanglepublic SampleModel getSampleModel()
SampleModel of the image.
The default implementation returns the corresponding instance variable.getSampleModel in interface RenderedImagepublic ColorModel getColorModel()
ColorModel of the image.
The default implementation returns the corresponding instance variable.getColorModel in interface RenderedImage
public static ColorModel getDefaultColorModel(int dataType,
int numBands)
ComponentColorModel created based on
the indicated dataType and numBands.
The dataType must be one of DataBuffer's
TYPE_BYTE, TYPE_USHORT,
TYPE_INT, TYPE_FLOAT, or
TYPE_DOUBLE.
The numBands may range from 1 to 4, with the
following ColorSpace and alpha settings:
numBands = 1: CS_GRAY without alpha;
numBands = 2: CS_GRAY with alpha;
numBands = 3: CS_sRGB without alpha;
numBands = 4: CS_sRGB with alpha.
Transparency.TRANSLUCENT if
alpha is used and to Transparency.OPAQUE otherwise.
All other inputs result in a null return value.
dataType - The data type of the ColorModel.numBands - The number of bands of the pixels the created
ColorModel is going to work with.public static ColorModel createColorModel(SampleModel sm)
ColorModel that may be used with the
specified SampleModel. If a suitable
ColorModel cannot be found, this method returns
null.
Suitable ColorModels are guaranteed to exist
for all instances of ComponentSampleModel whose
dataType is not DataBuffer.TYPE_SHORT
and with no more than 4 bands. A ComponentColorModel
of either type CS_GRAY or CS_sRGB is returned.
For 1- and 3- banded SampleModels, the returned
ColorModel will be opaque. For 2- and 4-banded
SampleModels, the output will use alpha transparency.
Additionally, an instance of DirectColorModel
will be created for instances of
SinglePixelPackedSampleModel with no more than 4 bands.
Finally, an instance of IndexColorModel
will be created for instances of
MultiPixelPackedSampleModel with a single band and a
pixel bit stride of unity. This represents the case of binary data.
This method is intended as an useful utility for the creation
of simple ColorModels for some common cases.
In more complex situations, it may be necessary to instantiate
the appropriate ColorModels directly.
ColorModel that is suitable for
the supplied SampleModel, or null.IllegalArgumentException - If sm is
null.public TileFactory getTileFactory()
tileFactory.public int getNumSources()
PlanarImage sources
this image has. If this image has no source, this method returns
0.public Vector getSources()
Vector.
If this image has no source, this method returns null.getSources in interface RenderedImagepublic PlanarImage getSource(int index)
getSourceImage().
index - The index of the desired source.PlanarImage source.ArrayIndexOutOfBoundsException - If this image has no
immediate source, or if the index is negative or greater
than the maximum source index.getSourceImage(int)protected void setSources(List sourceList)
List of
PlanarImages. All of the existing sources are
discarded. Any RenderedImage sources in the supplied
list are wrapped using wrapRenderedImage(). The list
of sinks of each prior PlanarImage source and of each
current unwrapped PlanarImage source is adjusted as
necessary such that this image is a sink of all such current sources
but is removed as a sink of all such prior sources which are not
also current.sourceList - a List of PlanarImages.IllegalArgumentException - If sourceList is
null or contains any null elements.protected void removeSources()
PlanarImages sources.public PlanarImage getSourceImage(int index)
index - The index of the desired source.PlanarImage source.ArrayIndexOutOfBoundsException - If this image has no
immediate source, or if the index is negative or greater
than the maximum source index.public Object getSourceObject(int index)
index - The index of the desired source.Object source.ArrayIndexOutOfBoundsException - If this image has no
immediate source, or if the index is negative or greater
than the maximum source index.protected void addSource(Object source)
Object source to the list of sources.
If the source is a RenderedImage it is wrapped using
wrapRenderedImage(). If the unwrapped source is a
PlanarImage then this image is added to its list of sinks.source - An Object to be added as an
immediate source of this image.IllegalArgumentException - If source is
null.
protected void setSource(Object source,
int index)
Object is referred to by its
index. This image must already have a source corresponding to the
specified index. If the source is a RenderedImage it is
wrapped using wrapRenderedImage(). If the unwrapped
source is a PlanarImage then this image is added to its
list of sinks. If a PlanarImage source previously
existed at this index, this image is removed from its list of sinks.source - A Object source to be set.index - The index of the source to be set.ArrayIndexOutOfBoundsException - If this image has no
immediate source, or if there is no source corresponding
to the index value.IllegalArgumentException - If source is
null.protected boolean removeSource(Object source)
Object source from the list of sources.
If the source is a PlanarImage then this image
is removed from its list of sinks.source - The Object source to be removed.true if the element was present,
false otherwise.IllegalArgumentException - If source is
null.public Vector getSinks()
Vector containing the currently available
PlanarImage sinks of this image (images for which
this image is a source), or null if no sinks are
present.
Sinks are stored using weak references. This means that
the set of sinks may change between calls to
getSinks() if the garbage collector happens to
identify a sink as not otherwise reachable (reachability is
discussed in the class comments for this class).
Since the pool of sinks may change as garbage collection
occurs, PlanarImage does not implement either a
getSink(int index) or a getNumSinks()
method. Instead, the caller must call getSinks(),
which returns a Vector of normal references. As long as the
returned Vector is referenced from user code, the
images it references are reachable and may be reliably
accessed.
public boolean addSink(Object sink)
Object sink to the list of sinks.true if the element was added,
false otherwise.IllegalArgumentException - if
sink is null.public boolean removeSink(Object sink)
Object sink from the list of sinks.true if the element was present,
false otherwise.IllegalArgumentException - if
sink is null.protected void addSink(PlanarImage sink)
addSink(Object) instead.
PlanarImage sink to the list of sinks.sink - A PlanarImage to be added as a sink.IllegalArgumentException - If sink is
null.protected boolean removeSink(PlanarImage sink)
removeSink(Object) instead.
PlanarImage sink from the list of sinks.sink - A PlanarImage sink to be removed.true if the element was present,
false otherwise.IllegalArgumentException - If sink is
null.IndexOutOfBoundsException - If sink is not
in the sink list.public void removeSinks()
protected Hashtable getProperties()
Hashtable containing the
image properties by reference.protected void setProperties(Hashtable properties)
Hashtable containing the image properties
to a given Hashtable. The Hashtable
is incorporated by reference and must not be altered by other
classes after this method is called.public Object getProperty(String name)
java.awt.Image.UndefinedProperty will be returned.getProperty in interface PropertySourcename - the name of the property to get, as a String.Object, or the value
java.awt.Image.UndefinedProperty.IllegalArgumentException - if propertyName
is null.public Class getPropertyClass(String name)
null will be returned.getPropertyClass in interface PropertySourceClass expected to be return by a
request for the value of this property or null.IllegalArgumentException - if name
is null.
public void setProperty(String name,
Object value)
PlanarImage. Some
PlanarImage subclasses may ignore attempts to set
properties.setProperty in interface WritablePropertySourcename - a String containing the property's name.value - the property, as a general Object.IllegalArgumentException - If name or
value is null.public void removeProperty(String name)
PlanarImage.
Some PlanarImage subclasses may ignore attempts to
remove properties.removeProperty in interface WritablePropertySourceIllegalArgumentException - if name
is null.public String[] getPropertyNames()
null if none are recognized.getPropertyNames in interface PropertySourceStrings containing valid
property names or null.public String[] getPropertyNames(String prefix)
Strings recognized as names by
this property source that begin with the supplied prefix. If
no property names match, null will be returned.
The comparison is done in a case-independent manner.
The default implementation calls
getPropertyNames() and searches the list of names
for matches.
getPropertyNames in interface PropertySourceStrings giving the valid
property names.IllegalArgumentException - If prefix is
null.public void addPropertyChangeListener(PropertyChangeListener listener)
addPropertyChangeListener in interface PropertyChangeEmitter
public void addPropertyChangeListener(String propertyName,
PropertyChangeListener listener)
addPropertyChangeListener in interface PropertyChangeEmitterpublic void removePropertyChangeListener(PropertyChangeListener listener)
removePropertyChangeListener in interface PropertyChangeEmitter
public void removePropertyChangeListener(String propertyName,
PropertyChangeListener listener)
removePropertyChangeListener in interface PropertyChangeEmitterpublic void addTileComputationListener(TileComputationListener listener)
TileComputationListener to the list of
registered TileComputationListeners. This listener
will be notified when tiles requested via queueTiles()
have been computed.listener - The TileComputationListener to register.IllegalArgumentException - if listener is
null.public void removeTileComputationListener(TileComputationListener listener)
TileComputationListener from the list of
registered TileComputationListeners.listener - The TileComputationListener to unregister.IllegalArgumentException - if listener is
null.public TileComputationListener[] getTileComputationListeners()
TileComputationListeners as of the moment this
method is invoked.TileComputationListeners or
null if there are none.
public void getSplits(IntegerSequence xSplits,
IntegerSequence ySplits,
Rectangle rect)
xSplits - An IntegerSequence to which the
tile seams in the X direction are to be added.ySplits - An IntegerSequence to which the
tile seams in the Y direction are to be added.rect - The rectangular region of interest.IllegalArgumentException - If xSplits,
ySplits, or rect
is null.public Point[] getTileIndices(Rectangle region)
Rectangle. If the Rectangle
does not intersect the image bounds then null will be
returned. If an array is returned, it will be ordered in terms of
the row major ordering of its contained tile indices. If the
specified Rectangle is null, the tile
indicies for the entire image will be returned.region - The Rectangle of interest.null if region does not intersect
the image bounds.public boolean overlapsMultipleTiles(Rectangle rect)
true if and only if the intersection of
the specified Rectangle with the image bounds
overlaps more than one tile.IllegalArgumentException - if rect is
null.
protected final WritableRaster createWritableRaster(SampleModel sampleModel,
Point location)
WritableRaster with the specified
SampleModel and location. If tileFactory
is non-null, it will be used to create the
WritableRaster; otherwise
RasterFactory.createWritableRaster(SampleModel,Point)
will be used.sampleModel - The SampleModel to use.location - The origin of the WritableRaster; if
null, (0, 0) will be used.IllegalArgumentException - if sampleModel is
null.public Raster getData()
Raster. For
images with multiple tiles this will require creating a new
Raster and copying data from multiple tiles into
it ("cobbling").
The returned Raster is semantically a copy.
This means that subsequent updates to this image will not be
reflected in the returned Raster. For non-writable
(immutable) images, the returned value may be a reference to the
image's internal data. The returned Raster should
be considered non-writable; any attempt to alter its pixel data
(such as by casting it to a WritableRaster or obtaining
and modifying its DataBuffer) may result in undefined
behavior. The copyData method should be used if the
returned Raster is to be modified.
For a very large image, more than
Integer.MAX_VALUE entries could be required in the
returned Raster's underlying data array. Since
the Java language does not permit such an array, an
IllegalArgumentException will be thrown.
getData in interface RenderedImageRaster containing the entire image data.IllegalArgumentException - If the size of the returned data
is too large to be stored in a single Raster.public Raster getData(Rectangle region)
Raster.
The returned Raster is semantically a copy.
This means that subsequent updates to this image will not be
reflected in the returned Raster. For non-writable
(immutable) images, the returned value may be a reference to the
image's internal data. The returned Raster should
be considered non-writable; any attempt to alter its pixel data
(such as by casting it to a WritableRaster or obtaining
and modifying its DataBuffer) may result in undefined
behavior. The copyData method should be used if the
returned Raster is to be modified.
The region of the image to be returned is specified by a
Rectangle. This region may go beyond this image's
boundary. If so, the pixels in the areas outside this image's
boundary are left unset. Use getExtendedData if
a specific extension policy is required.
The region parameter may also be
null, in which case the entire image data is
returned in the Raster.
If region is non-null but does
not intersect the image bounds at all, an
IllegalArgumentException will be thrown.
It is possible to request a region of an image that would
require more than Integer.MAX_VALUE entries
in the returned Raster's underlying data array.
Since the Java language does not permit such an array,
an IllegalArgumentException will be thrown.
getData in interface RenderedImageregion - The rectangular region of this image to be
returned, or null.Raster containing the specified image data.IllegalArgumentException - If the region does not
intersect the image bounds.IllegalArgumentException - If the size of the returned data
is too large to be stored in a single Raster.public WritableRaster copyData()
public WritableRaster copyData(WritableRaster raster)
WritableRaster.
The region to be copied is defined as the boundary of the
WritableRaster, which can be obtained by calling
WritableRaster.getBounds().
The supplied WritableRaster may have a region
that extends beyond this image's boundary, in which case only
pixels in the part of the region that intersects this image
are copied. The areas outside of this image's boundary are left
untouched.
The supplied WritableRaster may also be
null, in which case the entire image is copied
into a newly-created WritableRaster with a
SampleModel that is compatible with that of
this image.
copyData in interface RenderedImageraster - A WritableRaster to hold the copied
pixel data of this image.WritableRaster,
or to a new WritableRaster if the supplied
one was null.
public void copyExtendedData(WritableRaster dest,
BorderExtender extender)
RenderedImage into a caller-supplied
WritableRaster. The portion of the supplied
WritableRaster that lies outside of the bounds of
the image is computed by calling the given
BorderExtender. The supplied
WritableRaster must have a
SampleModel that is compatible with that of the
image.dest - a WritableRaster to hold the returned
portion of the image.extender - an instance of BorderExtender.IllegalArgumentException - If dest or
extender is null.
public Raster getExtendedData(Rectangle region,
BorderExtender extender)
Raster. The portion of the rectangle of
interest ouside the bounds of the image will be computed by
calling the given BorderExtender. If the region
falls entirely within the image, extender will not
be used in any way. Thus it is possible to use a
null value for extender when it is
known that no actual extension will be required.
The returned Raster should be considered
non-writable; any attempt to alter its pixel data (such as by
casting it to a WritableRaster or obtaining and
modifying its DataBuffer) may result in undefined
behavior. The copyExtendedData method should be
used if the returned Raster is to be modified.
region - the region of the image to be returned.extender - an instance of BorderExtender,
used only if the region exceeds the image bounds,
or null.Raster containing the extended data.IllegalArgumentException - If region is
null.IllegalArgumentException - If the region exceeds the image
bounds and extender is null.
public BufferedImage getAsBufferedImage(Rectangle rect,
ColorModel cm)
BufferedImage.
A subarea of the image may be copied by supplying a
Rectangle parameter; if it is set to
null, the entire image is copied. The supplied
Rectangle will be clipped to the image bounds. The image's
ColorModel may be overridden by supplying a
non-null second argument. The resulting
ColorModel must be non-null and
appropriate for the image's SampleModel.
The resulting BufferedImage will contain the
full requested area, but will always have its top-left corner
translated (0, 0) as required by the BufferedImage
interface.
rect - The Rectangle of the image to be
copied, or null to indicate that the
entire image is to be copied.cm - A ColorModel used to override
this image's ColorModel, or null.
The caller is responsible for supplying a
ColorModel that is compatible with the image's
SampleModel.IllegalArgumentException - If an incompatible, non-null
ColorModel is supplied.IllegalArgumentException - If no ColorModel is
supplied, and the image ColorModel is
null.public BufferedImage getAsBufferedImage()
BufferedImage. The image's
ColorModel must be non-null, and
appropriate for the image's SampleModel.BufferedImagepublic Graphics getGraphics()
Graphics object that may be used to draw
into this image. By default, an
IllegalAccessError is thrown. Subclasses that
support such drawing, such as TiledImage, may
override this method to return a suitable Graphics
object.
public abstract Raster getTile(int tileX,
int tileY)
tileX, tileY) as a
Raster. Note that tileX and
tileY are indices into the tile array, not pixel
locations.
Subclasses must override this method to return a
non-null value for all tile indices between
getMinTile{X,Y} and getMaxTile{X,Y},
inclusive. Tile indices outside of this region should result
in a return value of null.
getTile in interface RenderedImagetileX - The X index of the requested tile in the tile array.tileY - The Y index of the requested tile in the tile array.public Raster[] getTiles(Point[] tileIndices)
Rasters indicated by the
tileIndices array. This call allows certain
PlanarImage subclasses such as
OpImage to take advantage of the knowledge that
multiple tiles are requested at once.tileIndices - An array of Points representing tile indices.Raster containing the tiles
corresponding to the given tile indices.IllegalArgumentException - If tileIndices is
null.public Raster[] getTiles()
public TileRequest queueTiles(Point[] tileIndices)
The TileScheduler of the default instance of the
JAI class is used to process the tiles. If this
TileScheduler has a positive parallelism this
method will be non-blocking. The event source parameter passed to
such listeners will be the TileScheduler and the image
parameter will be this image.
tileIndices - A list of tile indices indicating which tiles
to schedule for computation.IllegalArgumentException - If tileIndices is
null.
public void cancelTiles(TileRequest request,
Point[] tileIndices)
The cancellation request is forwarded to the
TileScheduler of the default instance of the
JAI class.
request - The request for which tiles are to be cancelled.tileIndices - The tiles to be cancelled; may be null.
Any tiles not actually in the TileRequest will be
ignored.IllegalArgumentException - If request is
null.public void prefetchTiles(Point[] tileIndices)
The TileScheduler of the default instance of the
JAI class is used to prefetch the tiles. If this
TileScheduler has a positive prefetch parallelism
this method will be non-blocking.
tileIndices - A list of tile indices indicating which tiles
to prefetch.IllegalArgumentException - If tileIndices is
null.public void dispose()
PlanarImage defines this method to remove the
image being disposed from the list of sinks in all of its
source images. Subclasses should call
super.dispose() in their dispose
methods, if any.
The results of referencing an image after a call to
dispose() are undefined.
protected void finalize()
throws Throwable
PlanarImage defines this method to invoke
the dispose() method.
finalize in class ObjectThrowablepublic String toString()
String which includes the basic information
of this image.toString in class Objectpublic Object getImageID()
PlanarImage.
This UID may be used when the potential redundancy of the value
returned by the hashCode() method is unacceptable.
An example of this is in generating a key for storing image tiles
in a cache.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||