path: root/src/javax/media/j3d/CompressedGeometry.java

/*
 * 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 ;
    }
}