diff options
Diffstat (limited to 'src/javax/media/j3d/TransparencyAttributes.java')
| -rw-r--r-- | src/javax/media/j3d/TransparencyAttributes.java | 643 |
1 files changed, 643 insertions, 0 deletions
diff --git a/src/javax/media/j3d/TransparencyAttributes.java b/src/javax/media/j3d/TransparencyAttributes.java new file mode 100644 index 0000000..2779f38 --- /dev/null +++ b/src/javax/media/j3d/TransparencyAttributes.java @@ -0,0 +1,643 @@ +/* + * 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:<p> + * <ul> + * <li>Transparency mode - defines how transparency is applied to + * this Appearance component object:</li><p> + * <ul> + * <li>FASTEST - uses the fastest available method for transparency.</li><p> + * <li>NICEST - uses the nicest available method for transparency.</li><p> + * <li>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.</li><p> + * <li>BLENDED - uses alpha blended transparency. The blend equation is + * specified by the srcBlendFunction and dstBlendFunction attributes. + * The default equation is: + * <ul> + * <code>alpha<sub><font size=-1>src</font></sub>*src + + * (1-alpha<sub><font size=-1>src</font></sub>)*dst</code> + * </ul> + * where <code>alpha<sub><font size=-1>src</font></sub></code> is + * <code>1-transparency</code>. + * 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: + * <ul> + * <code>alpha<sub><font size=-1>src</font></sub> = + * alpha<sub><font size=-1>pix</font></sub> * + * (1-transparency)</code>. + * </ul> + * </li><p> + * <li>NONE - no transparency; opaque object.</li><p> + * </ul> + * <li>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.</li><p> + * <li>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:</li><p> + * <ul> + * <li>BLEND_ZERO - the blend function is <code>f = 0</code></li> + * <li>BLEND_ONE - the blend function is <code>f = 1</code></li> + * <li>BLEND_SRC_ALPHA - the blend function is <code>f = + * alpha<sub><font size=-1>src</font></sub></code></li> + * <li>BLEND_ONE_MINUS_SRC_ALPHA - the blend function is <code>f = + * 1 - alpha<sub><font size=-1>src</font></sub></code></li> + * <li>BLEND_DST_COLOR - the blend function is <code>f = + * color<sub><font size=-1>dst</font></sub></code></li> + * <li>BLEND_ONE_MINUS_DST_COLOR - the blend function is <code>f = + * 1 - color<sub><font size=-1>dst</font></sub></code></li> + * <li>BLEND_SRC_COLOR - the blend function is <code>f = + * color<sub><font size=-1>src</font></sub></code></li> + * <li>BLEND_ONE_MINUS_SRC_COLOR - the blend function is <code>f = + * 1 - color<sub><font size=-1>src</font></sub></code></li> + * </ul> + * </ul> + */ +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: + * <ul> + * <code>alpha<sub><font size=-1>src</font></sub>*src + + * (1-alpha<sub><font size=-1>src</font></sub>)*dst</code> + * </ul> + * where <code>alpha<sub><font size=-1>src</font></sub></code> is + * <code>1-transparency</code>. + * 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: + * <ul> + * <code>alpha<sub><font size=-1>src</font></sub> = + * alpha<sub><font size=-1>pix</font></sub> * + * (1-transparency)</code>. + * </ul> + * + * @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: <code>f = 0</code>. + * @see #setSrcBlendFunction + * @see #setDstBlendFunction + * + * @since Java 3D 1.2 + */ + public static final int BLEND_ZERO = 0; + + /** + * Blend function: <code>f = 1</code>. + * @see #setSrcBlendFunction + * @see #setDstBlendFunction + * + * @since Java 3D 1.2 + */ + public static final int BLEND_ONE = 1; + + /** + * Blend function: + * <code>f = alpha<sub><font size=-1>src</font></sub></code>. + * @see #setSrcBlendFunction + * @see #setDstBlendFunction + * + * @since Java 3D 1.2 + */ + public static final int BLEND_SRC_ALPHA = 2; + + /** + * Blend function: + * <code>f = 1-alpha<sub><font size=-1>src</font></sub></code>. + * @see #setSrcBlendFunction + * @see #setDstBlendFunction + * + * @since Java 3D 1.2 + */ + public static final int BLEND_ONE_MINUS_SRC_ALPHA = 3; + + /** + * Blend function: + * <code>f = color<sub><font size=-1>dst</font></sub></code>. + * <p>Note that this function may <i>only</i> be used as a source + * blend function.</p> + * @see #setSrcBlendFunction + * + * @since Java 3D 1.4 + */ + public static final int BLEND_DST_COLOR = 4; + + /** + * Blend function: + * <code>f = 1-color<sub><font size=-1>dst</font></sub></code>. + * <p>Note that this function may <i>only</i> be used as a source + * blend function.</p> + * @see #setSrcBlendFunction + * + * @since Java 3D 1.4 + */ + public static final int BLEND_ONE_MINUS_DST_COLOR = 5; + + /** + * Blend function: + * <code>f = color<sub><font size=-1>src</font></sub></code>. + * <p>Note that this function may <i>only</i> be used as a destination + * blend function.</p> + * @see #setDstBlendFunction + * + * @since Java 3D 1.4 + */ + public static final int BLEND_SRC_COLOR = 6; + + /** + * Blend function: + * <code>f = 1-color<sub><font size=-1>src</font></sub></code>. + * <p>Note that this function may <i>only</i> be used as a destination + * blend function.</p> + * @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: + * <ul> + * transparency mode : <code>NONE</code><br> + * transparency value : 0.0<br> + * source blend function : <code>BLEND_SRC_ALPHA</code><br> + * destination blend function : <code>BLEND_ONE_MINUS_SRC_ALPHA</code><br> + * </ul> + */ + 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 + * <code>tMode</code> is a value other than + * <code>NONE</code>, <code>FASTEST</code>, <code>NICEST</code>, + * <code>SCREEN_DOOR</code>, or <code>BLENDED</code> + * + */ + 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 <code>BLEND_ZERO</code>, <code>BLEND_ONE</code>, + * <code>BLEND_SRC_ALPHA</code>, <code>BLEND_ONE_MINUS_SRC_ALPHA</code>, + * <code>BLEND_DST_COLOR</code>, or <code>BLEND_ONE_MINUS_DST_COLOR</code>. + * @param dstBlendFunction the blend function to be used for the + * destination + * color, one of <code>BLEND_ZERO</code>, <code>BLEND_ONE</code>, + * <code>BLEND_SRC_ALPHA</code>, <code>BLEND_ONE_MINUS_SRC_ALPHA</code>, + * <code>BLEND_SRC_COLOR</code>, or <code>BLEND_ONE_MINUS_SRC_COLOR</code>. + * @exception IllegalArgumentException if + * <code>tMode</code> is a value other than + * <code>NONE</code>, <code>FASTEST</code>, <code>NICEST</code>, + * <code>SCREEN_DOOR</code>, or <code>BLENDED</code> + * @exception IllegalArgumentException if + * <code>srcBlendFunction</code> or <code>dstBlendFunction</code> + * 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 + * <code>NONE</code>, <code>FASTEST</code>, <code>NICEST</code>, + * <code>SCREEN_DOOR</code>, or <code>BLENDED</code> + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + * @exception IllegalArgumentException if + * <code>transparencyMode</code> is a value other than + * <code>NONE</code>, <code>FASTEST</code>, <code>NICEST</code>, + * <code>SCREEN_DOOR</code>, or <code>BLENDED</code> + */ + 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 + * <code>BLEND_SRC_ALPHA</code>. + * + * @param blendFunction the blend function to be used for the source + * color, one of <code>BLEND_ZERO</code>, <code>BLEND_ONE</code>, + * <code>BLEND_SRC_ALPHA</code>, <code>BLEND_ONE_MINUS_SRC_ALPHA</code>, + * <code>BLEND_DST_COLOR</code>, or <code>BLEND_ONE_MINUS_DST_COLOR</code>. + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + * @exception IllegalArgumentException if <code>blendFunction</code> + * 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 + * <code>BLEND_ONE_MINUS_SRC_ALPHA</code>. + * + * @param blendFunction the blend function to be used for the destination + * color, one of <code>BLEND_ZERO</code>, <code>BLEND_ONE</code>, + * <code>BLEND_SRC_ALPHA</code>, <code>BLEND_ONE_MINUS_SRC_ALPHA</code>, + * <code>BLEND_SRC_COLOR</code>, or <code>BLEND_ONE_MINUS_SRC_COLOR</code>. + * + * @exception CapabilityNotSetException if appropriate capability is + * not set and this object is part of live or compiled scene graph + * @exception IllegalArgumentException if <code>blendFunction</code> + * 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 <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); + + 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()); + } + +} |