ImageComponent (Java 3D Javadocs 0-SNAPSHOT API)

java.lang.Object
- org.scijava.java3d.SceneGraphObject
- - org.scijava.java3d.NodeComponent
  - - org.scijava.java3d.ImageComponent

Direct Known Subclasses:

ImageComponent2D, ImageComponent3D
```
public abstract class ImageComponent
extends NodeComponent
```
Abstract class that is used to define 2D or 3D ImageComponent classes used in a Java 3D scene graph. This is used for texture images, background images and raster components of Shape3D nodes.
Image data may be passed to this ImageComponent object in one of two ways: by copying the image data into this object or by accessing the image data by reference.
- By Copying: By default, the set and get image methods copy the image data into or out of this ImageComponent object. This is appropriate for many applications, since the application may reuse the RenderedImage object after copying it to the ImageComponent.
- By Reference: A new feature in Java 3D version 1.2 allows image data to be accessed by reference, directly from the RenderedImage object. To use this feature, you need to construct an ImageComponent object with the byReference flag set to true. In this mode, a reference to the input data is saved, but the data itself is not necessarily copied (although it may be, depending on the value of the yUp flag, the format of the ImageComponent, and the format of the RenderedImage). Image data referenced by an ImageComponent object can only be modified via the updateData method. Applications must exercise care not to violate this rule. If any referenced RenderedImage is modified outside the updateData method after it has been passed to an ImageComponent object, the results are undefined. Another restriction in by-reference mode is that if the specified RenderedImage is not an instance of BufferedImage, then this ImageComponent cannot be used for readRaster or off-screen rendering operations, since these operations modify the ImageComponent data.
An image component object also specifies whether the orientation of its image data is "y-up" or "y-down" (the default). Y-up mode causes images to be interpreted as having their origin at the lower left (rather than the default upper left) of a texture or raster image with successive scan lines moving up. This is more consistent with texture mapping data onto a surface, and maps directly into the the way textures are used in OpenGL and other 3D APIs. Setting the yUp flag to true in conjunction with setting the byReference flag to true makes it possible for Java 3D to avoid copying the texture map in some cases.
Note that all color fields are treated as unsigned values, even though Java does not directly support unsigned variables. This means, for example, that an ImageComponent using a format of FORMAT_RGB5 can represent red, green, and blue values between 0 and 31, while an ImageComponent using a format of FORMAT_RGB8 can represent color values between 0 and 255. Even when byte values are used to create a RenderedImage with 8-bit color components, the resulting colors (bytes) are interpreted as if they were unsigned. Values greater than 127 can be assigned to a byte variable using a type cast. For example:
If intValue is greater than 127, then byteVariable will be negative. The correct value will be extracted when it is used (by masking off the upper bits).

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ImageComponent.ImageClass
Used to specify the class of the image being wrapped.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ImageComponent.ImageClass` Used to specify the class of the image being wrapped.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ALLOW_FORMAT_READ` Specifies that this ImageComponent object allows reading its format component information.
`static int`	`ALLOW_IMAGE_READ` Specifies that this ImageComponent object allows reading its image component information.
`static int`	`ALLOW_IMAGE_WRITE` Specifies that this ImageComponent object allows writing its image component information.
`static int`	`ALLOW_SIZE_READ` Specifies that this ImageComponent object allows reading its size component information (width, height, and depth).
`static int`	`FORMAT_CHANNEL8` Specifies that each pixel contains 1 8-bit channel: it can be used for only luminance or only alpha or only intensity.
`static int`	`FORMAT_LUM4_ALPHA4` Specifies that each pixel contains 2 4-bit channels: one each for luminance and alpha.
`static int`	`FORMAT_LUM8_ALPHA8` Specifies that each pixel contains 2 8-bit channels: one each for luminance and alpha.
`static int`	`FORMAT_R3_G3_B2` Specifies that each pixel contains 2 3-bit channels: one each for red, green, and 1 2-bit channel for blue.
`static int`	`FORMAT_RGB` Specifies that each pixel contains 3 8-bit channels: one each for red, green, blue.
`static int`	`FORMAT_RGB4` Specifies that each pixel contains 3 4-bit channels: one each for red, green, blue.
`static int`	`FORMAT_RGB5` Specifies that each pixel contains 3 5-bit channels: one each for red, green, blue.
`static int`	`FORMAT_RGB5_A1` Specifies that each pixel contains 3 5-bit channels: one each for red, green, blue and 1 1-bit channel for alpha.
`static int`	`FORMAT_RGB8` Specifies that each pixel contains 3 8-bit channels: one each for red, green, blue.
`static int`	`FORMAT_RGBA` Specifies that each pixel contains 4 8-bit channels: one each for red, green, blue, alpha.
`static int`	`FORMAT_RGBA4` Specifies that each pixel contains 4 4-bit channels: one each for red, green, blue, alpha.
`static int`	`FORMAT_RGBA8` Specifies that each pixel contains 4 8-bit channels: one each for red, green, blue, alpha.

Constructor Summary

Constructors
Constructor and Description
`ImageComponent(int format, int width, int height)` Constructs an image component object using the specified format, width, and height.
`ImageComponent(int format, int width, int height, boolean byReference, boolean yUp)` Constructs an image component object using the specified format, width, height, byReference flag, and yUp flag.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`int`	`getFormat()` Retrieves the format of this image component object.
`int`	`getHeight()` Retrieves the height of this image component object.
`ImageComponent.ImageClass`	`getImageClass()` Retrieves the image class of this ImageComponent object.
`int`	`getWidth()` Retrieves the width of this image component object.
`boolean`	`isByReference()` Retrieves the data access mode for this ImageComponent object.
`boolean`	`isYUp()` Retrieves the y-orientation for this ImageComponent object.
`void`	`setYUp(boolean yUp)` Deprecated. as of Java 3D 1.5, the yUp flag should only be set at object construction time.

Methods inherited from class org.scijava.java3d.NodeComponent
cloneNodeComponent, cloneNodeComponent, duplicateNodeComponent, duplicateNodeComponent, getDuplicateOnCloneTree, setDuplicateOnCloneTree

Methods inherited from class org.scijava.java3d.SceneGraphObject
clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString, updateNodeReferences

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - FORMAT_RGB
```
public static final int FORMAT_RGB
```
    Specifies that each pixel contains 3 8-bit channels: one each for red, green, blue. Same as FORMAT_RGB8.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGBA
```
public static final int FORMAT_RGBA
```
    Specifies that each pixel contains 4 8-bit channels: one each for red, green, blue, alpha. Same as FORMAT_RGBA8.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGB8
```
public static final int FORMAT_RGB8
```
    Specifies that each pixel contains 3 8-bit channels: one each for red, green, blue. Same as FORMAT_RGB.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGBA8
```
public static final int FORMAT_RGBA8
```
    Specifies that each pixel contains 4 8-bit channels: one each for red, green, blue, alpha. Same as FORMAT_RGBA.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGB5
```
public static final int FORMAT_RGB5
```
    Specifies that each pixel contains 3 5-bit channels: one each for red, green, blue.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGB5_A1
```
public static final int FORMAT_RGB5_A1
```
    Specifies that each pixel contains 3 5-bit channels: one each for red, green, blue and 1 1-bit channel for alpha.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGB4
```
public static final int FORMAT_RGB4
```
    Specifies that each pixel contains 3 4-bit channels: one each for red, green, blue.
    
    See Also:
    
    Constant Field Values
  - FORMAT_RGBA4
```
public static final int FORMAT_RGBA4
```
    Specifies that each pixel contains 4 4-bit channels: one each for red, green, blue, alpha.
    
    See Also:
    
    Constant Field Values
  - FORMAT_LUM4_ALPHA4
```
public static final int FORMAT_LUM4_ALPHA4
```
    Specifies that each pixel contains 2 4-bit channels: one each for luminance and alpha.
    
    See Also:
    
    Constant Field Values
  - FORMAT_LUM8_ALPHA8
```
public static final int FORMAT_LUM8_ALPHA8
```
    Specifies that each pixel contains 2 8-bit channels: one each for luminance and alpha.
    
    See Also:
    
    Constant Field Values
  - FORMAT_R3_G3_B2
```
public static final int FORMAT_R3_G3_B2
```
    Specifies that each pixel contains 2 3-bit channels: one each for red, green, and 1 2-bit channel for blue.
    
    See Also:
    
    Constant Field Values
  - FORMAT_CHANNEL8
```
public static final int FORMAT_CHANNEL8
```
    Specifies that each pixel contains 1 8-bit channel: it can be used for only luminance or only alpha or only intensity.
    
    See Also:
    
    Constant Field Values
  - ALLOW_SIZE_READ
```
public static final int ALLOW_SIZE_READ
```
    Specifies that this ImageComponent object allows reading its size component information (width, height, and depth).
    
    See Also:
    
    Constant Field Values
  - ALLOW_FORMAT_READ
```
public static final int ALLOW_FORMAT_READ
```
    Specifies that this ImageComponent object allows reading its format component information.
    
    See Also:
    
    Constant Field Values
  - ALLOW_IMAGE_READ
```
public static final int ALLOW_IMAGE_READ
```
    Specifies that this ImageComponent object allows reading its image component information.
    
    See Also:
    
    Constant Field Values
  - ALLOW_IMAGE_WRITE
```
public static final int ALLOW_IMAGE_WRITE
```
    Specifies that this ImageComponent object allows writing its image component information.
    
    Since:
    
    Java 3D 1.3
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ImageComponent
```
public ImageComponent(int format,
                      int width,
                      int height)
```
    Constructs an image component object using the specified format, width, and height. Default values are used for all other parameters. The default values are as follows:
    Parameters:
    
    format - the image component format, one of: FORMAT_RGB, FORMAT_RGBA etc.
    
    width - the number of columns of pixels in this image component object
    
    height - the number of rows of pixels in this image component object
    
    Throws:
    
    IllegalArgumentException - if format is invalid, or if width or height are not positive.
  - ImageComponent
```
public ImageComponent(int format,
                      int width,
                      int height,
                      boolean byReference,
                      boolean yUp)
```
    Constructs an image component object using the specified format, width, height, byReference flag, and yUp flag.
    
    Parameters:
    
    format - the image component format, one of: FORMAT_RGB, FORMAT_RGBA etc.
    
    width - the number of columns of pixels in this image component object
    
    height - the number of rows of pixels in this image component object
    
    byReference - a flag that indicates whether the data is copied into this image component object or is accessed by reference.
    
    yUp - a flag that indicates the y-orientation of this image component. If yUp is set to true, the origin of the image is the lower left; otherwise, the origin of the image is the upper left.
    
    Throws:
    
    IllegalArgumentException - if format is invalid, or if width or height are not positive.
    
    Since:
    
    Java 3D 1.2
- Method Detail
  - getWidth
```
public int getWidth()
```
    Retrieves the width of this image component object.
    
    Returns:
    
    the width of this image component object
    
    Throws:
    
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
  - getHeight
```
public int getHeight()
```
    Retrieves the height of this image component object.
    
    Returns:
    
    the height of this image component object
    
    Throws:
    
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
  - getFormat
```
public int getFormat()
```
    Retrieves the format of this image component object.
    
    Returns:
    
    the format of this image component object
    
    Throws:
    
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph
  - isByReference
```
public boolean isByReference()
```
    Retrieves the data access mode for this ImageComponent object.
    
    Returns:
    
    true if the data access mode for this ImageComponent object is by-reference; false if the data access mode is by-copying.
    
    Since:
    
    Java 3D 1.2
  - setYUp
```
public void setYUp(boolean yUp)
```
    Deprecated. as of Java 3D 1.5, the yUp flag should only be set at object construction time.
    
    Sets the y-orientation of this ImageComponent object to y-up or y-down.
    
    Parameters:
    
    yUp - a flag that indicates the y-orientation of this image component. If yUp is set to true, the origin of the image is the lower left; otherwise, the origin of the image is the upper left.
    
    Throws:
    
    RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.
    
    IllegalStateException - if the image class of this object is ImageClass.NIO_IMAGE_BUFFER.
    
    Since:
    
    Java 3D 1.2
  - isYUp
```
public boolean isYUp()
```
    Retrieves the y-orientation for this ImageComponent object.
    
    Returns:
    
    true if the y-orientation of this ImageComponent object is y-up; false if the y-orientation of this ImageComponent object is y-down.
    
    Since:
    
    Java 3D 1.2
  - getImageClass
```
public ImageComponent.ImageClass getImageClass()
```
    Retrieves the image class of this ImageComponent object.
    
    Returns:
    
    the image class of this ImageComponent, one of: ImageClass.BUFFERED_IMAGE, ImageClass.RENDERED_IMAGE, or ImageClass.NIO_IMAGE_BUFFER.
    
    Since:
    
    Java 3D 1.5

Class ImageComponent

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.scijava.java3d.NodeComponent

Methods inherited from class org.scijava.java3d.SceneGraphObject

Methods inherited from class java.lang.Object

Field Detail

FORMAT_RGB

FORMAT_RGBA

FORMAT_RGB8

FORMAT_RGBA8

FORMAT_RGB5

FORMAT_RGB5_A1

FORMAT_RGB4

FORMAT_RGBA4

FORMAT_LUM4_ALPHA4

FORMAT_LUM8_ALPHA8

FORMAT_R3_G3_B2

FORMAT_CHANNEL8

ALLOW_SIZE_READ

ALLOW_FORMAT_READ

ALLOW_IMAGE_READ

ALLOW_IMAGE_WRITE

Constructor Detail

ImageComponent

ImageComponent

Method Detail

getWidth

getHeight

getFormat

isByReference

setYUp

isYUp

getImageClass