appearance.java

JAVA3D矩陈的相关类

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

package javax.media.j3d;

import java.util.Hashtable;

/**
 * The Appearance object defines all rendering state that can be set
 * as a component object of a Shape3D node. The rendering state 
 * consists of the following:<p>
 * <ul>
 * <li>Coloring attributes - defines attributes used in color selection
 * and shading. These attributes are defined in a ColoringAttributes
 * object.</li><p>
 * 
 * <li>Line attributes - defines attributes used to define lines, including
 * the pattern, width, and whether antialiasing is to be used. These
 * attributes are defined in a LineAttributes object.</li><p>
 *
 * <li>Point attributes - defines attributes used to define points,
 * including the size and whether antialiasing is to be used. These
 * attributes are defined in a PointAttributes object.</li><p>
 *
 * <li>Polygon attributes - defines the attributes used to define
 * polygons, including culling, rasterization mode (filled, lines,
 * or points), constant offset, offset factor, and whether back
 * back facing normals are flipped. These attributes are defined
 * in a PolygonAttributes object.</li><p>
 *
 * <li>Rendering attributes - defines rendering operations,
 * including the alpha test function and test value, the raster
 * operation, whether vertex colors are ignored, whether invisible
 * objects are rendered, and whether the depth buffer is enabled.
 * These attributes are defined in a RenderingAttributes 
 * object.</li><p>
 *
 * <li>Transparency attributes - defines the attributes that affect
 * transparency of the object, such as the transparency mode 
 * (blended, screen-door), blending function (used in transparency
 * and antialiasing operations), and a blend value that defines
 * the amount of transparency to be applied to this Appearance 
 * component object.</li><p>
 * 
 * <li>Material - defines the appearance of an object under illumination,
 * such as the ambient color, diffuse color, specular color, emissive
 * color, and shininess. These attributes are defined in a Material
 * object.</li><p>
 *
 * <li>Texture - defines the texture image and filtering
 * parameters used when texture mapping is enabled. These attributes
 * are defined in a Texture object.</li><p>
 *
 * <li>Texture attributes - defines the attributes that apply to
 * texture mapping, such as the texture mode, texture transform,
 * blend color, and perspective correction mode. These attributes
 * are defined in a TextureAttributes object.</li><p>
 *
 * <li>Texture coordinate generation - defines the attributes
 * that apply to texture coordinate generation, such as whether
 * texture coordinate generation is enabled, coordinate format 
 * (2D or 3D coordinates), coordinate generation mode (object
 * linear, eye linear, or spherical reflection mapping), and the
 * R, S, and T coordinate plane equations. These attributes
 * are defined in a TexCoordGeneration object.</li><p>
 *
 * <li>Texture unit state - array that defines texture state for each
 * of <i>N</i> separate texture units.  This allows multiple textures
 * to be applied to geometry.  Each TextureUnitState object contains a
 * Texture object, TextureAttributes, and TexCoordGeneration object
 * for one texture unit.  If the length of the texture unit state
 * array is greater than 0, then the array is used for all texture
 * state; the individual Texture, TextureAttributes, and
 * TexCoordGeneration objects in this Appearance object are not used
 * and and must not be set by an application. If the length of the
 * texture unit state array is 0, the multi-texture is disabled and
 * the Texture, TextureAttributes, and TexCoordGeneration objects
 * in the Appearance object are used. If the application sets the
 * existing Texture, TextureAttributes, and TexCoordGeneration
 * objects to non-null values, they effectively define the state
 * for texture unit 0. If the TextureUnitState array is set to a
 * non-null, non-empty array, the individual TextureUnitState
 * objects define the state for texture units 0 through <i>n</i>
 * -1. If both the old and new values are set, an exception is thrown.
 *
 * </li>
 * </ul>
 *
 * @see ColoringAttributes
 * @see LineAttributes
 * @see PointAttributes
 * @see PolygonAttributes
 * @see RenderingAttributes
 * @see TransparencyAttributes
 * @see Material
 * @see Texture
 * @see TextureAttributes
 * @see TexCoordGeneration
 * @see TextureUnitState
 */
public class Appearance extends NodeComponent {

  /**
   * Specifies that this Appearance object
   * allows reading its coloringAttributes component
   * information.
   */
  public static final int
    ALLOW_COLORING_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_COLORING_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its coloringAttributes component
   * information.
   */
  public static final int
    ALLOW_COLORING_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_COLORING_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its transparency component
   * information.
   */
  public static final int
    ALLOW_TRANSPARENCY_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_TRANSPARENCY_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its transparency component
   * information.
   */
  public static final int
    ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its rendering/rasterization component
   * information.
   */
  public static final int
    ALLOW_RENDERING_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_RENDERING_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its rendering/rasterization component
   * information.
   */
  public static final int
    ALLOW_RENDERING_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_RENDERING_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its polygon component
   * information.
   */
  public static final int
    ALLOW_POLYGON_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_POLYGON_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its polygon component
   * information.
   */
  public static final int
    ALLOW_POLYGON_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_POLYGON_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its line component
   * information.
   */
  public static final int
    ALLOW_LINE_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_LINE_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its line component
   * information.
   */
  public static final int
    ALLOW_LINE_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_LINE_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its point component
   * information.
   */
  public static final int
    ALLOW_POINT_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_POINT_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its point component
   * information.
   */
  public static final int
    ALLOW_POINT_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_POINT_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its material component information.
   */
  public static final int
    ALLOW_MATERIAL_READ = CapabilityBits.APPEARANCE_ALLOW_MATERIAL_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its material component information.
   */
  public static final int
    ALLOW_MATERIAL_WRITE = CapabilityBits.APPEARANCE_ALLOW_MATERIAL_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its texture component information.
   */
  public static final int
    ALLOW_TEXTURE_READ = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its texture component information.
   */
  public static final int
    ALLOW_TEXTURE_WRITE = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its textureAttributes component
   * information.
   */
  public static final int
    ALLOW_TEXTURE_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_ATTRIBUTES_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its textureAttributes component
   * information.
   */
  public static final int
    ALLOW_TEXTURE_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_ATTRIBUTES_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its texture coordinate generation component
   * information.
   */
  public static final int
    ALLOW_TEXGEN_READ = CapabilityBits.APPEARANCE_ALLOW_TEXGEN_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its texture coordinate generation component
   * information.
   */
  public static final int
    ALLOW_TEXGEN_WRITE = CapabilityBits.APPEARANCE_ALLOW_TEXGEN_WRITE;

  /**
   * Specifies that this Appearance object
   * allows reading its texture unit state component
   * information.
   *
   * @since Java 3D 1.2
   */
  public static final int ALLOW_TEXTURE_UNIT_STATE_READ =
    CapabilityBits.APPEARANCE_ALLOW_TEXTURE_UNIT_STATE_READ;

  /**
   * Specifies that this Appearance object
   * allows writing its texture unit state  component
   * information.
   *
   * @since Java 3D 1.2
   */
  public static final int ALLOW_TEXTURE_UNIT_STATE_WRITE =
    CapabilityBits.APPEARANCE_ALLOW_TEXTURE_UNIT_STATE_WRITE;

   // Array for setting default read capabilities
    private static final int[] readCapabilities = {
        ALLOW_COLORING_ATTRIBUTES_READ,
        ALLOW_LINE_ATTRIBUTES_READ,
        ALLOW_MATERIAL_READ,
        ALLOW_POINT_ATTRIBUTES_READ,
        ALLOW_POLYGON_ATTRIBUTES_READ,
        ALLOW_RENDERING_ATTRIBUTES_READ,
        ALLOW_TEXGEN_READ,
        ALLOW_TEXTURE_ATTRIBUTES_READ,
        ALLOW_TEXTURE_READ,
        ALLOW_TEXTURE_UNIT_STATE_READ,
        ALLOW_TRANSPARENCY_ATTRIBUTES_READ        
    };
    
    /**
     * Constructs an Appearance component object using defaults for all
     * state variables. All component object references are initialized 
     * to null.
     */
    public Appearance() {
	// Just use default values
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);
    }

    /**
     * Creates the retained mode AppearanceRetained object that this
     * Appearance component object will point to.
     */
    void createRetained() {
	this.retained = new AppearanceRetained();
	this.retained.setSource(this);
    }
  
    /**
     * Sets the material object to the specified object.
     * Setting it to null disables lighting.
     * @param material object that specifies the desired material
     * properties
     * @exception CapabilityNotSetException if appropriate capability is 
     * not set and this object is part of live or compiled scene graph
     */
    public void setMaterial(Material material) {
	if (isLiveOrCompiled())
	  if (!this.getCapability(ALLOW_MATERIAL_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("Appearance0"));
	((AppearanceRetained)this.retained).setMaterial(material);
    }

    /**