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

/*
 * Copyright 1997-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 PolygonAttributes object defines attributes for rendering polygon
 * primitives.
 * Polygon primitives include triangles, triangle strips, triangle fans,
 * and quads.
 * The polygon attributes that can be defined are:</li>
 * <p><ul>
 * <li>Rasterization mode - defines how the polygon is drawn: as points,
 * outlines, or filled.<p>
 * <ul>
 * <li>POLYGON_POINT - the polygon is rendered as points
 * drawn at the vertices.</li><p>
 * <li>POLYGON_LINE - the polygon is rendered as lines
 * drawn between consecutive vertices.</li><p>
 * <li>POLYGON_FILL - the polygon is rendered by filling the interior
 * between the vertices. The default mode.</li>
 * <p></ul>
 * <li>Face culling - defines which polygons are culled (discarded)
 * before they are converted to screen coordinates.<p>
 * <ul>
 * <li>CULL_NONE - disables face culling.</li>
 * <li>CULL_BACK - culls all back-facing polygons. The default.</li>
 * <li>CULL_FRONT - culls all front-facing polygons.</li>
 * <p></ul>
 * <li>Back-face normal flip - specifies whether vertex normals of
 * back-facing polygons are flipped (negated) prior to lighting. The
 * setting is either true, meaning to flip back-facing normals, or
 * false. The default is false.</li>
 * <p>
 * <li>Offset - the depth values of all pixels generated by polygon
 * rasterization can be offset by a value that is computed for that
 * polygon. Two values are used to specify the offset:</li><p>
 * <ul>
 * <li>Offset bias - the constant polygon offset that is added to
 * the final device coordinate Z value of polygon primitives.</li>
 * <p>
 * <li>Offset factor - the factor to be multiplied by the
 * slope of the polygon and then added to the final, device coordinate
 * Z value of the polygon primitives.</li><p>
 * </ul>
 * These values can be either positive or negative. The default
 * for both of these values is 0.0.<p>
 * </ul>
 *
 * @see Appearance
 */
public class PolygonAttributes extends NodeComponent {

    /**
     * Specifies that this PolygonAttributes object allows reading its
     * cull face information.
     */
    public static final int
    ALLOW_CULL_FACE_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_CULL_FACE_READ;

    /**
     * Specifies that this PolygonAttributes object allows writing its
     * cull face information.
     */
    public static final int
    ALLOW_CULL_FACE_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_CULL_FACE_WRITE;

    /**
     * Specifies that this PolygonAttributes object allows reading its
     * back face normal flip flag.
     */
    public static final int
    ALLOW_NORMAL_FLIP_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_NORMAL_FLIP_READ;

    /**
     * Specifies that this PolygonAttributes object allows writing its
     * back face normal flip flag.
     */
    public static final int
    ALLOW_NORMAL_FLIP_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_NORMAL_FLIP_WRITE;

    /**
     * Specifies that this PolygonAttributes object allows reading its
     * polygon mode information.
     */
    public static final int
    ALLOW_MODE_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_MODE_READ;

    /**
     * Specifies that this PolygonAttributes object allows writing its
     * polygon mode information.
     */
    public static final int
    ALLOW_MODE_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_MODE_WRITE;

    /**
     * Specifies that this PolygonAttributes object allows reading its
     * polygon offset information.
     */
    public static final int
    ALLOW_OFFSET_READ = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_OFFSET_READ;

    /**
     * Specifies that this PolygonAttributes object allows writing its
     * polygon offset information.
     */
    public static final int
    ALLOW_OFFSET_WRITE = CapabilityBits.POLYGON_ATTRIBUTES_ALLOW_OFFSET_WRITE;

    // Polygon rasterization modes
    /**
     * Render polygonal primitives as points drawn at the vertices
     * of the polygon.
     */
    public static final int POLYGON_POINT = 0;
    /**
     * Render polygonal primitives as lines drawn between consecutive
     * vertices of the polygon.
     */
    public static final int POLYGON_LINE  = 1;
    /**
     * Render polygonal primitives by filling the interior of the polygon.
     */
    public static final int POLYGON_FILL  = 2;

    /**
     * Don't perform any face culling.
     */
    public static final int CULL_NONE  = 0;
    /**
     * Cull all back-facing polygons.  This is the default mode.
     */
    public static final int CULL_BACK  = 1;
    /**
     * Cull all front-facing polygons.
     */
    public static final int CULL_FRONT = 2;

   // Array for setting default read capabilities
    private static final int[] readCapabilities = {
        ALLOW_CULL_FACE_READ,
        ALLOW_MODE_READ,
        ALLOW_NORMAL_FLIP_READ,
        ALLOW_OFFSET_READ
    };

    /**
     * Constructs a PolygonAttributes object with default parameters.
     * The default values are as follows:
     * <ul>
     * cull face : CULL_BACK<br>
     * back face normal flip : false<br>
     * polygon mode : POLYGON_FILL<br>
     * polygon offset : 0.0<br>
     * polygon offset factor : 0.0<br>
     * </ul>
     */
    public PolygonAttributes() {
	// Just use defaults for all attributes
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);
    }

    /**
     * Constructs a PolygonAttributes object with specified values.
     * @param polygonMode polygon rasterization mode; one of POLYGON_POINT,
     * POLYGON_LINE, or POLYGON_FILL
     * @param cullFace polygon culling mode; one of CULL_NONE,
     * CULL_BACK, or CULL_FRONT
     * @param polygonOffset constant polygon offset
     */
    public PolygonAttributes(int polygonMode,
			     int cullFace,
			     float polygonOffset) {
	this(polygonMode, cullFace, polygonOffset, false, 0.0f);
     }

    /**
     * Constructs PolygonAttributes object with specified values.
     * @param polygonMode polygon rasterization mode; one of POLYGON_POINT,
     * POLYGON_LINE, or POLYGON_FILL
     * @param cullFace polygon culling mode; one of CULL_NONE,
     * CULL_BACK, or CULL_FRONT
     * @param polygonOffset constant polygon offset
     * @param backFaceNormalFlip back face normal flip flag; true or false
     */
    public PolygonAttributes(int polygonMode,
			     int cullFace,
			     float polygonOffset,
			     boolean backFaceNormalFlip) {
	this(polygonMode, cullFace, polygonOffset, backFaceNormalFlip, 0.0f);
     }

    /**
     * Constructs PolygonAttributes object with specified values.
     * @param polygonMode polygon rasterization mode; one of POLYGON_POINT,
     * POLYGON_LINE, or POLYGON_FILL
     * @param cullFace polygon culling mode; one of CULL_NONE,
     * CULL_BACK, or CULL_FRONT
     * @param polygonOffset constant polygon offset
     * @param backFaceNormalFlip back face normal flip flag; true or false
     * @param polygonOffsetFactor polygon offset factor for slope-based polygon
     * offset
     *
     * @since Java 3D 1.2
     */
    public PolygonAttributes(int polygonMode,
			     int cullFace,
			     float polygonOffset,
			     boolean backFaceNormalFlip,
			     float polygonOffsetFactor) {

       if (polygonMode < POLYGON_POINT || polygonMode > POLYGON_FILL)
         throw new IllegalArgumentException(J3dI18N.getString("PolygonAttributes0"));

       if (cullFace < CULL_NONE || cullFace > CULL_FRONT)
         throw new IllegalArgumentException(J3dI18N.getString("PolygonAttributes12"));

        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);

       ((PolygonAttributesRetained)this.retained).initPolygonMode(polygonMode);
       ((PolygonAttributesRetained)this.retained).initCullFace(cullFace);
       ((PolygonAttributesRetained)this.retained).initPolygonOffset(polygonOffset);
       ((PolygonAttributesRetained)this.retained).initBackFaceNormalFlip(backFaceNormalFlip);
       ((PolygonAttributesRetained)this.retained).initPolygonOffsetFactor(polygonOffsetFactor);
     }

    /**
     * Sets the face culling for this
     * appearance component object.
     * @param cullFace the face to be culled, one of:
     * CULL_NONE, CULL_FRONT, or CULL_BACK
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void setCullFace(int cullFace) {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_CULL_FACE_WRITE))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes2"));

        if (cullFace < CULL_NONE || cullFace > CULL_FRONT)
          throw new IllegalArgumentException(J3dI18N.getString("PolygonAttributes3"));
	if (isLive())
	    ((PolygonAttributesRetained)this.retained).setCullFace(cullFace);
	else
	    ((PolygonAttributesRetained)this.retained).initCullFace(cullFace);

    }

    /**
     * Gets the face culling for this
     * appearance component object.
     * @return the face to be culled
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public int getCullFace() {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_CULL_FACE_READ))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes4"));

        return ((PolygonAttributesRetained)this.retained).getCullFace();
    }

    /**
     * Sets the back face normal flip flag to the specified value.
     * This flag indicates whether vertex normals of back facing polygons
     * should be flipped (negated) prior to lighting.  When this flag
     * is set to true and back face culling is disabled, polygons are
     * rendered as if the polygon had two sides with opposing normals.
     * This feature is disabled by default.
     * @param backFaceNormalFlip the back face normal flip flag
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void setBackFaceNormalFlip(boolean backFaceNormalFlip) {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_NORMAL_FLIP_WRITE))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes5"));
	if (isLive())
	    ((PolygonAttributesRetained)this.retained).setBackFaceNormalFlip(backFaceNormalFlip);
	else
	    ((PolygonAttributesRetained)this.retained).initBackFaceNormalFlip(backFaceNormalFlip);

    }

    /**
     * Gets the back face normal flip flag.
     * @return the back face normal flip flag
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public boolean getBackFaceNormalFlip() {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_NORMAL_FLIP_READ))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes6"));

        return ((PolygonAttributesRetained)this.retained).getBackFaceNormalFlip();
    }

    /**
     * Sets the polygon rasterization mode for this
     * appearance component object.
     * @param polygonMode the polygon rasterization mode to be used; one of
     * POLYGON_FILL, POLYGON_LINE, or POLYGON_POINT
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void setPolygonMode(int polygonMode) {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_MODE_WRITE))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes7"));

        if (polygonMode < POLYGON_POINT || polygonMode > POLYGON_FILL)
          throw new IllegalArgumentException(J3dI18N.getString("PolygonAttributes8"));
	if (isLive())
	    ((PolygonAttributesRetained)this.retained).setPolygonMode(polygonMode);
	else
	    ((PolygonAttributesRetained)this.retained).initPolygonMode(polygonMode);

    }

    /**
     * Gets the polygon rasterization mode for this
     * appearance component object.
     * @return the polygon rasterization mode
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public int getPolygonMode() {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_MODE_READ))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes9"));

        return ((PolygonAttributesRetained)this.retained).getPolygonMode();
    }

    /**
     * Sets the constant polygon offset to the specified value.
     * This screen space
     * offset is added to the final, device coordinate Z value of polygon
     * primitives.
     * @param polygonOffset the constant polygon offset
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void setPolygonOffset(float polygonOffset) {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_OFFSET_WRITE))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes10"));

	if (isLive())
	    ((PolygonAttributesRetained)this.retained).setPolygonOffset(polygonOffset);
	else
	    ((PolygonAttributesRetained)this.retained).initPolygonOffset(polygonOffset);

    }

    /**
     * Gets the constant polygon offset.
     * @return the constant polygon offset
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public float getPolygonOffset() {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_OFFSET_READ))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes11"));

        return ((PolygonAttributesRetained)this.retained).getPolygonOffset();
    }

    /**
     * Sets the polygon offset factor to the specified value.
     * This factor is multiplied by the slope of the polygon, and
     * then added to the final, device coordinate Z value of polygon
     * primitives.
     * @param polygonOffsetFactor the polygon offset factor
     * @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 void setPolygonOffsetFactor(float polygonOffsetFactor) {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_OFFSET_WRITE))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes10"));

	if (isLive())
	    ((PolygonAttributesRetained)this.retained).
		setPolygonOffsetFactor(polygonOffsetFactor);
	else
	    ((PolygonAttributesRetained)this.retained).
		initPolygonOffsetFactor(polygonOffsetFactor);
    }

    /**
     * Gets the polygon offset factor.
     * @return the polygon offset factor.
     * @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 float getPolygonOffsetFactor() {
        if (isLiveOrCompiled())
            if(!this.getCapability(ALLOW_OFFSET_READ))
              throw new CapabilityNotSetException(J3dI18N.getString("PolygonAttributes11"));

	return ((PolygonAttributesRetained)this.retained).getPolygonOffsetFactor();
    }

    /**
     * Creates a retained mode PolygonAttributesRetained object that this
     * PolygonAttributes component object will point to.
     */
    @Override
    void createRetained() {
	this.retained = new PolygonAttributesRetained();
	this.retained.setSource(this);
    }

   /**
    * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
    */
    @Override
    public NodeComponent cloneNodeComponent() {
        PolygonAttributes pga = new PolygonAttributes();
        pga.duplicateNodeComponent(this);
        return pga;
    }


    /**
     * Copies all node information from <code>originalNodeComponent</code> into
     * the current node.  This method is called from the
     * <code>duplicateNode</code> method. This routine does
     * the actual duplication of all "local data" (any data defined in
     * this object).
     *
     * @param originalNodeComponent the original node to duplicate.
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */

    @Override
    void duplicateAttributes(NodeComponent originalNodeComponent,
			     boolean forceDuplicate) {

	super.duplicateAttributes(originalNodeComponent, forceDuplicate);

	PolygonAttributesRetained attr = (PolygonAttributesRetained)
	    originalNodeComponent.retained;

	PolygonAttributesRetained rt = (PolygonAttributesRetained) retained;

	rt.initCullFace(attr.getCullFace());
	rt.initBackFaceNormalFlip(attr.getBackFaceNormalFlip());
	rt.initPolygonMode(attr.getPolygonMode());
	rt.initPolygonOffset(attr.getPolygonOffset());
	rt.initPolygonOffsetFactor(attr.getPolygonOffsetFactor());
    }
}