renderingattributes.java

JAVA3D矩陈的相关类

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

package javax.media.j3d;

/**
 * The RenderingAttributes object defines common rendering attributes
 * for all primitive types. The rendering attributes are:<p>
 * <ul>
 * <li>Depth test function - used to compare the incoming (source) depth of
 * each pixel with depth of the pixel stored in frame buffer. If the test
 * passes, the pixel is written, otherwise the pixel is not written. The depth test
 * function is set with the <code>setDepthTestFunction</code>
 * method. By default, LESS_OR_EQUAL is the function used. The depth test
 * function is one of the following:</li><p>
 * <ul>
 * <li>ALWAYS - pixels are always drawn, irrespective of the depth
 * value. This effectively disables depth testing.</li><p>
 *
 * <li>NEVER - pixels are never drawn, irrespective of the depth
 * value.</li><p>
 *
 * <li>EQUAL - pixels are drawn if the incoming pixel depth is equal
 * to the stored pixel depth in the frame buffer.</li><p>
 *
 * <li>NOT_EQUAL - pixels are drawn if the incoming pixel depth is
 * not equal to the stored pixel depth in the frame buffer.</li><p>
 * 
 * <li>LESS - pixels are drawn if the incoming pixel depth is less
 * than the stored pixel depth in the frame buffer.</li><p>
 * 
 * <li>LESS_OR_EQUAL - pixels are drawn if the incoming pixel depth
 * is less than or equal to the stored pixel depth in the frame buffer.
 * This is the default setting.</li><p>
 * 
 * <li>GREATER - pixels are drawn if the incoming pixel depth is greater
 * than the stored pixel depth in the frame buffer.</li><p>
 * 
 * <li>GREATER_OR_EQUAL - pixels are drawn if the incoming pixel depth
 * is greater than or equal to the stored pixel depth in the frame buffer.</li><p>
 * </ul>
 *
 * <li>Alpha test function - used to compare the incoming (source) alpha value
 * of each pixel with the alpha test value. If the test passes, the pixel is
 * written, otherwise the pixel is not written. The alpha test
 * function is set with the <code>setAlphaTestFunction</code>
 * method. The alpha test
 * function is one of the following:</li><p>
 * <ul>
 * <li>ALWAYS - pixels are always drawn, irrespective of the alpha
 * value. This effectively disables alpha testing.
 * This is the default setting.</li><p>
 *
 * <li>NEVER - pixels are never drawn, irrespective of the alpha
 * value.</li><p>
 *
 * <li>EQUAL - pixels are drawn if the incoming pixel alpha value is equal
 * to the alpha test value.</li><p>
 *
 * <li>NOT_EQUAL - pixels are drawn if the incoming pixel alpha value is
 * not equal to the alpha test value.</li><p>
 * 
 * <li>LESS - pixels are drawn if the incoming pixel alpha value is less
 * than the alpha test value.</li><p>
 * 
 * <li>LESS_OR_EQUAL - pixels are drawn if the incoming pixel alpha value
 * is less than or equal to the alpha test value.</li><p>
 * 
 * <li>GREATER - pixels are drawn if the incoming pixel alpha value is greater
 * than the alpha test value.</li><p>
 * 
 * <li>GREATER_OR_EQUAL - pixels are drawn if the incoming pixel alpha
 * value is greater than or equal to the alpha test value.</li><p>
 * </ul>
 *
 * <li>Alpha test value - the test value used by the alpha test function.
 * This value is compared to the alpha value of each rendered pixel.
 * The alpha test value is set with the <code>setAlphaTestValue</code>
 * method. The default alpha test value is 0.0.</li><p>
 * 
 * <li>Raster operation - the raster operation function for this
 * RenderingAttributes component object. The raster operation is
 * set with the <code>setRasterOp</code> method. The raster operation
 * is enabled or disabled with the <code>setRasterOpEnable</code>
 * method. The raster operation is one of the following:</li><p>
 * <ul>
 * <li>ROP_CLEAR - DST = 0.</li>
 * <li>ROP_AND DST = SRC & DST.</li>
 * <li>ROP_AND_REVERSE DST = SRC & ~DST.</li>
 * <li>ROP_COPY - DST = SRC. This is the default operation.</li>
 * <li>ROP_AND_INVERTED - DST = ~SRC & DST.</li>
 * <li>ROP_NOOP - DST = DST.</li>
 * <li>ROP_XOR - DST = SRC ^ DST.</li>
 * <li>ROP_OR - DST = DST | SRC.</li>
 * <li>ROP_NOR - DST = ~( DST | SRC .)</li>
 * <li>ROP_EQUIV - DST = ~( DST ^ SRC .)</li>
 * <li>ROP_INVERT - DST = ~DST.</li>
 * <li>ROP_OR_REVERSE - DST = src | ~DST.</li>
 * <li>ROP_COPY_INVERTED - DST = ~SRC.</li>
 * <li>ROP_OR_INVERTED - DST = ~SRC | DST.</li>
 * <li>ROP_NAND - DST = ~(SRC & DST.)</li>
 * <li>ROP_SET - DST = 1.</li><p>
 * </ul>
 * <li>Vertex colors - vertex colors can be ignored for this
 * RenderingAttributes object. This capability is set with the
 * <code>setIgnoreVertexColors</code> method. If 
 * ignoreVertexColors is false, per-vertex colors are used, when 
 * present in the associated geometry objects, taking
 * precedence over the ColoringAttributes color and the
 * specified Material color(s). If ignoreVertexColors is true, per-vertex
 * colors are ignored. In this case, if lighting is enabled, the 
 * Material diffuse color will be used as the object color.
 * if lighting is disabled, the ColoringAttributes color is
 * used. The default value is false.</li><p>
 * 
 * <li>Visibility flag - when set, invisible objects are
 * not rendered (subject to the visibility policy for
 * the current view), but they can be picked or collided with.
 * This flag is set with the <code>setVisible</code>
 * method. By default, the visibility flag is true.</li><p>
 * 
 * <li>Depth buffer - can be enabled or disabled for this
 * RenderingAttributes component object. The 
 * <code>setDepthBufferEnable</code> method enables
 * or disabled the depth buffer. The 
 * <code>setDepthBufferWriteEnable</code> method enables or disables
 * writing the depth buffer for this object. During the transparent
 * rendering pass, this attribute can be overridden by the
 * depthBufferFreezeTransparent attribute in the View
 * object. Transparent objects include BLENDED transparent and
 * antialiased lines and points. Transparent objects do not
 * include opaque objects or primitives rendered with
 * SCREEN_DOOR transparency. By default, the depth buffer
 * is enabled and the depth buffer write is enabled.</li><p>
 *
 * <li>Stencil buffer - can be enabled or disabled for this RenderingAttributes
 * component object using the <code>setStencilEnable</code> method. If the
 * stencil buffer is disabled, the stencil operation and function are ignored.
 * If a scene graph is rendered on a Canvas3D that does not have a stencil
 * buffer, the stencil buffer will be implicitly disabled for that
 * canvas.</li><p>
 *
 * <li>Stencil write mask - mask that controls which bits of the stencil
 * buffer are written when the stencil buffer is enabled. The default value is
 * <code>~0</code> (all ones).</li><p>
 *
 * <li>Stencil operation - a set of three stencil operations performed
 * when: 1)&nbsp;the stencil test fails; 2)&nbsp;the stencil test passes, but
 * the depth test fails; or 3)&nbsp;both the stencil test and depth test pass.
 * The stencil operations are set with the <code>setStencilOp</code>
 * method. The stencil operation is one of the following:</li><p>
 * <ul>
 * <li>STENCIL_KEEP - keeps the current value (no operation performed).
 * This is the default setting.</li>
 * <li>STENCIL_ZERO - Sets the stencil buffer value to 0.</li>
 * <li>STENCIL_REPLACE - Sets the stencil buffer value to
 * <code>refValue</code>, as specified by <code>setStencilFunction</code>.</li>
 * <li>STENCIL_INCR - Increments the current stencil buffer value.</li>
 * <li>STENCIL_DECR - Decrements the current stencil buffer value.</li>
 * <li>STENCIL_INVERT - Bitwise inverts the current stencil buffer value.</li><p>
 * </ul>
 *
 * <li>Stencil test function - used to compare the stencil reference value with
 * the per-pixel stencil value stored in the frame buffer. If the test passes,
 * the pixel is written, otherwise the pixel is not written. The stencil
 * test function, reference value, and comparison mask are set with the
 * <code>setStencilFunction</code> method. The stencil comparison mask is
 * bitwise-ANDed with both the stencil reference value and the stored stencil
 * value prior to doing the comparison. The default value for the reference value
 * is 0. The default value for the comparison mask is <code>~0</code> (all ones).
 * The stencil test function is one of the following:</li><p>
 * <ul>
 * <li>ALWAYS - pixels are always drawn, irrespective of the stencil
 * value. This effectively disables stencil testing.
 * This is the default setting.</li><p>
 *
 * <li>NEVER - pixels are never drawn, irrespective of the stencil
 * value.</li><p>
 *
 * <li>EQUAL - pixels are drawn if the stencil reference value is equal
 * to the stored stencil value in the frame buffer.</li><p>
 *
 * <li>NOT_EQUAL - pixels are drawn if the stencil reference value is
 * not equal to the stored stencil value in the frame buffer.</li><p>
 * 
 * <li>LESS - pixels are drawn if the stencil reference value is less
 * than the stored stencil value in the frame buffer.</li><p>
 * 
 * <li>LESS_OR_EQUAL - pixels are drawn if the stencil reference value
 * is less than or equal to the stored stencil value in the frame buffer.</li><p>
 * 
 * <li>GREATER - pixels are drawn if the stencil reference value is greater
 * than the stored stencil value in the frame buffer.</li><p>
 * 
 * <li>GREATER_OR_EQUAL - pixels are drawn if the stencil reference value
 * is greater than or equal to the stored stencil value in the frame buffer.</li><p>
 * </ul>
 *
 * </ul>
 *
 * <p>Note: the alpha test, depth test, and stencil functions all use
 * the same enums.</p>
 *
 * @see Appearance
 */
public class RenderingAttributes extends NodeComponent {

    /**
     * Specifies that this RenderingAttributes object
     * allows reading its alpha test value component information.
     */
    public static final int
    ALLOW_ALPHA_TEST_VALUE_READ = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_ALPHA_TEST_VALUE_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its alpha test value component information.
     */
    public static final int
    ALLOW_ALPHA_TEST_VALUE_WRITE = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_ALPHA_TEST_VALUE_WRITE;

    /**
     * Specifies that this RenderingAttributes object
     * allows reading its alpha test function component information.
     */
    public static final int
    ALLOW_ALPHA_TEST_FUNCTION_READ = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_ALPHA_TEST_FUNCTION_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its alpha test function component information.
     */
    public static final int
    ALLOW_ALPHA_TEST_FUNCTION_WRITE = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_ALPHA_TEST_FUNCTION_WRITE;

     /**
     * Specifies that this RenderingAttributes object
     * allows reading its depth test function component information.
     *
     * @since Java 3D 1.4
     */
    public static final int
    ALLOW_DEPTH_TEST_FUNCTION_READ = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_DEPTH_TEST_FUNCTION_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its depth test function component information.
     *
     * @since Java 3D 1.4
     */
    public static final int
    ALLOW_DEPTH_TEST_FUNCTION_WRITE = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_DEPTH_TEST_FUNCTION_WRITE;

    /**
     * Specifies that this RenderingAttributes object
     * allows reading its depth buffer enable and depth buffer write enable
     * component information.
     */
    public static final int
    ALLOW_DEPTH_ENABLE_READ = CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_DEPTH_ENABLE_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its depth buffer enable and depth buffer write enable
     * component information.
     *
     * @since Java 3D 1.3
     */
    public static final int ALLOW_DEPTH_ENABLE_WRITE =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_DEPTH_ENABLE_WRITE;

    /**
     * Specifies that this RenderingAttributes object
     * allows reading its visibility information.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_VISIBLE_READ =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_VISIBLE_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its visibility information.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_VISIBLE_WRITE =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_VISIBLE_WRITE;

    /**
     * Specifies that this RenderingAttributes object
     * allows reading its ignore vertex colors information.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_IGNORE_VERTEX_COLORS_READ =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_IGNORE_VERTEX_COLORS_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its ignore vertex colors information.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_IGNORE_VERTEX_COLORS_WRITE =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_IGNORE_VERTEX_COLORS_WRITE;

    /**
     * Specifies that this RenderingAttributes object
     * allows reading its raster operation information.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_RASTER_OP_READ =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_RASTER_OP_READ;

    /**
     * Specifies that this RenderingAttributes object
     * allows writing its raster operation information.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_RASTER_OP_WRITE =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_RASTER_OP_WRITE;

    /**
     * Specifies that this RenderingAttributes object allows reading
     * its stencil enable, stencil op, stencil function, and
     * stencil write mask information.
     *
     * @since Java 3D 1.4
     */
    public static final int ALLOW_STENCIL_ATTRIBUTES_READ =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_STENCIL_ATTRIBUTES_READ;

    /**
     * Specifies that this RenderingAttributes object allows writing
     * its stencil enable, stencil op, stencil function, and
     * stencil write mask information.
     *
     * @since Java 3D 1.4
     */
    public static final int ALLOW_STENCIL_ATTRIBUTES_WRITE =
    CapabilityBits.RENDERING_ATTRIBUTES_ALLOW_STENCIL_ATTRIBUTES_WRITE;


    //
    // Enums for alpha test, depth test, and stencil test
    //

    /**
     * Specifies that pixels are always drawn irrespective of the
     * values being tested.
     * Can be used to specify the alpha test function, the depth test function,
     * or the stencil function.
     * This setting effectively disables alpha, depth, or stencil testing.
     *
     * @see #setAlphaTestFunction
     * @see #setDepthTestFunction
     * @see #setStencilFunction(int,int,int)
     */
    public static final int ALWAYS = 0;