geometryarray.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: GeometryArray.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.6 $
 * $Date: 2007/02/09 17:18:00 $
 * $State: Exp $
 */

package javax.media.j3d;

import javax.vecmath.*;


/**
 * The GeometryArray object contains separate arrays of positional
 * coordinates, colors, normals, texture coordinates, and vertex
 * attributes that
 * describe point, line, or polygon geometry.  This class is extended
 * to create the various primitive types (such as lines,
 * triangle strips, etc.).
 * Vertex data may be passed to this geometry array in one of two
 * ways: by copying the data into the array using the existing
 * methods, or by passing a reference to the data.
 * <p>
 * <ul>
 * <li>
 * <b>By Copying:</b>
 * The existing methods for setting positional coordinates, colors,
 * normals, texture coordinates, and vertex attributes
 * (such as <code>setCoordinate</code>,
 * <code>setColors</code>, etc.)  copy the data into this
 * GeometryArray.  This is appropriate for many applications and
 * offers an application much flexibility in organizing its data.
 * This is the default mode.
 * </li>
 * <li><b>By Reference:</b>
 * A new set of methods in Java 3D version 1.2 allows data to be
 * accessed by reference, directly from the user's arrays.  To use
 * this feature, set the <code>BY_REFERENCE</code> bit in the
 * <code>vertexFormat</code> field of the constructor for this
 * GeometryArray.  In this mode, the various set methods for
 * coordinates, normals, colors, texture coordinates, and vertex attributes
 * are not used.
 * Instead, new methods are used to set a reference to user-supplied
 * coordinate, color, normal, texture coordinate, and vertex attribute
 * arrays (such as
 * <code>setCoordRefFloat</code>, <code>setColorRefFloat</code>,
 * etc.).  Data in any array that is referenced by a live or compiled
 * GeometryArray object may only be modified via the
 * <code>updateData</code> method (subject to the
 * <code>ALLOW_REF_DATA_WRITE</code> capability bit).  Applications
 * must exercise care not to violate this rule.  If any referenced
 * geometry data is modified outside of the <code>updateData</code>
 * method, the results are undefined.
 * </li>
 * </ul>
 * <p>
 * All colors used in the geometry array object must be in the range [0.0,1.0].
 * Values outside this range will cause undefined results.
 * All normals used in the geometry array object must be unit length
 * vectors.  That is their geometric length must be 1.0.  Normals that
 * are not unit length vectors will cause undefined results.
 * <p>
 * Note that the term <i>coordinate</i>, as used in the method names
 * and method descriptions, actually refers to a set of <i>x</i>,
 * <i>y</i>, and <i>z</i> coordinates representing the position of a
 * single vertex.  The term <i>coordinates</i> (plural) is used to
 * indicate sets of <i>x</i>, <i>y</i>, and <i>z</i> coordinates for
 * multiple vertices.  This is somewhat at odds with the mathematical
 * definition of a coordinate, but is used as a convenient shorthand.
 * Similarly, the term <i>texture coordinate</i> is used to indicate a
 * set of texture coordinates for a single vertex, while the term
 * <i>texture coordinates</i> (plural) is used to indicate sets of
 * texture coordinates for multiple vertices.
 */

public abstract class GeometryArray extends Geometry {

  /**
   * Specifies that this GeometryArray allows reading the array of
   * coordinates.
   */
  public static final int
    ALLOW_COORDINATE_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_COORDINATE_READ;

  /**
   * Specifies that this GeometryArray allows writing the array of
   * coordinates.
   */
  public static final int
    ALLOW_COORDINATE_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_COORDINATE_WRITE;

  /**
   * Specifies that this GeometryArray allows reading the array of
   * colors.
   */
  public static final int
    ALLOW_COLOR_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_COLOR_READ;

  /**
   * Specifies that this GeometryArray allows writing the array of
   * colors.
   */
  public static final int
    ALLOW_COLOR_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_COLOR_WRITE;

  /**
   * Specifies that this GeometryArray allows reading the array of
   * normals.
   */
  public static final int
    ALLOW_NORMAL_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_NORMAL_READ;

  /**
   * Specifies that this GeometryArray allows writing the array of
   * normals.
   */
  public static final int
    ALLOW_NORMAL_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_NORMAL_WRITE;

  /**
   * Specifies that this GeometryArray allows reading the array of
   * texture coordinates.
   */
  public static final int
    ALLOW_TEXCOORD_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_TEXCOORD_READ;

  /**
   * Specifies that this GeometryArray allows writing the array of
   * texture coordinates.
   */
  public static final int
    ALLOW_TEXCOORD_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_TEXCOORD_WRITE;

  /**
   * Specifies that this GeometryArray allows reading the array of
   * vertex attributes.
   *
   * @since Java 3D 1.4
   */
  public static final int
    ALLOW_VERTEX_ATTR_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_VERTEX_ATTR_READ;

  /**
   * Specifies that this GeometryArray allows writing the array of
   * vertex attributes.
   *
   * @since Java 3D 1.4
   */
  public static final int
    ALLOW_VERTEX_ATTR_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_VERTEX_ATTR_WRITE;

  /**
   * Specifies that this GeometryArray allows reading the count or
   * initial index information for this object.
   */
  public static final int
    ALLOW_COUNT_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_COUNT_READ;

  /**
   * Specifies that this GeometryArray allows writing the count or
   * initial index information for this object.
   *
   * @since Java 3D 1.2
   */
  public static final int
    ALLOW_COUNT_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_COUNT_WRITE;

  /**
   * Specifies that this GeometryArray allows reading the vertex format
   * information for this object.
   */
  public static final int
    ALLOW_FORMAT_READ = CapabilityBits.GEOMETRY_ARRAY_ALLOW_FORMAT_READ;

  /**
   * Specifies that this GeometryArray 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.GEOMETRY_ARRAY_ALLOW_REF_DATA_READ;

  private static final int J3D_1_2_ALLOW_REF_DATA_READ =
    CapabilityBits.J3D_1_2_GEOMETRY_ARRAY_ALLOW_REF_DATA_READ;

  /**
   * Specifies that this GeometryArray allows writing the geometry
   * data reference information for this object.  It also enables
   * writing the referenced data itself, via the GeometryUpdater
   * interface.  This is only used in by-reference geometry mode.
   *
   * @since Java 3D 1.2
   */
  public static final int
    ALLOW_REF_DATA_WRITE = CapabilityBits.GEOMETRY_ARRAY_ALLOW_REF_DATA_WRITE;

  /**
   * Specifies that this GeometryArray contains an array of coordinates.
   * This bit must be set.
   */
  public static final int COORDINATES = 0x01;

  /**
   * Specifies that this GeometryArray contains an array of normals.
   */
  public static final int NORMALS = 0x02;

  /**
   * Specifies that this GeometryArray contains an array of colors.
   */
  static final int COLOR = 0x04;

  /**
   * Specifies that this GeometryArray's colors contain alpha.
   */
  static final int WITH_ALPHA = 0x08;

  /**
   * Specifies that this GeometryArray contains an array of colors without alpha.
   */
  public static final int COLOR_3 = COLOR;

  /**
   * Specifies that this GeometryArray contains an array of colors with alpha.
   * This takes precedence over COLOR_3.
   */
  public static final int COLOR_4 = COLOR | WITH_ALPHA;

  /**
   * Specifies that this GeometryArray contains one or more arrays of
   * 2D texture coordinates.
   */
  public static final int TEXTURE_COORDINATE_2 = 0x20;

  /**
   * Specifies that this GeometryArray contains one or more arrays of
   * 3D texture coordinates.
   * This takes precedence over TEXTURE_COORDINATE_2.
   */
  public static final int TEXTURE_COORDINATE_3 = 0x40;


  /**
   * Specifies that this GeometryArray contains one or more arrays of
   * 4D texture coordinates.
   * This takes precedence over TEXTURE_COORDINATE_2 and TEXTURE_COORDINATE_3.
   *
   * @since Java 3D 1.3
   */
  public static final int TEXTURE_COORDINATE_4 = 0x400;


  static final int TEXTURE_COORDINATE = TEXTURE_COORDINATE_2 |
                                        TEXTURE_COORDINATE_3 |
					TEXTURE_COORDINATE_4;

    /**
     * Specifies that the position, color, normal, and texture coordinate
     * data for this GeometryArray are accessed by reference.
     *
     * @since Java 3D 1.2
     */
    public static final int BY_REFERENCE = 0x80;


    /**
     * Specifies that the position, color, normal, and texture
     * coordinate data for this GeometryArray are accessed via a single
     * interleaved, floating-point array reference.  All of the data
     * values for each vertex are stored in consecutive memory
     * locations.  This flag is only valid in conjunction with the
     * <code>BY_REFERENCE</code> flag.
     *
     * @since Java 3D 1.2
     */
    public static final int INTERLEAVED = 0x100;

    /**
     * Specifies that geometry by-reference data for this
     * GeometryArray, whether interleaved or non-interleaved, is
     * accessed via J3DBuffer objects that wrap NIO Buffer objects,
     * rather than float, double, byte, or TupleXX arrays.  This flag
     * is only valid in conjunction with the <code>BY_REFERENCE</code>
     * flag.
     *
     * @see J3DBuffer
     * @see #setCoordRefBuffer(J3DBuffer)
     * @see #setColorRefBuffer(J3DBuffer)
     * @see #setNormalRefBuffer(J3DBuffer)
     * @see #setTexCoordRefBuffer(int,J3DBuffer)
     * @see #setVertexAttrRefBuffer(int,J3DBuffer)
     * @see #setInterleavedVertexBuffer(J3DBuffer)
     *
     * @since Java 3D 1.3
     */
    public static final int USE_NIO_BUFFER = 0x800;

    /**
     * Specifies that only the coordinate indices are used for indexed
     * geometry arrays.  In this mode, the values from the coordinate
     * index array are used as a single set of index values to access
     * the vertex data for all five vertex components (coord, color,
     * normal, texCoord, and vertexAttr).  The color, normal, texCoord,
     * and vertexAttr index arrays are neither allocated nor used. Any
     * attempt to access the color, normal, texCoord,
     * or vertexAttr index arrays will result in a NullPointerException.
     * This flag is only valid for indexed geometry arrays