/*
* 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());
}
}