imagecomponent3d.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: ImageComponent3D.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.6 $
 * $Date: 2007/02/09 17:18:03 $
 * $State: Exp $
 */

package javax.media.j3d;

import java.awt.image.BufferedImage;
import java.awt.image.RenderedImage;

/**
 * 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:
 *
 * <p>
 * <ul>
 * <code>
 * BufferedImage bi;<br>
 * RenderedImage ri = bi;<br>
 * ImageComponent3D ic;<br>
 * <p>
 * // Set image 0 to the specified BufferedImage<br>
 * ic.set(0, bi);<br>
 * <p>
 * // Set image 0 to the specified RenderedImage<br>
 * ic.set(0, ri);<br>
 * </code>
 * </ul>
 *
 */
public class ImageComponent3D extends ImageComponent {

    // non-public, no parameter constructor
    ImageComponent3D() {}
    
    /**
     * 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:
     * <ul>
     * array of images : null<br>
     * imageClass : ImageClass.BUFFERED_IMAGE<br>
     * </ul>
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA, etc.
     * @param width the number of columns of pixels in this image component
     * object
     * @param height the number of rows of pixels in this image component
     * object
     * @param depth the number of 2D slices in this image component object
     * @exception IllegalArgumentException if format is invalid, or if
     * any of width, height, or depth are not positive.
     */
    public ImageComponent3D(int		format,
			    int		width,
			    int		height,
			    int		depth) {

        ((ImageComponent3DRetained)this.retained).processParams(format, width, height, depth);
    }

    /**
     * Constructs a 3D image component object using the specified format,
     * and the BufferedImage array.
     * The image class is set to ImageClass.BUFFERED_IMAGE.
     * Default values are used for all other parameters.
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA etc.
     * @param images an array of BufferedImage objects.  The
     * first image in the array determines the width and height of this
     * ImageComponent3D.
     *
     * @exception IllegalArgumentException if format is invalid, or if
     * the width or height of the first image are not positive.
     */
    public ImageComponent3D(int format, BufferedImage[] images) {
        ((ImageComponent3DRetained)this.retained).processParams(format, 
		images[0].getWidth(null), images[0].getHeight(null), images.length);
        for (int i=0; i<images.length; i++) {
            ((ImageComponent3DRetained)this.retained).set(i, images[i]);
        }
    }

    /**
     * Constructs a 3D image component object using the specified format,
     * and the RenderedImage array.
     * The image class is set to ImageClass.BUFFERED_IMAGE.
     * Default values are used for all other parameters.
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA etc.
     * @param images an array of RenderedImage objects.  The
     * first image in the array determines the width and height of this
     * ImageComponent3D.
     *
     * @exception IllegalArgumentException if format is invalid, or if
     * the width or height of the first image are not positive.
     *
     * @since Java 3D 1.2
     */
    public ImageComponent3D(int format, RenderedImage[] images) {

        ((ImageComponent3DRetained)this.retained).processParams(format, 
	images[0].getWidth(), images[0].getHeight(), images.length);
        for (int i=0; i<images.length; i++) {
            ((ImageComponent3DRetained)this.retained).set(i, images[i]);
        }
    }

    /**
     * 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.
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA, etc.
     * @param width the number of columns of pixels in this image component
     * object
     * @param height the number of rows of pixels in this image component
     * object
     * @param depth the number of 2D slices in this image component object
     * @param byReference a flag that indicates whether the data is copied
     * into this image component object or is accessed by reference.
     * @param 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.
     *
     * @exception IllegalArgumentException if format is invalid, or if
     * any of width, height, or depth are not positive.
     *
     * @since Java 3D 1.2
     */
    public ImageComponent3D(int		format,
			    int		width,
			    int		height,
			    int		depth,
			    boolean	byReference,
			    boolean	yUp) {

 	((ImageComponentRetained)this.retained).setByReference(byReference);
 	((ImageComponentRetained)this.retained).setYUp(yUp);
 	((ImageComponent3DRetained)this.retained).processParams(format, width, height, depth);
    }

    /**
     * Constructs a 3D image component object using the specified format,
     * BufferedImage array, byReference flag, and yUp flag.
     * The image class is set to ImageClass.BUFFERED_IMAGE.
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA etc.
     * @param images an array of BufferedImage objects.  The
     * first image in the array determines the width and height of this
     * ImageComponent3D.
     * @param byReference a flag that indicates whether the data is copied
     * into this image component object or is accessed by reference.
     * @param 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.
     *
     * @exception IllegalArgumentException if format is invalid, or if
     * the width or height of the first image are not positive.
     *
     * @since Java 3D 1.2
     */
    public ImageComponent3D(int format,
			    BufferedImage[] images,
			    boolean byReference,
			    boolean yUp) {


 	((ImageComponentRetained)this.retained).setByReference(byReference);
 	((ImageComponentRetained)this.retained).setYUp(yUp);
 	((ImageComponent3DRetained)this.retained).processParams(format, 
                images[0].getWidth(null), images[0].getHeight(null), images.length);
 	for (int i=0; i<images.length; i++) {
 	    ((ImageComponent3DRetained)this.retained).set(i, images[i]);
 	}
    }

    /**
     * Constructs a 3D image component object using the specified format,
     * RenderedImage array, byReference flag, and yUp flag.
     * The image class is set to ImageClass.RENDERED_IMAGE if the byReference
     * flag is true and any of the specified RenderedImages is <i>not</i> an
     * instance of BufferedImage. In all other cases, the image class is set to
     * ImageClass.BUFFERED_IMAGE.
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA etc.
     * @param images an array of RenderedImage objects.  The
     * first image in the array determines the width and height of this
     * ImageComponent3D.
     * @param byReference a flag that indicates whether the data is copied
     * into this image component object or is accessed by reference.
     * @param 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.
     * @exception IllegalArgumentException if format is invalid, or if
     * the width or height of the first image are not positive.
     *
     * @since Java 3D 1.2
     */
    public ImageComponent3D(int format,
			    RenderedImage[] images,
			    boolean byReference,
			    boolean yUp) {

 	((ImageComponentRetained)this.retained).setByReference(byReference);
 	((ImageComponentRetained)this.retained).setYUp(yUp);
 	((ImageComponent3DRetained)this.retained).processParams(format, 
                images[0].getWidth(), images[0].getHeight(), images.length);
 	for (int i=0; i<images.length; i++) {
 	    ((ImageComponent3DRetained)this.retained).set(i, images[i]);
 	}
    }

    /**
     * Constructs a 3D image component object using the specified format,
     * NioImageBuffer array, byReference flag, and yUp flag.
     * The image class is set to ImageClass.NIO_IMAGE_BUFFER.
     *
     * @param format the image component format, one of: FORMAT_RGB,
     * FORMAT_RGBA etc.
     * @param images an array of NioImageBuffer objects.  The
     * first image in the array determines the width and height of this
     * ImageComponent3D.
     * @param byReference a flag that indicates whether the data is copied
     * into this image component object or is accessed by reference.
     * @param 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.
     *
     * @exception IllegalArgumentException if format is invalid, or if
     * the width or height of the first image are not positive.
     *
     * @exception IllegalArgumentException if the byReference flag is false.
     *
     * @exception IllegalArgumentException if the yUp flag is false.
     *
     * @exception UnsupportedOperationException this method is not supported
     * for Java 3D 1.5.
     *
     * @since Java 3D 1.5
     */
    public ImageComponent3D(int format,
			    NioImageBuffer[] images,
			    boolean byReference,
			    boolean yUp) {

        
 	throw new UnsupportedOperationException();
        /*
  	((ImageComponentRetained)this.retained).setByReference(byReference);
 	((ImageComponentRetained)this.retained).setYUp(yUp);
 	((ImageComponent3DRetained)this.retained).processParams(format, 
                images[0].getWidth(), images[0].getHeight(), images.length);
 	for (int i=0; i<images.length; i++) {
 	    ((ImageComponent3DRetained)this.retained).set(i, images[i]);
 	}
         */
    }

    /**
     * Retrieves the depth of this 3D image component object.
     *
     * @return the depth of this 3D image component object
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public int getDepth() {
        if (isLiveOrCompiled())
            if(!this.getCapability(ImageComponent.ALLOW_SIZE_READ))
              throw new CapabilityNotSetException(J3dI18N.getString("ImageComponent3D0"));
        return ((ImageComponent3DRetained)this.retained).getDepth();
    }

    /**
     * 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.
     * <p>
     * The image class is set to ImageClass.BUFFERED_IMAGE.
     *
     * @param images array of BufferedImage objects containing the image.
     * The size (width and height) of each image must be the same as the
     * size of the image component, and the length of the images array
     * must equal the depth of the image component.
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     *
     * @exception IllegalArgumentException if the length of the images array is
     * not equal to the depth of this ImageComponent object.
     *