javax.media.j3d.TransparencyAttributes Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of java3d-core Show documentation
Java3D Core And Java3D Util Libraries
The newest version!
/*
 * 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 TransparencyAttributes object defines all attributes affecting
 * transparency of the object. The transparency attributes are:
 * 

 * Transparency mode - defines how transparency is applied to
 * this Appearance component object:

 * 

 * FASTEST - uses the fastest available method for transparency.

 * 
NICEST - uses the nicest available method for transparency.

 * 
SCREEN_DOOR - uses screen-door transparency. This is done using
 * an on/off stipple pattern in which the percentage of transparent pixels
 * is approximately equal to the value specified by the transparency
 * parameter.

 * 
BLENDED - uses alpha blended transparency. The blend equation is
 * specified by the srcBlendFunction and dstBlendFunction attributes.
 * The default equation is:
 * 
 * alpha_src*src +
 * (1-alpha_src)*dst
 * 
 * where alpha_src is
 * 1-transparency.
 * When this mode is used with a Raster object or with a Geometry
 * that contains per-vertex colors with alpha, the alpha values in
 * the Raster's image or in the Geometry's per-vertex colors are
 * combined with the transparency value in this TransparencyAttributes
 * object to perform blending.  In this case, the alpha value used for
 * blending at each pixel is:
 * 
 * alpha_src =
 * alpha_pix *
 * (1-transparency).
 * 
 * 

 * 
NONE - no transparency; opaque object.

 * 
 * Transparency value - the amount of transparency to be applied to this
 * Appearance component object. The transparency values are in the
 * range [0.0, 1.0], with 0.0 being fully opaque and 1.0 being
 * fully transparent.

 * 
Blend function - used in blended transparency and antialiasing
 * operations. The source function specifies the factor that is
 * multiplied by the source color. This value is added to the product
 * of the destination factor and the destination color. The default
 * source blend function is BLEND_SRC_ALPHA. The source blend function
 * is one of the following:

 * 

 * BLEND_ZERO - the blend function is f = 0
 * BLEND_ONE - the blend function is f = 1
 * BLEND_SRC_ALPHA - the blend function is f =
 * alpha_src
 * BLEND_ONE_MINUS_SRC_ALPHA - the blend function is f =
 * 1 - alpha_src
 * BLEND_DST_COLOR - the blend function is f =
 * color_dst
 * BLEND_ONE_MINUS_DST_COLOR - the blend function is f =
 * 1 - color_dst
 * BLEND_SRC_COLOR - the blend function is f =
 * color_src
 * BLEND_ONE_MINUS_SRC_COLOR - the blend function is f =
 * 1 - color_src
 * 
 * 
 */
public class TransparencyAttributes extends NodeComponent {
    /**
     * Specifies that this TransparencyAttributes object
     * allows reading its transparency mode component information.
     */
    public static final int
        ALLOW_MODE_READ = CapabilityBits.TRANSPARENCY_ATTRIBUTES_ALLOW_MODE_READ;

    /**
     * Specifies that this TransparencyAttributes object
     * allows writing its transparency mode component information.
     */
    public static final int
        ALLOW_MODE_WRITE = CapabilityBits.TRANSPARENCY_ATTRIBUTES_ALLOW_MODE_WRITE;

    /**
     * Specifies that this TransparencyAttributes object
     * allows reading its transparency value.
     */
    public static final int
        ALLOW_VALUE_READ = CapabilityBits.TRANSPARENCY_ATTRIBUTES_ALLOW_VALUE_READ;

    /**
     * Specifies that this TransparencyAttributes object
     * allows writing its transparency value.
     */
    public static final int
        ALLOW_VALUE_WRITE = CapabilityBits.TRANSPARENCY_ATTRIBUTES_ALLOW_VALUE_WRITE;

    /**
     * Specifies that this TransparencyAttributes object
     * allows reading its blend function.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_BLEND_FUNCTION_READ =
        CapabilityBits.TRANSPARENCY_ATTRIBUTES_ALLOW_BLEND_FUNCTION_READ;

    /**
     * Specifies that this TransparencyAttributes object
     * allows writing its blend function.
     *
     * @since Java 3D 1.2
     */
    public static final int ALLOW_BLEND_FUNCTION_WRITE =
        CapabilityBits.TRANSPARENCY_ATTRIBUTES_ALLOW_BLEND_FUNCTION_WRITE;

    /**
     * Use the fastest available method for transparency.
     * @see #setTransparencyMode
     */
    public static final int FASTEST            = 0;

    /**
     * Use the nicest available method for transparency.
     * @see #setTransparencyMode
     */
    public static final int NICEST             = 1;

    /**
     * Use alpha blended transparency.  The blend equation is
     * specified by the srcBlendFunction and dstBlendFunction attributes.
     * The default equation is:
     * 
     * alpha_src*src +
     * (1-alpha_src)*dst
     * 
     * where alpha_src is
     * 1-transparency.
     * When this mode is used with a Raster object or with a Geometry
     * that contains per-vertex colors with alpha, the alpha values in
     * the Raster's image or in the Geometry's per-vertex colors are
     * combined with the transparency value in this TransparencyAttributes
     * object to perform blending.  In this case, the alpha value used for
     * blending at each pixel is:
     * 
     * alpha_src =
     * alpha_pix *
     * (1-transparency).
     * 
     *
     * @see #setTransparencyMode
     * @see #setSrcBlendFunction
     * @see #setDstBlendFunction
     */
    public static final int BLENDED     = 2;

    /**
     * Use screen-door transparency.  This is done using an on/off stipple
     * pattern where the percentage of pixels that are transparent is
     * approximately equal to the value specified by the transparency
     * parameter.
     * @see #setTransparencyMode
     */
    public static final int SCREEN_DOOR = 3;

    /**
     * No transparency, opaque object.
     * @see #setTransparencyMode
     */
    public static final int NONE     = 4;

    /**
     * Blend function: f = 0.
     * @see #setSrcBlendFunction
     * @see #setDstBlendFunction
     *
     * @since Java 3D 1.2
     */
    public static final int BLEND_ZERO = 0;

    /**
     * Blend function: f = 1.
     * @see #setSrcBlendFunction
     * @see #setDstBlendFunction
     *
     * @since Java 3D 1.2
     */
    public static final int BLEND_ONE = 1;

    /**
     * Blend function:
     * f = alpha_src.
     * @see #setSrcBlendFunction
     * @see #setDstBlendFunction
     *
     * @since Java 3D 1.2
     */
    public static final int BLEND_SRC_ALPHA = 2;

    /**
     * Blend function:
     * f = 1-alpha_src.
     * @see #setSrcBlendFunction
     * @see #setDstBlendFunction
     *
     * @since Java 3D 1.2
     */
    public static final int BLEND_ONE_MINUS_SRC_ALPHA = 3;

    /**
     * Blend function:
     * f = color_dst.
     * Note that this function may only be used as a source
     * blend function.
     * @see #setSrcBlendFunction
     *
     * @since Java 3D 1.4
     */
    public static final int BLEND_DST_COLOR = 4;

    /**
     * Blend function:
     * f = 1-color_dst.
     * Note that this function may only be used as a source
     * blend function.
     * @see #setSrcBlendFunction
     *
     * @since Java 3D 1.4
     */
    public static final int BLEND_ONE_MINUS_DST_COLOR = 5;

    /**
     * Blend function:
     * f = color_src.
     * Note that this function may only be used as a destination
     * blend function.
     * @see #setDstBlendFunction
     *
     * @since Java 3D 1.4
     */
    public static final int BLEND_SRC_COLOR = 6;

    /**
     * Blend function:
     * f = 1-color_src.
     * Note that this function may only be used as a destination
     * blend function.
     * @see #setDstBlendFunction
     *
     * @since Java 3D 1.4
     */
    public static final int BLEND_ONE_MINUS_SRC_COLOR = 7;

    static final int BLEND_CONSTANT_COLOR = 8;

    static final int MAX_BLEND_FUNC_TABLE_SIZE = 9;

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

    /**
     * Constructs a TransparencyAttributes object with default parameters.
     * The default values are as follows:
     * 
     * transparency mode : NONE

     * transparency value : 0.0

     * source blend function : BLEND_SRC_ALPHA

     * destination blend function : BLEND_ONE_MINUS_SRC_ALPHA

     * 
     */
    public TransparencyAttributes() {
	// Just use the default for all attributes
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);
    }

    /**
     * Construct TransparencyAttributes object with specified values.
     * @param tMode the transparency mode
     * @param tVal the transparency value
     * @exception IllegalArgumentException if
     * tMode is a value other than
     * NONE, FASTEST, NICEST,
     * SCREEN_DOOR, or BLENDED
     *
     */
    public TransparencyAttributes(int tMode, float tVal){
	this(tMode, tVal, BLEND_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA);
     }

    /**
     * Construct TransparencyAttributes object with specified values.
     * @param tMode the transparency mode
     * @param tVal the transparency value
     * @param srcBlendFunction the blend function to be used for the source
     * color, one of BLEND_ZERO, BLEND_ONE,
     * BLEND_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA,
     * BLEND_DST_COLOR, or BLEND_ONE_MINUS_DST_COLOR.
     * @param dstBlendFunction the blend function to be used for the
     * destination
     * color, one of BLEND_ZERO, BLEND_ONE,
     * BLEND_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA,
     * BLEND_SRC_COLOR, or BLEND_ONE_MINUS_SRC_COLOR.
     * @exception IllegalArgumentException if
     * tMode is a value other than
     * NONE, FASTEST, NICEST,
     * SCREEN_DOOR, or BLENDED
     * @exception IllegalArgumentException if
     * srcBlendFunction or dstBlendFunction
     * is a value other than one of the supported functions listed above.
     *
     * @since Java 3D 1.2
     */
    public TransparencyAttributes(int tMode,
				  float tVal,
				  int srcBlendFunction,
				  int dstBlendFunction) {
	if ((tMode < FASTEST) ||(tMode > NONE)) {
	    throw new IllegalArgumentException(J3dI18N.getString("TransparencyAttributes6"));
	}

        switch (srcBlendFunction) {
        case BLEND_ZERO:
        case BLEND_ONE:
        case BLEND_SRC_ALPHA:
        case BLEND_ONE_MINUS_SRC_ALPHA:
        case BLEND_DST_COLOR:
        case BLEND_ONE_MINUS_DST_COLOR:
            break;
            default:
            throw new IllegalArgumentException(J3dI18N.getString("TransparencyAttributes7"));
        }

        switch (dstBlendFunction) {
        case BLEND_ZERO:
        case BLEND_ONE:
        case BLEND_SRC_ALPHA:
        case BLEND_ONE_MINUS_SRC_ALPHA:
        case BLEND_SRC_COLOR:
        case BLEND_ONE_MINUS_SRC_COLOR:
            break;
            default:
            throw new IllegalArgumentException(J3dI18N.getString("TransparencyAttributes8"));
        }

        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);

        ((TransparencyAttributesRetained)this.retained).initTransparencyMode(tMode);
        ((TransparencyAttributesRetained)this.retained).initTransparency(tVal);
        ((TransparencyAttributesRetained)this.retained).initSrcBlendFunction(srcBlendFunction);
        ((TransparencyAttributesRetained)this.retained).initDstBlendFunction(dstBlendFunction);
    }

    /**
     * Sets the transparency mode for this
     * appearance component object.
     * @param transparencyMode the transparency mode to be used, one of
     * NONE, FASTEST, NICEST,
     * SCREEN_DOOR, or BLENDED
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     * @exception IllegalArgumentException if
     * transparencyMode is a value other than
     * NONE, FASTEST, NICEST,
     * SCREEN_DOOR, or BLENDED
     */
    public void setTransparencyMode(int transparencyMode) {
	if (isLiveOrCompiled())
	  if (!this.getCapability(ALLOW_MODE_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes0"));

	if ((transparencyMode < FASTEST) || (transparencyMode > NONE)) {
		throw new IllegalArgumentException(J3dI18N.getString("TransparencyAttributes6"));
	}

	if (isLive())
	    ((TransparencyAttributesRetained)this.retained).setTransparencyMode(transparencyMode);
	else
	    ((TransparencyAttributesRetained)this.retained).initTransparencyMode(transparencyMode);
    }



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

        return ((TransparencyAttributesRetained)this.retained).getTransparencyMode();
    }

    /**
     * Sets this appearance's transparency.
     * @param transparency the appearance's transparency
     * in the range [0.0, 1.0] with 0.0 being
     * fully opaque and 1.0 being fully transparent
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void setTransparency(float transparency) {
	if (isLiveOrCompiled())
	  if (!this.getCapability(ALLOW_VALUE_WRITE))
	    throw new CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes2"));


	if (isLive())
	    ((TransparencyAttributesRetained)this.retained).setTransparency(transparency);
	else
	    ((TransparencyAttributesRetained)this.retained).initTransparency(transparency);

    }


    /**
     * Retrieves this appearance's transparency.
     * @return the appearance's transparency
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public float getTransparency() {
	if (isLiveOrCompiled())
	  if (!this.getCapability(ALLOW_VALUE_READ))
	    throw new CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes3"));

        return ((TransparencyAttributesRetained)this.retained).getTransparency();
    }

    /**
     * Sets the source blend function used in blended transparency
     * and antialiasing operations.  The source function specifies the
     * factor that is multiplied by the source color; this value is
     * added to the product of the destination factor and the
     * destination color.  The default source blend function is
     * BLEND_SRC_ALPHA.
     *
     * @param blendFunction the blend function to be used for the source
     * color, one of BLEND_ZERO, BLEND_ONE,
     * BLEND_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA,
     * BLEND_DST_COLOR, or BLEND_ONE_MINUS_DST_COLOR.
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     * @exception IllegalArgumentException if blendFunction
     * is a value other than one of the supported functions listed above.
     *
     * @since Java 3D 1.2
     */
    public void setSrcBlendFunction(int blendFunction) {
	if (isLiveOrCompiled())
	    if (!this.getCapability(ALLOW_BLEND_FUNCTION_WRITE))
		throw new
		    CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes4"));

        switch (blendFunction) {
        case BLEND_ZERO:
        case BLEND_ONE:
        case BLEND_SRC_ALPHA:
        case BLEND_ONE_MINUS_SRC_ALPHA:
        case BLEND_DST_COLOR:
        case BLEND_ONE_MINUS_DST_COLOR:
            break;
            default:
            throw new IllegalArgumentException(J3dI18N.getString("TransparencyAttributes7"));
        }

	if (isLive())
	    ((TransparencyAttributesRetained)this.retained).setSrcBlendFunction(blendFunction);
	else
	    ((TransparencyAttributesRetained)this.retained).initSrcBlendFunction(blendFunction);
    }



    /**
     * Gets the source blend function for this
     * TransparencyAttributes object.
     * @return the source blend function.
     * @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 int getSrcBlendFunction() {
	if (isLiveOrCompiled())
	    if (!this.getCapability(ALLOW_BLEND_FUNCTION_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes5"));
	return ((TransparencyAttributesRetained)this.retained).getSrcBlendFunction();
    }

    /**
     * Sets the destination blend function used in blended transparency
     * and antialiasing operations.  The destination function specifies the
     * factor that is multiplied by the destination color; this value is
     * added to the product of the source factor and the
     * source color.  The default destination blend function is
     * BLEND_ONE_MINUS_SRC_ALPHA.
     *
     * @param blendFunction the blend function to be used for the destination
     * color, one of BLEND_ZERO, BLEND_ONE,
     * BLEND_SRC_ALPHA, BLEND_ONE_MINUS_SRC_ALPHA,
     * BLEND_SRC_COLOR, or BLEND_ONE_MINUS_SRC_COLOR.
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     * @exception IllegalArgumentException if blendFunction
     * is a value other than one of the supported functions listed above.
     *
     * @since Java 3D 1.2
     */
    public void setDstBlendFunction(int blendFunction) {
	if (isLiveOrCompiled())
	    if (!this.getCapability(ALLOW_BLEND_FUNCTION_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes4"));

        switch (blendFunction) {
        case BLEND_ZERO:
        case BLEND_ONE:
        case BLEND_SRC_ALPHA:
        case BLEND_ONE_MINUS_SRC_ALPHA:
        case BLEND_SRC_COLOR:
        case BLEND_ONE_MINUS_SRC_COLOR:
            break;
            default:
            throw new IllegalArgumentException(J3dI18N.getString("TransparencyAttributes8"));
        }

	if (isLive())
	    ((TransparencyAttributesRetained)this.retained).setDstBlendFunction(blendFunction);
	else
	    ((TransparencyAttributesRetained)this.retained).initDstBlendFunction(blendFunction);
    }



    /**
     * Gets the destination blend function for this
     * TransparencyAttributes object.
     * @return the destination blend function.
     * @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 int getDstBlendFunction() {
	if (isLiveOrCompiled())
	    if (!this.getCapability(ALLOW_BLEND_FUNCTION_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("TransparencyAttributes5"));

	return ((TransparencyAttributesRetained)this.retained).getDstBlendFunction();
    }

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


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



   /**
     * Copies all node information from originalNodeComponent into
     * the current node.  This method is called from the
     * duplicateNode 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 true, causes the
     *  duplicateOnCloneTree flag to be ignored.  When
     *  false, the value of each node's
     *  duplicateOnCloneTree 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);

	TransparencyAttributesRetained attr =
	    (TransparencyAttributesRetained) originalNodeComponent.retained;
	TransparencyAttributesRetained rt =
	    (TransparencyAttributesRetained) retained;

	rt.initTransparencyMode(attr.getTransparencyMode());
	rt.initTransparency(attr.getTransparency());
	rt.initSrcBlendFunction(attr.getSrcBlendFunction());
	rt.initDstBlendFunction(attr.getDstBlendFunction());
    }

}