Java tutorial
/* * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Sun designates this * particular file as subject to the "Classpath" exception as provided * by Sun in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, * CA 95054 USA or visit www.sun.com if you need additional information or * have any questions. * */ package javax.media.j3d; import java.awt.Dimension; import java.awt.Point; import javax.vecmath.Point3f; /** * The Raster object extends Geometry to allow drawing a raster image * that is attached to a 3D location in the virtual world. * It contains a 3D point that is defined in the local object * coordinate system of the Shape3D node that references the Raster. * It also contains a type specifier, a clipping mode, a reference to * a ImageComponent2D object and/or a DepthComponent object, an * integer x,y source offset and a size (width, height) to allow * reading or writing a portion of the referenced image, and an * integer x,y destination offset to position the raster relative to * the transformed 3D point. * In addition to being used as a type of geometry for drawing, * a Raster may be used to readback pixel data (color and/or z-buffer) * from the frame buffer in immediate mode. * <p> * The geometric extent of a Raster object is a single 3D point, specified * by the raster position. This means that geometry-based picking or * collision with a Raster object will only intersect the object at * this single point; the 2D raster image is neither pickable * nor collidable. */ public class Raster extends Geometry { /** * Specifies a Raster object with color data. * In this mode, the image reference must point to * a valid ImageComponent object. * * @see #setType */ public static final int RASTER_COLOR = 0x1; /** * Specifies a Raster object with depth (z-buffer) data. * In this mode, the depthImage reference must point to * a valid DepthComponent object. * * @see #setType */ public static final int RASTER_DEPTH = 0x2; /** * Specifies a Raster object with both color and depth (z-buffer) data. * In this mode, the image reference must point to * a valid ImageComponent object, and the depthImage reference * must point to a valid DepthComponent object. * * @see #setType */ public static final int RASTER_COLOR_DEPTH = RASTER_COLOR | RASTER_DEPTH; /** * Specifies that this raster object is not drawn * if the raster position is outside the viewing volume. * In this mode, the raster is not drawn when the transformed * raster position is clipped out, even if part of the raster would * have been visible. This is the default mode. * * @see #setClipMode * * @since Java 3D 1.3 */ public static final int CLIP_POSITION = 0; /** * Specifies that the raster object is clipped as an image after * the raster position has been transformed. In this mode, part * of the raster may be drawn even when the transformed raster * position is clipped out. * * @see #setClipMode * * @since Java 3D 1.3 */ public static final int CLIP_IMAGE = 1; /** * Specifies that this Raster allows reading the position. */ public static final int ALLOW_POSITION_READ = CapabilityBits.RASTER_ALLOW_POSITION_READ; /** * Specifies that this Raster allows writing the position. */ public static final int ALLOW_POSITION_WRITE = CapabilityBits.RASTER_ALLOW_POSITION_WRITE; /** * Specifies that this Raster allows reading the source or * destination offset. */ public static final int ALLOW_OFFSET_READ = CapabilityBits.RASTER_ALLOW_OFFSET_READ; /** * Specifies that this Raster allows writing the source or * destination offset. */ public static final int ALLOW_OFFSET_WRITE = CapabilityBits.RASTER_ALLOW_OFFSET_WRITE; /** * Specifies that this Raster allows reading the image. */ public static final int ALLOW_IMAGE_READ = CapabilityBits.RASTER_ALLOW_IMAGE_READ; /** * Specifies that this Raster allows writing the image. */ public static final int ALLOW_IMAGE_WRITE = CapabilityBits.RASTER_ALLOW_IMAGE_WRITE; /** * Specifies that this Raster allows reading the depth component. */ public static final int ALLOW_DEPTH_COMPONENT_READ = CapabilityBits.RASTER_ALLOW_DEPTH_COMPONENT_READ; /** * Specifies that this Raster allows writing the depth component. */ public static final int ALLOW_DEPTH_COMPONENT_WRITE = CapabilityBits.RASTER_ALLOW_DEPTH_COMPONENT_WRITE; /** * Specifies that this Raster allows reading the size. */ public static final int ALLOW_SIZE_READ = CapabilityBits.RASTER_ALLOW_SIZE_READ; /** * Specifies that this Raster allows writing the size. */ public static final int ALLOW_SIZE_WRITE = CapabilityBits.RASTER_ALLOW_SIZE_WRITE; /** * Specifies that this Raster allows reading the type. */ public static final int ALLOW_TYPE_READ = CapabilityBits.RASTER_ALLOW_TYPE_READ; /** * Specifies that this Raster allows reading the clip mode. * * @since Java 3D 1.3 */ public static final int ALLOW_CLIP_MODE_READ = CapabilityBits.RASTER_ALLOW_CLIP_MODE_READ; /** * Specifies that this Raster allows writing the clip mode. * * @since Java 3D 1.3 */ public static final int ALLOW_CLIP_MODE_WRITE = CapabilityBits.RASTER_ALLOW_CLIP_MODE_WRITE; // Array for setting default read capabilities private static final int[] readCapabilities = { ALLOW_POSITION_READ, ALLOW_OFFSET_READ, ALLOW_IMAGE_READ, ALLOW_DEPTH_COMPONENT_READ, ALLOW_SIZE_READ, ALLOW_TYPE_READ, ALLOW_CLIP_MODE_READ }; /** * Constructs a Raster object with default parameters. * The default values are as follows: * <ul> * type : RASTER_COLOR<br> * clipMode : CLIP_POSITION<br> * position : (0,0,0)<br> * srcOffset : (0,0)<br> * size : (0,0)<br> * dstOffset : (0,0)<br> * image : null<br> * depth component : null<br> * </ul> */ public Raster() { // set default read capabilities setDefaultReadCapabilities(readCapabilities); } /** * Constructs a new Raster object with the specified values. * @param pos the position in object coordinates of the upper-left * corner of the raster * @param type the type of raster object, one of: RASTER_COLOR, * RASTER_DEPTH, or RASTER_COLOR_DEPTH * @param xSrcOffset the x offset within the source array of pixels * at which to start copying * @param ySrcOffset the y offset within the source array of pixels * at which to start copying * @param width the number of columns of pixels to copy * @param height the number of rows of pixels to copy * @param image the ImageComponent2D object containing the * color data * @param depthComponent the DepthComponent object containing the depth * (z-buffer) data * * @exception IllegalArgumentException if the image class of the specified * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER. */ public Raster(Point3f pos, int type, int xSrcOffset, int ySrcOffset, int width, int height, ImageComponent2D image, DepthComponent depthComponent) { // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((RasterRetained) this.retained).setPosition(pos); ((RasterRetained) this.retained).setType(type); ((RasterRetained) this.retained).setSrcOffset(xSrcOffset, ySrcOffset); ((RasterRetained) this.retained).setSize(width, height); ((RasterRetained) this.retained).setImage(image); ((RasterRetained) this.retained).setDepthComponent(depthComponent); } /** * Constructs a new Raster object with the specified values. * @param pos the position in object coordinates of the upper-left * corner of the raster * @param type the type of raster object, one of: RASTER_COLOR, * RASTER_DEPTH, or RASTER_COLOR_DEPTH * @param srcOffset the offset within the source array of pixels * at which to start copying * @param size the width and height of the image to be copied * @param image the ImageComponent2D object containing the * color data * @param depthComponent the DepthComponent object containing the depth * (z-buffer) data * * @exception IllegalArgumentException if the image class of the specified * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER. */ public Raster(Point3f pos, int type, Point srcOffset, Dimension size, ImageComponent2D image, DepthComponent depthComponent) { // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((RasterRetained) this.retained).setPosition(pos); ((RasterRetained) this.retained).setType(type); ((RasterRetained) this.retained).setSrcOffset(srcOffset.x, srcOffset.y); ((RasterRetained) this.retained).setSize(size.width, size.height); ((RasterRetained) this.retained).setImage(image); ((RasterRetained) this.retained).setDepthComponent(depthComponent); } /** * Constructs a new Raster object with the specified values. * @param pos the position in object coordinates of the upper-left * corner of the raster * @param type the type of raster object, one of: RASTER_COLOR, * RASTER_DEPTH, or RASTER_COLOR_DEPTH * @param clipMode the clipping mode of the raster object, one of: * CLIP_POSITION or CLIP_IMAGE * @param srcOffset the offset within the source array of pixels * at which to start copying * @param size the width and height of the image to be copied * @param dstOffset the destination pixel offset of the upper-left * corner of the rendered image relative to the transformed position * @param image the ImageComponent2D object containing the * color data * @param depthComponent the DepthComponent object containing the depth * (z-buffer) data * * @exception IllegalArgumentException if the image class of the specified * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER. * * @since Java 3D 1.3 */ public Raster(Point3f pos, int type, int clipMode, Point srcOffset, Dimension size, Point dstOffset, ImageComponent2D image, DepthComponent depthComponent) { // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((RasterRetained) this.retained).setPosition(pos); ((RasterRetained) this.retained).setType(type); ((RasterRetained) this.retained).setClipMode(clipMode); ((RasterRetained) this.retained).setSrcOffset(srcOffset.x, srcOffset.y); ((RasterRetained) this.retained).setSize(size.width, size.height); ((RasterRetained) this.retained).setDstOffset(dstOffset.x, dstOffset.y); ((RasterRetained) this.retained).setImage(image); ((RasterRetained) this.retained).setDepthComponent(depthComponent); } /** * Creates the retained mode Raster object that this * Raster object will point to. */ @Override void createRetained() { retained = new RasterRetained(); retained.setSource(this); } /** * Sets the position in object coordinates of this raster. This * position is transformed into device coordinates and is used as * the upper-left corner of the raster. * @param pos the new position of this raster * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setPosition(Point3f pos) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_POSITION_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster0")); ((RasterRetained) this.retained).setPosition(pos); } /** * Retrieves the current position in object coordinates of this raster. * @param pos the vector that will receive the current position * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void getPosition(Point3f pos) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_POSITION_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster1")); ((RasterRetained) this.retained).getPosition(pos); } /** * Sets the type of this raster object to one of: RASTER_COLOR, * RASTER_DEPTH, or RASTER_COLOR_DEPTH. * @param type the new type of this raster * @exception RestrictedAccessException if the method is called * when this object is part of live or compiled scene graph. */ public void setType(int type) { checkForLiveOrCompiled(); ((RasterRetained) this.retained).setType(type); } /** * Retrieves the current type of this raster object, one of: RASTER_COLOR, * RASTER_DEPTH, or RASTER_COLOR_DEPTH. * @return type the type of this raster * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public int getType() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_TYPE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster2")); return (((RasterRetained) this.retained).getType()); } /** * Sets the clipping mode of this raster object. * @param clipMode the new clipping mode of this raster, * one of: CLIP_POSITION or CLIP_IMAGE. The default mode * is CLIP_POSITION. * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void setClipMode(int clipMode) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_CLIP_MODE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster10")); ((RasterRetained) this.retained).setClipMode(clipMode); } /** * Retrieves the current clipping mode of this raster object. * @return clipMode the clipping mode of this raster, * one of: CLIP_POSITION or CLIP_IMAGE. * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public int getClipMode() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_CLIP_MODE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster11")); return (((RasterRetained) this.retained).getClipMode()); } /** * @deprecated As of Java 3D version 1.3, replaced by * <code>setSrcOffset(int,int)</code> */ public void setOffset(int xSrcOffset, int ySrcOffset) { setSrcOffset(xSrcOffset, ySrcOffset); } /** * @deprecated As of Java 3D version 1.3, replaced by * <code>setSrcOffset(java.awt.Point)</code> */ public void setOffset(Point srcOffset) { setSrcOffset(srcOffset); } /** * @deprecated As of Java 3D version 1.3, replaced by * <code>getSrcOffset(java.awt.Point)</code> */ public void getOffset(Point srcOffset) { getSrcOffset(srcOffset); } /** * Sets the offset within the source array of pixels * at which to start copying. * @param xSrcOffset the x offset within the source array of pixels * at which to start copying * @param ySrcOffset the y offset within the source array of pixels * at which to start copying * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void setSrcOffset(int xSrcOffset, int ySrcOffset) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_OFFSET_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster7")); ((RasterRetained) this.retained).setSrcOffset(xSrcOffset, ySrcOffset); } /** * Sets the offset within the source array of pixels * at which to start copying. * @param srcOffset the new source pixel offset * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void setSrcOffset(Point srcOffset) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_OFFSET_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster7")); ((RasterRetained) this.retained).setSrcOffset(srcOffset.x, srcOffset.y); } /** * Retrieves the current source pixel offset. * @param srcOffset the object that will receive the source offset * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void getSrcOffset(Point srcOffset) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_OFFSET_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster8")); ((RasterRetained) this.retained).getSrcOffset(srcOffset); } /** * Sets the number of pixels to be copied from the pixel array. * @param width the number of columns in the array of pixels to copy * @param height the number of rows in the array of pixels to copy * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setSize(int width, int height) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SIZE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster9")); ((RasterRetained) this.retained).setSize(width, height); } /** * Sets the size of the array of pixels to be copied. * @param size the new size * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setSize(Dimension size) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SIZE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster9")); ((RasterRetained) this.retained).setSize(size.width, size.height); } /** * Retrieves the current raster size. * @param size the object that will receive the size * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void getSize(Dimension size) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SIZE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster1")); ((RasterRetained) this.retained).getSize(size); } /** * Sets the destination pixel offset of the upper-left corner of * the rendered image relative to the transformed position. This * pixel offset is added to the transformed raster position prior * to rendering the image. * * @param xDstOffset the x coordinate of the new offset * @param yDstOffset the y coordinate of the new offset * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void setDstOffset(int xDstOffset, int yDstOffset) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_OFFSET_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster7")); ((RasterRetained) this.retained).setDstOffset(xDstOffset, yDstOffset); } /** * Sets the destination pixel offset of the upper-left corner of * the rendered image relative to the transformed position. This * pixel offset is added to the transformed raster position prior * to rendering the image. * * @param dstOffset the new destination pixel offset * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void setDstOffset(Point dstOffset) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_OFFSET_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster7")); ((RasterRetained) this.retained).setDstOffset(dstOffset.x, dstOffset.y); } /** * Retrieves the current destination pixel offset. * @param dstOffset the object that will receive the destination offset * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @since Java 3D 1.3 */ public void getDstOffset(Point dstOffset) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_OFFSET_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster8")); ((RasterRetained) this.retained).getDstOffset(dstOffset); } /** * Sets the pixel array used to copy pixels to/from a Canvas3D. * This is used when the type is RASTER_COLOR or RASTER_COLOR_DEPTH. * * @param image the ImageComponent2D object containing the * color data * * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * * @exception IllegalSharingException if this Raster is live and * the specified image is being used by a Canvas3D as an off-screen buffer. * * @exception IllegalArgumentException if the image class of the specified * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER. * */ public void setImage(ImageComponent2D image) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IMAGE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster3")); // Do illegal sharing check if (image != null) { ImageComponent2DRetained imageRetained = (ImageComponent2DRetained) image.retained; if (imageRetained.getUsedByOffScreen()) { if (isLive()) { throw new IllegalSharingException(J3dI18N.getString("Raster12")); } } } ((RasterRetained) this.retained).setImage(image); } /** * Retrieves the current pixel array object. * @return image the ImageComponent2D object containing the * color data * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public ImageComponent2D getImage() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IMAGE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster4")); return (((RasterRetained) this.retained).getImage()); } /** * Sets the depth image used to copy pixels to/from a Canvas3D. * This is used when the type is RASTER_DEPTH or RASTER_COLOR_DEPTH. * @param depthComponent the DepthComponent object containing the * depth (z-buffer) data * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setDepthComponent(DepthComponent depthComponent) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DEPTH_COMPONENT_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Raster5")); ((RasterRetained) this.retained).setDepthComponent(depthComponent); } /** * Retrieves the current depth image object. * @return depthImage DepthComponent containing the * depth (z-buffer) data * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public DepthComponent getDepthComponent() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DEPTH_COMPONENT_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Raster6")); return (((RasterRetained) this.retained).getDepthComponent()); } /** * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate) */ @Override public NodeComponent cloneNodeComponent() { Raster r = new Raster(); r.duplicateNodeComponent(this); return r; } /** * NOTE: Applications should <i>not</i> call this method directly. * It should only be called by the cloneNode method. * * @deprecated replaced with duplicateNodeComponent( * NodeComponent originalNodeComponent, boolean forceDuplicate) */ @Override public void duplicateNodeComponent(NodeComponent originalNodeComponent) { checkDuplicateNodeComponent(originalNodeComponent); } /** * Copies all node information from <code>originalNodeComponent</code> into * the current node. This method is called from the * <code>duplicateNode</code> method. This routine does * the actual duplication of all "local data" (any data defined in * this object). * * @param originalNodeComponent the original node to duplicate. * @param forceDuplicate when set to <code>true</code>, causes the * <code>duplicateOnCloneTree</code> flag to be ignored. When * <code>false</code>, the value of each node's * <code>duplicateOnCloneTree</code> variable determines whether * NodeComponent data is duplicated or copied. * * @see Node#cloneTree * @see NodeComponent#setDuplicateOnCloneTree */ @Override void duplicateAttributes(NodeComponent originalNodeComponent, boolean forceDuplicate) { super.duplicateAttributes(originalNodeComponent, forceDuplicate); RasterRetained raster = (RasterRetained) originalNodeComponent.retained; RasterRetained rt = (RasterRetained) retained; Point3f p = new Point3f(); raster.getPosition(p); rt.setPosition(p); rt.setType(raster.getType()); rt.setClipMode(raster.getClipMode()); Point offset = new Point(); raster.getSrcOffset(offset); rt.setSrcOffset(offset.x, offset.y); raster.getDstOffset(offset); rt.setDstOffset(offset.x, offset.y); Dimension dim = new Dimension(); raster.getSize(dim); rt.setSize(dim.width, dim.height); rt.setImage((ImageComponent2D) getNodeComponent(raster.getImage(), forceDuplicate, originalNodeComponent.nodeHashtable)); rt.setDepthComponent((DepthComponent) getNodeComponent(raster.getDepthComponent(), forceDuplicate, originalNodeComponent.nodeHashtable)); } /** * This function is called from getNodeComponent() to see if any of * the sub-NodeComponents duplicateOnCloneTree flag is true. * If it is the case, current NodeComponent needs to * duplicate also even though current duplicateOnCloneTree flag is false. * This should be overwrite by NodeComponent which contains sub-NodeComponent. */ @Override boolean duplicateChild() { if (getDuplicateOnCloneTree()) return true; RasterRetained rt = (RasterRetained) retained; NodeComponent nc = rt.getImage(); if ((nc != null) && nc.getDuplicateOnCloneTree()) return true; nc = rt.getDepthComponent(); if ((nc != null) && nc.getDuplicateOnCloneTree()) return true; return false; } }