javax.media.j3d
Class ImageComponent3D

java.lang.Object
  |
  +--javax.media.j3d.SceneGraphObject
        |
        +--javax.media.j3d.NodeComponent
              |
              +--javax.media.j3d.ImageComponent
                    |
                    +--javax.media.j3d.ImageComponent3D

public class ImageComponent3D

extends ImageComponent

This class defines a 3D image component. This is used for texture images. Prior to Java 3D 1.2, only BufferedImage objects could be used as the input to an ImageComponent3D object. As of Java 3D 1.2, an ImageComponent3D accepts an array of arbitrary RenderedImage objects (BufferedImage is an implementation of the RenderedImage interface). The methods that set/get a BufferedImage object are left in for compatibility. The new methods that set/get a RenderedImage are a superset of the old methods. In particular, the two set methods in the following example are equivalent:

BufferedImage bi;
RenderedImage ri = bi;
ImageComponent3D ic;


// Set image 0 to the specified BufferedImage
ic.set(0, bi);


// Set image 0 to the specified RenderedImage
ic.set(0, ri);


Fields inherited from class javax.media.j3d.ImageComponent

ALLOW_FORMAT_READ, ALLOW_IMAGE_READ, ALLOW_SIZE_READ, FORMAT_CHANNEL8, FORMAT_LUM4_ALPHA4, FORMAT_LUM8_ALPHA8, FORMAT_R3_G3_B2, FORMAT_RGB, FORMAT_RGB4, FORMAT_RGB5, FORMAT_RGB5_A1, FORMAT_RGB8, FORMAT_RGBA, FORMAT_RGBA4, FORMAT_RGBA8

Constructor Summary

ImageComponent3D(int format, java.awt.image.BufferedImage[] images)
Constructs a 3D image component object using the specified format, and the BufferedImage array.

ImageComponent3D(int format, java.awt.image.BufferedImage[] images, boolean byReference, boolean yUp)
Constructs a 3D image component object using the specified format, BufferedImage array, byReference flag, and yUp flag.

ImageComponent3D(int format, int width, int height, int depth)
Constructs a 3D image component object using the specified format, width, height, and depth.

ImageComponent3D(int format, int width, int height, int depth, boolean byReference, boolean yUp)
Constructs a 3D image component object using the specified format, width, height, depth, byReference flag, and yUp flag.

ImageComponent3D(int format, java.awt.image.RenderedImage[] images)
Constructs a 3D image component object using the specified format, and the RenderedImage array.

ImageComponent3D(int format, java.awt.image.RenderedImage[] images, boolean byReference, boolean yUp)
Constructs a 3D image component object using the specified format, RenderedImage array, byReference flag, and yUp flag.

Method Summary

NodeComponent	cloneNodeComponent() Deprecated. replaced with cloneNodeComponent(boolean forceDuplicate)
int	getDepth() Retrieves the depth of this 3D image component object.
java.awt.image.BufferedImage[]	getImage() Retrieves the images from this ImageComponent3D object.
java.awt.image.BufferedImage	getImage(int index) Retrieves one of the images from this ImageComponent3D object.
java.awt.image.RenderedImage[]	getRenderedImage() Retrieves the images from this ImageComponent3D object.
java.awt.image.RenderedImage	getRenderedImage(int index) Retrieves one of the images from this ImageComponent3D object.
void	set(java.awt.image.BufferedImage[] images) Sets the array of images in this image component to the specified array of BufferedImage objects.
void	set(int index, java.awt.image.BufferedImage image) Sets this image component at the specified index to the specified BufferedImage object.
void	set(int index, java.awt.image.RenderedImage image) Sets this image component at the specified index to the specified RenderedImage object.
void	set(java.awt.image.RenderedImage[] images) Sets the array of images in this image component to the specified array of RenderedImage objects.

Methods inherited from class javax.media.j3d.ImageComponent

getFormat, getHeight, getWidth, isByReference, isYUp, setYUp

Methods inherited from class javax.media.j3d.NodeComponent

cloneNodeComponent, duplicateNodeComponent, duplicateNodeComponent, getDuplicateOnCloneTree, setDuplicateOnCloneTree

Methods inherited from class javax.media.j3d.SceneGraphObject

clearCapability, duplicateSceneGraphObject, getCapability, getUserData, isCompiled, isLive, setCapability, setUserData, updateNodeReferences

Methods inherited from class java.lang.Object

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

Constructor Detail

ImageComponent3D

public ImageComponent3D(int format,
                        int width,
                        int height,
                        int depth)

Constructs a 3D image component object using the specified format, width, height, and depth. Default values are used for all other parameters. The default values are as follows:

array of images : null

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

depth - the number of 2D slices in this image component object

Throws:

java.lang.IllegalArgumentException - if format is invalid, or if any of width, height, or depth are not positive.

ImageComponent3D

public ImageComponent3D(int format,
                        java.awt.image.BufferedImage[] images)

Constructs a 3D image component object using the specified format, and the BufferedImage array. Default values are used for all other parameters.

Parameters:

format - the image component format, one of: FORMAT_RGB, FORMAT_RGBA etc.

image - an array of BufferedImage objects. The first image in the array determines the width and height of this ImageComponent3D.

Throws:

java.lang.IllegalArgumentException - if format is invalid, or if the width or height of the first image are not positive.

ImageComponent3D

public ImageComponent3D(int format,
                        java.awt.image.RenderedImage[] images)

Constructs a 3D image component object using the specified format, and the RenderedImage array. Default values are used for all other parameters.

Parameters:

format - the image component format, one of: FORMAT_RGB, FORMAT_RGBA etc.

image - an array of RenderedImage objects. The first image in the array determines the width and height of this ImageComponent3D.

Throws:

java.lang.IllegalArgumentException - if format is invalid, or if the width or height of the first image are not positive.

Since:

Java 3D 1.2

ImageComponent3D

public ImageComponent3D(int format,
                        int width,
                        int height,
                        int depth,
                        boolean byReference,
                        boolean yUp)

Constructs a 3D image component object using the specified format, width, height, depth, byReference flag, and yUp flag. Default values are used for all other parameters.

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

depth - the number of 2D slices 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:

java.lang.IllegalArgumentException - if format is invalid, or if any of width, height, or depth are not positive.

Since:

Java 3D 1.2

ImageComponent3D

public ImageComponent3D(int format,
                        java.awt.image.BufferedImage[] images,
                        boolean byReference,
                        boolean yUp)

Constructs a 3D image component object using the specified format, BufferedImage array, byReference flag, and yUp flag. Default values are used for all other parameters.

Parameters:

format - the image component format, one of: FORMAT_RGB, FORMAT_RGBA etc.

image - an array of BufferedImage objects. The first image in the array determines the width and height of this ImageComponent3D.

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:

java.lang.IllegalArgumentException - if format is invalid, or if the width or height of the first image are not positive.

Since:

Java 3D 1.2

ImageComponent3D

public ImageComponent3D(int format,
                        java.awt.image.RenderedImage[] images,
                        boolean byReference,
                        boolean yUp)

Constructs a 3D image component object using the specified format, RenderedImage array, byReference flag, and yUp flag. Default values are used for all other parameters.

Parameters:

format - the image component format, one of: FORMAT_RGB, FORMAT_RGBA etc.

image - an array of RenderedImage objects. The first image in the array determines the width and height of this ImageComponent3D.

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:

java.lang.IllegalArgumentException - if format is invalid, or if the width or height of the first image are not positive.

Since:

Java 3D 1.2

Method Detail

getDepth

public int getDepth()

Retrieves the depth of this 3D image component object.

Returns:

the format of this 3D image component object

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

set

public void set(java.awt.image.BufferedImage[] images)

Sets the array of images in this image component to the specified array of BufferedImage objects. If the data access mode is not by-reference, then the BufferedImage data is copied into this object. If the data access mode is by-reference, then a shallow copy of the array of references to the BufferedImage objects is made, but the BufferedImage data is not necessarily copied.

Parameters:

images - array of BufferedImage objects containing the image. The format and size must be the same as the current format in the image component.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

set

public void set(java.awt.image.RenderedImage[] images)

Sets the array of images in this image component to the specified array of RenderedImage objects. If the data access mode is not by-reference, then the RenderedImage data is copied into this object. If the data access mode is by-reference, then a shallow copy of the array of references to the RenderedImage objects is made, but the RenderedImage data is not necessarily copied.

Parameters:

images - array of RenderedImage objects containing the image. The format and size must be the same as the current format in the image component.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

Since:

Java 3D 1.2

set

public void set(int index,
                java.awt.image.BufferedImage image)

Sets this image component at the specified index to the specified BufferedImage object. If the data access mode is not by-reference, then the BufferedImage data is copied into this object. If the data access mode is by-reference, then a reference to the BufferedImage is saved, but the data is not necessarily copied.

Parameters:

index - the image index

images - BufferedImage object containing the image. The format and size must be the same as the current format in this ImageComponent3D object. The index must not exceed the depth of this ImageComponent3D object.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

set

public void set(int index,
                java.awt.image.RenderedImage image)

Sets this image component at the specified index to the specified RenderedImage object. If the data access mode is not by-reference, then the RenderedImage data is copied into this object. If the data access mode is by-reference, then a reference to the RenderedImage is saved, but the data is not necessarily copied.

Parameters:

index - the image index

images - RenderedImage object containing the image. The format and size must be the same as the current format in this ImageComponent3D object. The index must not exceed the depth of this ImageComponent3D object.

Throws:

RestrictedAccessException - if the method is called when this object is part of live or compiled scene graph.

Since:

Java 3D 1.2

getImage

public java.awt.image.BufferedImage[] getImage()

Retrieves the images from this ImageComponent3D object. If the data access mode is not by-reference, then a copy of the images is made. If the data access mode is by-reference, then the references are returned.

Returns:

either a new array of new BufferedImage objects created from the data in this image component, or a new array of references to the BufferedImages that this image component refers to.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

java.lang.IllegalStateException - if the data access mode is by-reference and any image referenced by this ImageComponent3D object is not an instance of BufferedImage.

getRenderedImage

public java.awt.image.RenderedImage[] getRenderedImage()

Retrieves the images from this ImageComponent3D object. If the data access mode is not by-reference, then a copy of the images is made. If the data access mode is by-reference, then the references are returned.

Returns:

either a new array of new RenderedImage objects created from the data in this image component, or a new array of references to the RenderedImages that this image component refers to.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

getImage

public java.awt.image.BufferedImage getImage(int index)

Retrieves one of the images from this ImageComponent3D object. If the data access mode is not by-reference, then a copy of the image is made. If the data access mode is by-reference, then the reference is returned.

Parameters:

index - the index of the image to retrieve

Returns:

either a new BufferedImage object created from the data in this image component, or the BufferedImage object referenced by this image component.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

java.lang.IllegalStateException - if the data access mode is by-reference and the image referenced by this ImageComponent3D object at the specified index is not an instance of BufferedImage.

getRenderedImage

public java.awt.image.RenderedImage getRenderedImage(int index)

Retrieves one of the images from this ImageComponent3D object. If the data access mode is not by-reference, then a copy of the image is made. If the data access mode is by-reference, then the reference is returned.

Parameters:

index - the index of the image to retrieve

Returns:

either a new RenderedImage object created from the data in this image component, or the RenderedImage object referenced by this image component.

Throws:

CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

Since:

Java 3D 1.2

cloneNodeComponent

public NodeComponent cloneNodeComponent()

Deprecated. replaced with cloneNodeComponent(boolean forceDuplicate)

Overrides:

cloneNodeComponent in class NodeComponent