diff options
Diffstat (limited to 'src/javax/media/j3d/CompressedGeometry.java')
| -rw-r--r-- | src/javax/media/j3d/CompressedGeometry.java | 428 |
1 files changed, 428 insertions, 0 deletions
diff --git a/src/javax/media/j3d/CompressedGeometry.java b/src/javax/media/j3d/CompressedGeometry.java new file mode 100644 index 0000000..a595f1c --- /dev/null +++ b/src/javax/media/j3d/CompressedGeometry.java @@ -0,0 +1,428 @@ +/* + * Copyright 1996-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; + +/** + * The compressed geometry object is used to store geometry in a + * compressed format. Using compressed geometry may increase the speed + * objects can be sent over the network. Note that the geometry will + * be decompressed in memory, so the application will not see any + * memory savings. + * <p> + * Compressed geometry may be passed to this CompressedGeometry object + * in one of two ways: by copying the data into this object using the + * existing constructor, or by passing a reference to the data. + * <p> + * <ul> + * <li> + * <b>By Copying:</b> + * The existing CompressedGeometry constructor copies the buffer of + * compressed geometry data into this CompressedGeometry object. This + * is appropriate for many applications, and allows Java 3D to verify + * the data once and then not worry about it again. + * </li> + * <li><b>By Reference:</b> + * A new constructor and set of methods in Java 3D version 1.2 allows + * compressed geometry data to be accessed by reference, directly from + * the user's array. To use this feature, you need to construct a + * CompressedGeometry object with the <code>byReference</code> flag + * set to <code>true</code>. In this mode, a reference to the input + * data is saved, but the data itself is not necessarily copied. Note + * that the compressed geometry header is still copied into this + * compressed geometry object. Data referenced by a + * CompressedGeometry object must not be modified after the + * CompressedGeometry object is constructed. + * Applications + * must exercise care not to violate this rule. If any referenced + * compressed geometry data is modified after construction, + * the results are undefined. + * </li> + * </ul> + * + * @deprecated As of Java 3D version 1.4. + */ +public class CompressedGeometry extends Geometry { + + CompressedGeometryHeader cgHeader ; + + /** + * Specifies that this CompressedGeometry object allows reading its + * byte count information. + */ + public static final int + ALLOW_COUNT_READ = CapabilityBits.COMPRESSED_GEOMETRY_ALLOW_COUNT_READ ; + + /** + * Specifies that this CompressedGeometry object allows reading its + * header information. + */ + public static final int + ALLOW_HEADER_READ = CapabilityBits.COMPRESSED_GEOMETRY_ALLOW_HEADER_READ ; + + /** + * Specifies that this CompressedGeometry object allows reading its + * geometry data component information. + */ + public static final int + ALLOW_GEOMETRY_READ = + CapabilityBits.COMPRESSED_GEOMETRY_ALLOW_GEOMETRY_READ ; + + /** + * Specifies that this CompressedGeometry allows reading the geometry + * data reference information for this object. This is only used in + * by-reference geometry mode. + * + * @since Java 3D 1.2 + */ + public static final int + ALLOW_REF_DATA_READ = + CapabilityBits.COMPRESSED_GEOMETRY_ALLOW_REF_DATA_READ; + + + // Array for setting default read capabilities + private static final int[] readCapabilities = { + ALLOW_COUNT_READ, + ALLOW_HEADER_READ, + ALLOW_GEOMETRY_READ, + ALLOW_REF_DATA_READ + }; + + /** + * Package scoped default constructor for use by cloneNodeComponent. + */ + CompressedGeometry() { + // set default read capabilities + setDefaultReadCapabilities(readCapabilities); + } + + /** + * Creates a new CompressedGeometry NodeComponent by copying + * the specified compressed geometry data into this object. + * If the version number of compressed geometry, as specified by + * the CompressedGeometryHeader, is incompatible with the + * supported version of compressed geometry in the current version + * of Java 3D, then the compressed geometry object will not be + * rendered. + * + * @param hdr the compressed geometry header. This is copied + * into the CompressedGeometry NodeComponent. + * + * @param compressedGeometry the compressed geometry data. The + * geometry must conform to the format described in Appendix B of + * the <i>Java 3D API Specification</i>. + * + * @exception IllegalArgumentException if a problem is detected with the + * header + * + * @see CompressedGeometryHeader + * @see Canvas3D#queryProperties + */ + public CompressedGeometry(CompressedGeometryHeader hdr, + byte[] compressedGeometry) { + this(hdr, compressedGeometry, false) ; + } + + /** + * Creates a new CompressedGeometry NodeComponent. The + * specified compressed geometry data is either copied into this + * object or is accessed by reference. + * If the version number of compressed geometry, as specified by + * the CompressedGeometryHeader, is incompatible with the + * supported version of compressed geometry in the current version + * of Java 3D, the compressed geometry object will not be + * rendered. + * + * @param hdr the compressed geometry header. This is copied + * into the CompressedGeometry NodeComponent. + * + * @param compressedGeometry the compressed geometry data. The + * geometry must conform to the format described in Appendix B of + * the <i>Java 3D API Specification</i>. + * + * @param byReference a flag that indicates whether the data is copied + * into this compressed geometry object or is accessed by reference. + * + * @exception IllegalArgumentException if a problem is detected with the + * header + * + * @see CompressedGeometryHeader + * @see Canvas3D#queryProperties + * + * @since Java 3D 1.2 + */ + public CompressedGeometry(CompressedGeometryHeader hdr, + byte[] compressedGeometry, + boolean byReference) { + + if ((hdr.size + hdr.start) > compressedGeometry.length) + throw new IllegalArgumentException + (J3dI18N.getString("CompressedGeometry0")) ; + + // set default read capabilities + setDefaultReadCapabilities(readCapabilities); + + // Create a separate copy of the given header. + cgHeader = new CompressedGeometryHeader() ; + hdr.copy(cgHeader) ; + + // Create the retained object. + ((CompressedGeometryRetained)this.retained).createCompressedGeometry + (cgHeader, compressedGeometry, byReference) ; + + // This constructor is designed to accept byte arrays that may contain + // possibly many large compressed geometry blocks interspersed with + // non-J3D-specific metadata. Only one of these blocks is used per + // CompressedGeometry object, so set the geometry offset to zero in + // the header if the data itself is copied. + if (!byReference) + cgHeader.start = 0 ; + } + + /** + * This constructor is not implemented. + * + * @exception UnsupportedOperationException this constructor is not + * implemented + * + * @since Java 3D 1.3 + */ + public CompressedGeometry(CompressedGeometryHeader hdr, + J3DBuffer compressedGeometry) { + throw new UnsupportedOperationException(J3dI18N.getString("CompressedGeometry9")) ; + } + + + /** + * Returns the size, in bytes, of the compressed geometry buffer. + * The size of the compressed geometry header is not included. + * + * @return the size, in bytes, of the compressed geometry buffer. + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + */ + public int getByteCount() { + if (isLiveOrCompiled()) + if (!this.getCapability(ALLOW_COUNT_READ)) + throw new CapabilityNotSetException + (J3dI18N.getString("CompressedGeometry1")) ; + + return cgHeader.size ; + } + + /** + * Copies the compressed geometry header from the CompressedGeometry + * NodeComponent into the passed in parameter. + * + * @param hdr the CompressedGeometryHeader object into which to copy the + * CompressedGeometry NodeComponent's header; the offset field may differ + * from that which was originally specified if a copy of the original + * compressed geometry byte array was created. + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + * + * @see CompressedGeometryHeader + */ + public void getCompressedGeometryHeader(CompressedGeometryHeader hdr) { + if (isLiveOrCompiled()) + if (!this.getCapability(ALLOW_HEADER_READ)) + throw new CapabilityNotSetException + (J3dI18N.getString("CompressedGeometry2")) ; + + cgHeader.copy(hdr) ; + } + + /** + * Retrieves the compressed geometry associated with the + * CompressedGeometry NodeComponent object. Copies the compressed + * geometry from the CompressedGeometry node into the given array. + * The array must be large enough to hold all of the bytes. + * The individual array elements must be allocated by the caller. + * + * @param compressedGeometry the array into which to copy the compressed + * geometry. + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + * + * @exception IllegalStateException if the data access mode for this + * object is by-reference. + * + * @exception ArrayIndexOutOfBoundsException if compressedGeometry byte + * array is not large enough to receive the compressed geometry + */ + public void getCompressedGeometry(byte[] compressedGeometry) { + if (isLiveOrCompiled()) + if (!this.getCapability(ALLOW_GEOMETRY_READ)) + throw new CapabilityNotSetException + (J3dI18N.getString("CompressedGeometry3")) ; + + if (isByReference()) + throw new IllegalStateException + (J3dI18N.getString("CompressedGeometry7")) ; + + if (cgHeader.size > compressedGeometry.length) + throw new ArrayIndexOutOfBoundsException + (J3dI18N.getString("CompressedGeometry4")) ; + + ((CompressedGeometryRetained)this.retained).copy(compressedGeometry) ; + } + + /** + * Decompresses the compressed geometry. Returns an array of Shape nodes + * containing the decompressed geometry objects, or null if the version + * number of the compressed geometry is incompatible with the decompressor + * in the current version of Java 3D. + * + * @return an array of Shape nodes containing the + * geometry decompressed from this CompressedGeometry NodeComponent + * object, or null if its version is incompatible + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + */ + public Shape3D[] decompress() { + if (isLiveOrCompiled()) + if (!this.getCapability(ALLOW_GEOMETRY_READ)) + throw new CapabilityNotSetException + (J3dI18N.getString("CompressedGeometry5")) ; + + CompressedGeometryRetained cgr = + (CompressedGeometryRetained)this.retained ; + + GeometryDecompressorShape3D decompressor = + new GeometryDecompressorShape3D() ; + + // Decompress the geometry as TriangleStripArrays. A combination of + // TriangleStripArrays and TrianglesFanArrays is more compact but + // requires twice as many Shape3D objects, resulting in slower + // rendering performance. + // + // Using TriangleArray output is currently the fastest, given the + // strip sizes observed from various compressed geometry objects, but + // produces about twice as many vertices. TriangleStripArray produces + // the same number of Shape3D objects as TriangleArray using 1/2 + // to 2/3 of the vertices, with only a marginal performance penalty. + // + return decompressor.toTriangleStripArrays(cgr) ; + } + + + /** + * Retrieves the data access mode for this CompressedGeometry object. + * + * @return <code>true</code> if the data access mode for this + * CompressedGeometry object is by-reference; + * <code>false</code> if the data access mode is by-copying. + * + * @since Java 3D 1.2 + */ + public boolean isByReference() { + return ((CompressedGeometryRetained)this.retained).isByReference() ; + } + + + /** + * Gets the compressed geometry data reference. + * + * @return the current compressed geometry data reference. + * + * @exception IllegalStateException if the data access mode for this + * object is not by-reference. + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + * + * @since Java 3D 1.2 + */ + public byte[] getCompressedGeometryRef() { + if (isLiveOrCompiled()) + if (!this.getCapability(ALLOW_REF_DATA_READ)) + throw new CapabilityNotSetException + (J3dI18N.getString("CompressedGeometry6")) ; + + if (!isByReference()) + throw new IllegalStateException + (J3dI18N.getString("CompressedGeometry8")) ; + + return ((CompressedGeometryRetained)this.retained).getReference() ; + } + + + /** + * Gets the compressed geometry data buffer reference, which is + * always null since NIO buffers are not supported for + * CompressedGeometry objects. + * + * @return null + * + * @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 J3DBuffer getCompressedGeometryBuffer() { + if (isLiveOrCompiled()) + if (!this.getCapability(ALLOW_REF_DATA_READ)) + throw new CapabilityNotSetException + (J3dI18N.getString("CompressedGeometry6")) ; + + return null; + } + + + /** + * Creates the retained mode CompressedGeometryRetained object that this + * CompressedGeometry object will point to. + */ + @Override + void createRetained() { + this.retained = new CompressedGeometryRetained() ; + this.retained.setSource(this) ; + } + + /** + * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate) + */ + @Override + public NodeComponent cloneNodeComponent() { + CompressedGeometry cg = new CompressedGeometry() ; + + // Duplicate data specific to this class. + cg.cgHeader = new CompressedGeometryHeader() ; + cgHeader.copy(cg.cgHeader) ; + + // Duplicate the retained side. + CompressedGeometryRetained cgr = (CompressedGeometryRetained)retained ; + cgr.duplicate((CompressedGeometryRetained)cg.retained) ; + + // Duplicate superclass data and return. + cg.duplicateNodeComponent(this) ; + return cg ; + } +} |