Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

java.awt.image
Class Raster

java.lang.Object
  java.awt.image.Raster

Direct Known Subclasses:

WritableRaster

public class Raster

extends java.lang.Object

A class representing a rectangular array of pixels. A Raster encapsulates a DataBuffer that stores the sample values and a SampleModel that describes how to locate a given sample value in a DataBuffer.

A Raster defines values for pixels occupying a particular rectangular area of the plane, not necessarily including (0, 0). The rectangle, known as the Raster's bounding rectangle and available by means of the getBounds method, is defined by minX, minY, width, and height values. The minX and minY values define the coordinate of the upper left corner of the Raster. References to pixels outside of the bounding rectangle may result in an exception being thrown, or may result in references to unintended elements of the Raster's associated DataBuffer. It is the user's responsibility to avoid accessing such pixels.

A Raster may share a DataBuffer with another Raster either by explicit construction or by the use of the createChild method.

A SampleModel describes how samples of a Raster are stored in the primitive array elements of a DataBuffer. The SampleModel also controls whether samples are sign extended, allowing unsigned data to be stored in signed Java data types such as byte, short, and int.

Although a Raster may live anywhere in the plane, a SampleModel makes use of a simple coordinate system that starts at (0, 0). A Raster therefore contains a translation factor that allows pixel locations to be mapped between the Raster's coordinate system and that of the SampleModel.

All constructors are protected.

Restrictions

Subclasses of Raster that are instantiated via the protected constructors may only accept DataBuffer and SampleModel system instances, those created internally and returned using accessor method calls such as, getDataBuffer() and BufferedImage.getSampleModel(). Instances of DataBuffer and SampleModel created directly through invocation of the SampleModel and DataBuffer constuctors when passed in to the protected constructors will result in an IllegalArgumentException.

See Also:

DataBuffer, SampleModel, SinglePixelPackedSampleModel

Field Summary

protected DataBuffer	dataBuffer The DataBuffer that stores the image data.
protected int	height The height of this Raster.
protected int	minX The X coordinate of the upper-left pixel of this Raster.
protected int	minY The Y coordinate of the upper-left pixel of this Raster.
protected int	numBands The number of bands in the Raster.
protected int	numDataElements The number of DataBuffer data elements per pixel.
protected Raster	parent The parent of this Raster, or null.
protected SampleModel	sampleModel The SampleModel that describes how pixels from this Raster are stored in the DataBuffer.
protected int	sampleModelTranslateX The X translation from the coordinate space of the Raster's SampleModel to that of the Raster.
protected int	sampleModelTranslateY The Y translation from the coordinate space of the Raster's SampleModel to that of the Raster.
protected int	width The width of this Raster.

Constructor Summary

protected	Raster(SampleModel sampleModel, DataBuffer dataBuffer, Point origin) Constructs a Raster with the given SampleModel and DataBuffer.
protected	Raster(SampleModel sampleModel, DataBuffer dataBuffer, Rectangle aRegion, Point sampleModelTranslate, Raster parent) Constructs a Raster with the given SampleModel, DataBuffer, and parent.
protected	Raster(SampleModel sampleModel, Point origin) Constructs a Raster with the given SampleModel.

Method Summary

Raster	createChild(int parentX, int parentY, int width, int height, int childMinX, int childMinY, int[] bandList) Returns a new Raster which shares all or part of this Raster's DataBuffer.
Rectangle	getBounds() Returns the bounding Rectangle of this Raster.
DataBuffer	getDataBuffer() Returns the DataBuffer associated with this Raster.
int	getHeight() Returns the height in pixels of the Raster.
int	getNumBands() Returns the number of bands (samples per pixel) in this Raster.
Raster	getParent() Returns the parent Raster (if any) of this Raster or null.
int[]	getPixels(int x, int y, int w, int h, int[] iArray) Returns an int array containing all samples for a rectangle of pixels, one sample per array element.
SampleModel	getSampleModel() Returns the SampleModel that describes the layout of the image data.
int	getSampleModelTranslateX() Returns the X translation from the coordinate system of the SampleModel to that of the Raster.
int	getSampleModelTranslateY() Returns the Y translation from the coordinate system of the SampleModel to that of the Raster.
int[]	getSamples(int x, int y, int w, int h, int b, int[] iArray) Returns the samples for a specified band for the specified rectangle of pixels in an int array, one sample per array element.
int	getWidth() Returns the width in pixels of the Raster.

Methods inherited from class java.lang.Object

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

Field Detail

sampleModel

protected SampleModel sampleModel

The SampleModel that describes how pixels from this Raster are stored in the DataBuffer.

dataBuffer

protected DataBuffer dataBuffer

The DataBuffer that stores the image data.

minX

protected int minX

The X coordinate of the upper-left pixel of this Raster.

minY

protected int minY

The Y coordinate of the upper-left pixel of this Raster.

width

protected int width

The width of this Raster.

height

protected int height

The height of this Raster.

sampleModelTranslateX

protected int sampleModelTranslateX

The X translation from the coordinate space of the Raster's SampleModel to that of the Raster.

sampleModelTranslateY

protected int sampleModelTranslateY

The Y translation from the coordinate space of the Raster's SampleModel to that of the Raster.

numBands

protected int numBands

The number of bands in the Raster.

numDataElements

protected int numDataElements

The number of DataBuffer data elements per pixel.

parent

protected Raster parent

The parent of this Raster, or null.

Constructor Detail

Raster

protected Raster(SampleModel sampleModel,
                 Point origin)

Constructs a Raster with the given SampleModel. The Raster's upper left corner is origin and it is the same size as the SampleModel. A DataBuffer large enough to describe the Raster is automatically created.

Parameters:

sampleModel - The SampleModel that specifies the layout

origin - The Point that specified the origin

Throws:

RasterFormatException - if computing either origin.x + sampleModel.getWidth() or origin.y + sampleModel.getHeight() results in integer overflow

java.lang.NullPointerException - if either sampleModel or origin is null

java.lang.IllegalArgumentException - for instances of SampleModel and DataBuffer created directly through the invocation of the DataBuffer and SampleModel constructors.

Raster

protected Raster(SampleModel sampleModel,
                 DataBuffer dataBuffer,
                 Point origin)

Constructs a Raster with the given SampleModel and DataBuffer. The Raster's upper left corner is origin and it is the same size as the SampleModel. The DataBuffer is not initialized and must be compatible with SampleModel.

Parameters:

sampleModel - The SampleModel that specifies the layout

dataBuffer - The DataBuffer that contains the image data

origin - The Point that specifies the origin

Throws:

RasterFormatException - if computing either origin.x + sampleModel.getWidth() or origin.y + sampleModel.getHeight() results in integer overflow

java.lang.NullPointerException - if either sampleModel or origin is null

java.lang.IllegalArgumentException - for instances of SampleModel and DataBuffer created directly through the invocation of the DataBuffer and SampleModel constructors.

Raster

protected Raster(SampleModel sampleModel,
                 DataBuffer dataBuffer,
                 Rectangle aRegion,
                 Point sampleModelTranslate,
                 Raster parent)

Constructs a Raster with the given SampleModel, DataBuffer, and parent. aRegion specifies the bounding rectangle of the new Raster. When translated into the base Raster's coordinate system, aRegion must be contained by the base Raster. (The base Raster is the Raster's ancestor which has no parent.) sampleModelTranslate specifies the sampleModelTranslateX and sampleModelTranslateY values of the new Raster. Note that this constructor should generally be called by other constructors or create methods, it should not be used directly.

Parameters:

sampleModel - The SampleModel that specifies the layout

dataBuffer - The DataBuffer that contains the image data

aRegion - The Rectangle that specifies the image area

sampleModelTranslate - The Point that specifies the translation from SampleModel to Raster coordinates

parent - The parent (if any) of this raster

Throws:

java.lang.NullPointerException - if any of sampleModel, dataBuffer, aRegion or sampleModelTranslate is null

RasterFormatException - if aRegion has width or height less than or equal to zero, or computing either aRegion.x + aRegion.width or aRegion.y + aRegion.height results in integer overflow

java.lang.IllegalArgumentException - for instances of SampleModel and DataBuffer created directly through the invocation of the DataBuffer and SampleModel constructors.

Method Detail

getParent

public Raster getParent()

Returns the parent Raster (if any) of this Raster or null.

Returns:

the parent Raster or null.

getSampleModelTranslateX

public final int getSampleModelTranslateX()

Returns the X translation from the coordinate system of the SampleModel to that of the Raster. To convert a pixel's X coordinate from the Raster coordinate system to the SampleModel coordinate system, this value must be subtracted.

Returns:

the X translation from the coordinate space of the Raster's SampleModel to that of the Raster.

getSampleModelTranslateY

public final int getSampleModelTranslateY()

Returns the Y translation from the coordinate system of the SampleModel to that of the Raster. To convert a pixel's Y coordinate from the Raster coordinate system to the SampleModel coordinate system, this value must be subtracted.

Returns:

the Y translation from the coordinate space of the Raster's SampleModel to that of the Raster.

createChild

public Raster createChild(int parentX,
                          int parentY,
                          int width,
                          int height,
                          int childMinX,
                          int childMinY,
                          int[] bandList)

Returns a new Raster which shares all or part of this Raster's DataBuffer. The new Raster will possess a reference to the current Raster, accessible through its getParent() method.

The parentX, parentY, width and height parameters form a Rectangle in this Raster's coordinate space, indicating the area of pixels to be shared. An error will be thrown if this Rectangle is not contained with the bounds of the current Raster.

The new Raster may additionally be translated to a different coordinate system for the plane than that used by the current Raster. The childMinX and childMinY parameters give the new (x, y) coordinate of the upper-left pixel of the returned Raster; the coordinate (childMinX, childMinY) in the new Raster will map to the same pixel as the coordinate (parentX, parentY) in the current Raster.

The new Raster may be defined to contain only a subset of the bands of the current Raster, possibly reordered, by means of the bandList parameter. If bandList is null, it is taken to include all of the bands of the current Raster in their current order.

To create a new Raster that contains a subregion of the current Raster, but shares its coordinate system and bands, this method should be called with childMinX equal to parentX, childMinY equal to parentY, and bandList equal to null.

Parameters:

width - Width of the region starting at (parentX, parentY)

height - Height of the region starting at (parentX, parentY).

bandList - Array of band indices, or null to use all bands

Returns:

a new Raster.

Throws:

RasterFormatException - if the specified subregion is outside of the raster bounds.

RasterFormatException - if width or height is less than or equal to zero, or computing any of parentX + width, parentY + height, childMinX + width, or childMinY + height results in integer overflow

getBounds

public Rectangle getBounds()

Returns the bounding Rectangle of this Raster. This function returns the same information as getMinX/MinY/Width/Height.

Returns:

the bounding box of this Raster.

getWidth

public final int getWidth()

Returns the width in pixels of the Raster.

Returns:

the width of this Raster.

getHeight

public final int getHeight()

Returns the height in pixels of the Raster.

Returns:

the height of this Raster.

getNumBands

public final int getNumBands()

Returns the number of bands (samples per pixel) in this Raster.

Returns:

the number of bands of this Raster.

getDataBuffer

public DataBuffer getDataBuffer()

Returns the DataBuffer associated with this Raster.

Returns:

the DataBuffer of this Raster.

getSampleModel

public SampleModel getSampleModel()

Returns the SampleModel that describes the layout of the image data.

Returns:

the SampleModel of this Raster.

getPixels

public int[] getPixels(int x,
                       int y,
                       int w,
                       int h,
                       int[] iArray)

Returns an int array containing all samples for a rectangle of pixels, one sample per array element. An ArrayIndexOutOfBoundsException may be thrown if the coordinates are not in bounds. However, explicit bounds checking is not guaranteed.

Parameters:

w - Width of the pixel rectangle

h - Height of the pixel rectangle

iArray - An optionally pre-allocated int array

Returns:

the samples for the specified rectangle of pixels.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the coordinates are not in bounds, or if iArray is too small to hold the output.

getSamples

public int[] getSamples(int x,
                        int y,
                        int w,
                        int h,
                        int b,
                        int[] iArray)

Returns the samples for a specified band for the specified rectangle of pixels in an int array, one sample per array element. An ArrayIndexOutOfBoundsException may be thrown if the coordinates are not in bounds. However, explicit bounds checking is not guaranteed.

Parameters:

w - Width of the pixel rectangle

h - Height of the pixel rectangle

b - The band to return

iArray - An optionally pre-allocated int array

Returns:

the samples for the specified band for the specified rectangle of pixels.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the coordinates or the band index are not in bounds, or if iArray is too small to hold the output.