Java Doc for ImageComponent.java in  » 6.0-JDK-Modules » java-3d » javax » media » j3d » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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:

byteVariable = (byte) intValue; // intValue can be > 127

byReference : false
yUp : false