SimpleRenderedImage
Date: 2016-04-28

org.apache.xmlgraphics.image.codec.util

## Class SimpleRenderedImage

- java.lang.Object
- - org.apache.xmlgraphics.image.codec.util.SimpleRenderedImage

- All Implemented Interfaces:
    java.awt.image.RenderedImage
  Direct Known Subclasses:
    SingleTileRenderedImage

      public abstract class SimpleRenderedImage
      extends java.lang.Object
      implements java.awt.image.RenderedImage

  A simple class implemented the `RenderedImage` interface. Only the `getTile()` method needs to be implemented by subclasses. The instance variables must also be filled in properly.

  Normally in JAI `PlanarImage` is used for this purpose, but in the interest of modularity the use of `PlanarImage` has been avoided.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.awt.image.ColorModel` | `colorModel` The image's ColorModel.
    `protected int` | `height` The image's height in pixels.
    `protected int` | `minX` The X coordinate of the image's upper-left pixel.
    `protected int` | `minY` The Y coordinate of the image's upper-left pixel.
    `protected java.util.Map` | `properties` A Hashtable containing the image properties.
    `protected java.awt.image.SampleModel` | `sampleModel` The image's SampleModel.
    `protected int` | `tileGridXOffset` The X coordinate of the upper-left pixel of tile (0, 0).
    `protected int` | `tileGridYOffset` The Y coordinate of the upper-left pixel of tile (0, 0).
    `protected int` | `tileHeight` The height of a tile.
    `protected int` | `tileWidth` The width of a tile.
    `protected int` | `width` The image's width in pixels.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleRenderedImage()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `convertXToTileX(int x)` Converts a pixel's X coordinate into a horizontal tile index.
    `static int` | `convertXToTileX(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` | `convertYToTileY(int y)` Converts a pixel's Y coordinate into a vertical tile index.
    `static int` | `convertYToTileY(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.
    `java.awt.image.WritableRaster` | `copyData(java.awt.image.WritableRaster dest)` Copies an arbitrary rectangular region of the RenderedImage into a caller-supplied WritableRaster.
    `java.awt.Rectangle` | `getBounds()` Returns a Rectangle indicating the image bounds.
    `java.awt.image.ColorModel` | `getColorModel()` Returns the ColorModel of the image.
    `java.awt.image.Raster` | `getData()` Returns the entire image in a single Raster.
    `java.awt.image.Raster` | `getData(java.awt.Rectangle bounds)` Returns an arbitrary rectangular region of the RenderedImage in a Raster.
    `int` | `getHeight()` Returns the height of the image.
    `int` | `getMaxTileX()` Returns the horizontal index of the rightmost column of tiles.
    `int` | `getMaxTileY()` Returns the vertical index of the bottom row of tiles.
    `int` | `getMaxX()` Returns the X coordinate of the column immediatetely to the right of the rightmost column of the image.
    `int` | `getMaxY()` Returns the Y coordinate of the row immediately below the bottom row of the image.
    `int` | `getMinTileX()` Returns the horizontal index of the leftmost column of tiles.
    `int` | `getMinTileY()` Returns the vertical index of the uppermost row of tiles.
    `int` | `getMinX()` Returns the X coordinate of the leftmost column of the image.
    `int` | `getMinY()` Returns the X coordinate of the uppermost row of the image.
    `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.
    `java.lang.Object` | `getProperty(java.lang.String name)` Gets a property from the property set of this image.
    `java.lang.String[]` | `getPropertyNames()` Returns a list of the properties recognized by this image.
    `java.lang.String[]` | `getPropertyNames(java.lang.String prefix)` Returns an array of `String`s recognized as names by this property source that begin with the supplied prefix.
    `java.awt.image.SampleModel` | `getSampleModel()` Returns the SampleModel of the image.
    `java.util.Vector` | `getSources()`
    `int` | `getTileGridXOffset()` Returns the X coordinate of the upper-left pixel of tile (0, 0).
    `int` | `getTileGridYOffset()` Returns the Y coordinate of the upper-left pixel of tile (0, 0).
    `int` | `getTileHeight()` Returns the height of a tile.
    `int` | `getTileWidth()` Returns the width of a tile.
    `int` | `getWidth()` Returns the width of the image.
    `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.awt.image.RenderedImage

      `getTile`

- - ### Field Detail

    - #### minX

          protected int minX

      The X coordinate of the image's upper-left pixel.

    - #### minY

          protected int minY

      The Y coordinate of the image's upper-left pixel.

    - #### width

          protected int width

      The image's width in pixels.

    - #### height

          protected int height

      The image's height in pixels.

    - #### tileWidth

          protected int tileWidth

      The width of a tile.

    - #### tileHeight

          protected int tileHeight

      The height of a tile.

    - #### tileGridXOffset

          protected int tileGridXOffset

      The X coordinate of the upper-left pixel of tile (0, 0).

    - #### tileGridYOffset

          protected int tileGridYOffset

      The Y coordinate of the upper-left pixel of tile (0, 0).

    - #### sampleModel

          protected java.awt.image.SampleModel sampleModel

      The image's SampleModel.

    - #### colorModel

          protected java.awt.image.ColorModel colorModel

      The image's ColorModel.

    - #### properties

          protected java.util.Map properties

      A Hashtable containing the image properties.

  - ### Constructor Detail

    - #### SimpleRenderedImage

          public SimpleRenderedImage()

  - ### Method Detail

    - #### getMinX

          public int getMinX()

      Returns the X coordinate of the leftmost column of the image.
      Specified by:
        `getMinX` in interface `java.awt.image.RenderedImage`

    - #### getMaxX

          public final int getMaxX()

      Returns the X coordinate of the column immediatetely to the right of the rightmost column of the image. getMaxX() is implemented in terms of getMinX() and getWidth() and so does not need to be implemented by subclasses.

    - #### getMinY

          public int getMinY()

      Returns the X coordinate of the uppermost row of the image.
      Specified by:
        `getMinY` in interface `java.awt.image.RenderedImage`

    - #### getMaxY

          public final int getMaxY()

      Returns the Y coordinate of the row immediately below the bottom row of the image. getMaxY() is implemented in terms of getMinY() and getHeight() and so does not need to be implemented by subclasses.

    - #### getWidth

          public int getWidth()

      Returns the width of the image.
      Specified by:
        `getWidth` in interface `java.awt.image.RenderedImage`

    - #### getHeight

          public int getHeight()

      Returns the height of the image.
      Specified by:
        `getHeight` in interface `java.awt.image.RenderedImage`

    - #### getBounds

          public java.awt.Rectangle getBounds()

      Returns a Rectangle indicating the image bounds.

    - #### getTileWidth

          public int getTileWidth()

      Returns the width of a tile.
      Specified by:
        `getTileWidth` in interface `java.awt.image.RenderedImage`

    - #### getTileHeight

          public int getTileHeight()

      Returns the height of a tile.
      Specified by:
        `getTileHeight` in interface `java.awt.image.RenderedImage`

    - #### getTileGridXOffset

          public int getTileGridXOffset()

      Returns the X coordinate of the upper-left pixel of tile (0, 0).
      Specified by:
        `getTileGridXOffset` in interface `java.awt.image.RenderedImage`

    - #### getTileGridYOffset

          public int getTileGridYOffset()

      Returns the Y coordinate of the upper-left pixel of tile (0, 0).
      Specified by:
        `getTileGridYOffset` in interface `java.awt.image.RenderedImage`

    - #### getMinTileX

          public int getMinTileX()

      Returns the horizontal index of the leftmost column of tiles. getMinTileX() is implemented in terms of getMinX() and so does not need to be implemented by subclasses.
      Specified by:
        `getMinTileX` in interface `java.awt.image.RenderedImage`

    - #### getMaxTileX

          public int getMaxTileX()

      Returns the horizontal index of the rightmost column of tiles. getMaxTileX() is implemented in terms of getMaxX() and so does not need to be implemented by subclasses.

    - #### getNumXTiles

          public int getNumXTiles()

      Returns the number of tiles along the tile grid in the horizontal direction. getNumXTiles() is implemented in terms of getMinTileX() and getMaxTileX() and so does not need to be implemented by subclasses.
      Specified by:
        `getNumXTiles` in interface `java.awt.image.RenderedImage`

    - #### getMinTileY

          public int getMinTileY()

      Returns the vertical index of the uppermost row of tiles. getMinTileY() is implemented in terms of getMinY() and so does not need to be implemented by subclasses.
      Specified by:
        `getMinTileY` in interface `java.awt.image.RenderedImage`

    - #### getMaxTileY

          public int getMaxTileY()

      Returns the vertical index of the bottom row of tiles. getMaxTileY() is implemented in terms of getMaxY() and so does not need to be implemented by subclasses.

    - #### getNumYTiles

          public int getNumYTiles()

      Returns the number of tiles along the tile grid in the vertical direction. getNumYTiles() is implemented in terms of getMinTileY() and getMaxTileY() and so does not need to be implemented by subclasses.
      Specified by:
        `getNumYTiles` in interface `java.awt.image.RenderedImage`

    - #### getSampleModel

          public java.awt.image.SampleModel getSampleModel()

      Returns the SampleModel of the image.
      Specified by:
        `getSampleModel` in interface `java.awt.image.RenderedImage`

    - #### getColorModel

          public java.awt.image.ColorModel getColorModel()

      Returns the ColorModel of the image.
      Specified by:
        `getColorModel` in interface `java.awt.image.RenderedImage`

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String name)

      Gets a property from the property set of this image. If the property name is not recognized, `null` will be returned.
      Specified by:
        `getProperty` in interface `java.awt.image.RenderedImage`
      Parameters:
        `name` - the name of the property to get, as a `String`.
      Returns:
        a reference to the property `Object`, or the value `null`

    - #### getPropertyNames

          public java.lang.String[] getPropertyNames()

      Returns a list of the properties recognized by this image. If no properties are available, an empty String[] will be returned.
      Specified by:
        `getPropertyNames` in interface `java.awt.image.RenderedImage`
      Returns:
        an array of `String`s representing valid property names.

    - #### getPropertyNames

          public java.lang.String[] getPropertyNames(java.lang.String prefix)

      Returns an array of `String`s 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.

      Returns:
        an array of `String`s giving the valid property names (can be null).

    - #### convertXToTileX

          public static int convertXToTileX(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.

    - #### convertYToTileY

          public static int convertYToTileY(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.

    - #### convertXToTileX

          public int convertXToTileX(int x)

      Converts a pixel's X coordinate into a horizontal tile index. This is a convenience method. No attempt is made to detect out-of-range coordinates.
      Parameters:
        `x` - the X coordinate of a pixel.
      Returns:
        the X index of the tile containing the pixel.

    - #### convertYToTileY

          public int convertYToTileY(int y)

      Converts a pixel's Y coordinate into a vertical tile index. This is a convenience method. No attempt is made to detect out-of-range coordinates.
      Parameters:
        `y` - the Y coordinate of a pixel.
      Returns:
        the Y index of the tile containing the pixel.

    - #### tileXToX

          public 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.

    - #### tileYToY

          public 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.

    - #### tileXToX

          public int tileXToX(int tx)

      Converts a horizontal tile index into the X coordinate of its upper left pixel. This is a convenience method. No attempt is made to detect out-of-range indices.
      Parameters:
        `tx` - the horizontal index of a tile.
      Returns:
        the X coordinate of the tile's upper left pixel.

    - #### tileYToY

          public int tileYToY(int ty)

      Converts a vertical tile index into the Y coordinate of its upper left pixel. This is a convenience method. No attempt is made to detect out-of-range indices.
      Parameters:
        `ty` - the vertical index of a tile.
      Returns:
        the Y coordinate of the tile's upper left pixel.

    - #### getSources

          public java.util.Vector getSources()

      Specified by:
        `getSources` in interface `java.awt.image.RenderedImage`

    - #### getData

          public java.awt.image.Raster getData()

      Returns the entire image in a single Raster. For images with multiple tiles this will require making a copy.

      The returned Raster is semantically a copy. This means that updates to the source image will not be reflected in the returned Raster. For non-writable (immutable) source 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 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.

      Specified by:
        `getData` in interface `java.awt.image.RenderedImage`
      Returns:
        a Raster containing a copy of this image's data.

    - #### getData

          public java.awt.image.Raster getData(java.awt.Rectangle bounds)

      Returns an arbitrary rectangular region of the RenderedImage in a Raster. The rectangle of interest will be clipped against the image bounds.

      The returned Raster is semantically a copy. This means that updates to the source image will not be reflected in the returned Raster. For non-writable (immutable) source 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 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.

      Specified by:
        `getData` in interface `java.awt.image.RenderedImage`
      Parameters:
        `bounds` - the region of the RenderedImage to be returned.

    - #### copyData

          public java.awt.image.WritableRaster copyData(java.awt.image.WritableRaster dest)

      Copies an arbitrary rectangular region of the RenderedImage into a caller-supplied WritableRaster. The region to be computed is determined by clipping the bounds of the supplied WritableRaster against the bounds of the image. The supplied WritableRaster must have a SampleModel that is compatible with that of the image.

      If the raster argument is null, the entire image will be copied into a newly-created WritableRaster with a SampleModel that is compatible with that of the image.

      Specified by:
        `copyData` in interface `java.awt.image.RenderedImage`
      Parameters:
        `dest` - a WritableRaster to hold the returned portion of the image.
      Returns:
        a reference to the supplied WritableRaster, or to a new WritableRaster if the supplied one was null.