compressedgeometrydata.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: CompressedGeometryData.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistribution of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistribution in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in
 *   the documentation and/or other materials provided with the
 *   distribution.
 *
 * Neither the name of Sun Microsystems, Inc. or the names of
 * contributors may be used to endorse or promote products derived
 * from this software without specific prior written permission.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
 * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * You acknowledge that this software is not designed, licensed or
 * intended for use in the design, construction, operation or
 * maintenance of any nuclear facility.
 *
 * $Revision: 1.3 $
 * $Date: 2007/02/09 17:20:21 $
 * $State: Exp $
 */

package com.sun.j3d.utils.geometry.compression;

import com.sun.j3d.internal.J3dUtilsI18N;
import javax.media.j3d.J3DBuffer;
import javax.media.j3d.Shape3D;
import javax.vecmath.Point3d;

/**
 * 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 CompressedGeometryData 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>
 * In by-copy mode, the CompressedGeometryData constructor copies the buffer of
 * compressed geometry data into this CompressedGeometryData 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>
 * In by-reference mode, the
 * compressed geometry data is accessed by reference, directly from
 * the user's array.  To use this feature, you need to construct a
 * CompressedGeometryData 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
 * CompressedGeometryData object must not be modified after the
 * CompressedGeometryData 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>
 *
 * @since Java 3D 1.5
 */
public class CompressedGeometryData extends Object {

    private Header cgHeader;
    private CompressedGeometryRetained retained;


    /**
     * Creates a new CompressedGeometryData object by copying
     * the specified compressed geometry data into this object.
     * If the version number of compressed geometry, as specified by
     * the Header, is incompatible with the
     * supported version of compressed geometry, then an exception
     * will be thrown.
     *
     * @param hdr the compressed geometry header.  This is copied
     * into this CompressedGeometryData object.
     *
     * @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.
     */ 
    public CompressedGeometryData(Header hdr,
            byte[] compressedGeometry) {

        this(hdr, compressedGeometry, false);
    }

    /**
     * Creates a new CompressedGeometryData object.  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 Header, is incompatible with the
     * supported version of compressed geometry, then an exception
     * will be thrown.
     *
     * @param hdr the compressed geometry header.  This is copied
     * into the CompressedGeometryData object.
     *
     * @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.
     */
    public CompressedGeometryData(Header hdr,
            byte[] compressedGeometry,
            boolean byReference) {

        if ((hdr.size + hdr.start) > compressedGeometry.length) {
            throw new IllegalArgumentException(J3dUtilsI18N.getString("CompressedGeometry0"));
        }

        // Create a separate copy of the given header.
        cgHeader = new Header();
        hdr.copy(cgHeader);

        // Create the retained object.
        retained = new 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;
    }

    /**
     * Creates a new CompressedGeometryData object.  The
     * specified compressed geometry data is accessed by reference
     * from the specified buffer.
     * If the version number of compressed geometry, as specified by
     * the Header, is incompatible with the
     * supported version of compressed geometry, then an exception
     * will be thrown.
     *
     * @param hdr the compressed geometry header.  This is copied
     * into the CompressedGeometryData object.
     *
     * @param compressedGeometry a buffer containing an NIO byte buffer
     * of compressed geometry data.  The
     * geometry must conform to the format described in Appendix B of
     * the <i>Java 3D API Specification</i>.
     *
     * @exception UnsupportedOperationException this method is not
     * yet implemented
     *
     * @exception IllegalArgumentException if a problem is detected with the
     * header,
     * or if the java.nio.Buffer contained in the specified J3DBuffer
     * is not a java.nio.ByteBuffer object.
     *
     * @see Header
     */
    public CompressedGeometryData(Header hdr,
            J3DBuffer compressedGeometry) {

        throw new UnsupportedOperationException("not implemented");
    }


    /**
     * 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.
     */
    public int getByteCount() {
	return cgHeader.size;
    }

    /**
     * Copies the compressed geometry header from the CompressedGeometryData
     * object into the passed in parameter.
     *
     * @param hdr the Header object into which to copy the
     * CompressedGeometryData object'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.
     */
    public void getCompressedGeometryHeader(Header hdr) {
	cgHeader.copy(hdr);
    }

    /**
     * Retrieves the compressed geometry associated with the
     * CompressedGeometryData object.  Copies the compressed
     * geometry from the CompressedGeometryData 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 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 (isByReference()) {
	    throw new IllegalStateException(
                    J3dUtilsI18N.getString("CompressedGeometry7"));
        }

	if (cgHeader.size > compressedGeometry.length) {
	    throw new ArrayIndexOutOfBoundsException(
                    J3dUtilsI18N.getString("CompressedGeometry4"));
        }

	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 CompressedGeometryData
     * object, or null if its version is incompatible
     */
    public Shape3D[] decompress() {
	CompressedGeometryRetained cgr = 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.