com.sun.j3d.utils.geometry.compression

## Class CompressedGeometryData

- java.lang.Object
- - com.sun.j3d.utils.geometry.compression.CompressedGeometryData

-     public class CompressedGeometryData
      extends java.lang.Object

  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.

  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.

  - By Copying: 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.
  - By Reference: 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 `byReference` flag set to `true`. 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.
  Since:
    Java 3D 1.5

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CompressedGeometryData.Header` The Header class is a data container for the header information, used in conjunction with a CompressedGeometryData object.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CompressedGeometryData(CompressedGeometryData.Header hdr, byte[] compressedGeometry)` Creates a new CompressedGeometryData object by copying the specified compressed geometry data into this object.
    `CompressedGeometryData(CompressedGeometryData.Header hdr, byte[] compressedGeometry, boolean byReference)` Creates a new CompressedGeometryData object.
    `CompressedGeometryData(CompressedGeometryData.Header hdr, J3DBuffer compressedGeometry)` Creates a new CompressedGeometryData object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Shape3D[]` | `decompress()` Decompresses the compressed geometry.
    `int` | `getByteCount()` Returns the size, in bytes, of the compressed geometry buffer.
    `void` | `getCompressedGeometry(byte[] compressedGeometry)` Retrieves the compressed geometry associated with the CompressedGeometryData object.
    `J3DBuffer` | `getCompressedGeometryBuffer()` Gets the compressed geometry data buffer reference, which is always null since NIO buffers are not supported for CompressedGeometryData objects.
    `void` | `getCompressedGeometryHeader(CompressedGeometryData.Header hdr)` Copies the compressed geometry header from the CompressedGeometryData object into the passed in parameter.
    `byte[]` | `getCompressedGeometryRef()` Gets the compressed geometry data reference.
    `boolean` | `isByReference()` Retrieves the data access mode for this CompressedGeometryData object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CompressedGeometryData

          public CompressedGeometryData(CompressedGeometryData.Header hdr,
                                byte[] compressedGeometry)

      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.
      Parameters:
        `hdr` - the compressed geometry header. This is copied into this CompressedGeometryData object.
        `compressedGeometry` - the compressed geometry data. The geometry must conform to the format described in Appendix B of the Java 3D API Specification.
      Throws:
        `java.lang.IllegalArgumentException` - if a problem is detected with the header.

    - #### CompressedGeometryData

          public CompressedGeometryData(CompressedGeometryData.Header hdr,
                                byte[] compressedGeometry,
                                boolean byReference)

      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.
      Parameters:
        `hdr` - the compressed geometry header. This is copied into the CompressedGeometryData object.
        `compressedGeometry` - the compressed geometry data. The geometry must conform to the format described in Appendix B of the Java 3D API Specification.
        `byReference` - a flag that indicates whether the data is copied into this compressed geometry object or is accessed by reference.
      Throws:
        `java.lang.IllegalArgumentException` - if a problem is detected with the header.

    - #### CompressedGeometryData

          public CompressedGeometryData(CompressedGeometryData.Header hdr,
                                J3DBuffer compressedGeometry)

      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.
      Parameters:
        `hdr` - the compressed geometry header. This is copied into the CompressedGeometryData object.
        `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 Java 3D API Specification.
      Throws:
        `java.lang.UnsupportedOperationException` - this method is not yet implemented
        `java.lang.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 Also:
        `CompressedGeometryData.Header`

  - ### Method Detail

    - #### getByteCount

          public int getByteCount()

      Returns the size, in bytes, of the compressed geometry buffer. The size of the compressed geometry header is not included.
      Returns:
        the size, in bytes, of the compressed geometry buffer.

    - #### getCompressedGeometryHeader

          public void getCompressedGeometryHeader(CompressedGeometryData.Header hdr)

      Copies the compressed geometry header from the CompressedGeometryData object into the passed in parameter.
      Parameters:
        `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.

    - #### getCompressedGeometry

          public void getCompressedGeometry(byte[] compressedGeometry)

      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.
      Parameters:
        `compressedGeometry` - the array into which to copy the compressed geometry.
      Throws:
        `java.lang.IllegalStateException` - if the data access mode for this object is by-reference.
        `java.lang.ArrayIndexOutOfBoundsException` - if compressedGeometry byte array is not large enough to receive the compressed geometry

    - #### decompress

          public Shape3D[] decompress()

      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.
      Returns:
        an array of Shape nodes containing the geometry decompressed from this CompressedGeometryData object, or null if its version is incompatible

    - #### isByReference

          public boolean isByReference()

      Retrieves the data access mode for this CompressedGeometryData object.
      Returns:
        `true` if the data access mode for this CompressedGeometryData object is by-reference; `false` if the data access mode is by-copying.

    - #### getCompressedGeometryRef

          public byte[] getCompressedGeometryRef()

      Gets the compressed geometry data reference.
      Returns:
        the current compressed geometry data reference.
      Throws:
        `java.lang.IllegalStateException` - if the data access mode for this object is not by-reference.

    - #### getCompressedGeometryBuffer

          public J3DBuffer getCompressedGeometryBuffer()

      Gets the compressed geometry data buffer reference, which is always null since NIO buffers are not supported for CompressedGeometryData objects.
      Returns:
        null

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.