edu.umd.cs.jazz
Class ZFadeGroup

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject
        |
        +--edu.umd.cs.jazz.ZNode
              |
              +--edu.umd.cs.jazz.ZGroup
                    |
                    +--edu.umd.cs.jazz.ZFadeGroup

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable, ZSerializable

public class ZFadeGroup

extends ZGroup

implements ZSerializable, java.io.Serializable

ZFadeGroup is a group node that controls transparency and fading of its sub-tree. Inserting a fade node into the tree lets you control transparency and minimum/maximum magnification of all its descendants. If this node is rendered below its minimum magnification, or above its maximum magnification, it and its children will not be rendered. The node and its subtree will be smoothly faded out as the minimum or maximum magnification is approached.

Four types of fading have been implemented, selected with the setFadeType method:

CAMERA_MAG fades a node on camera magnification.
COMPOSITE_MAG fades on composite camera magnification.
ABSOLUTE_SCREEN_SIZE fades on absolute screen size in pixels.
PERCENT_OF_CAMERA fades on percentage of the camera size.

ZSceneGraphEditor provides a convenience mechanism to locate, create and manage nodes of this type.

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

Author:

Ben Bederson

See Also:

Serialized Form

CAMERA_MAG

public static final short CAMERA_MAG

FadeType: Fade on camera magnification.

See Also:

Constant Field Values

COMPOSITE_MAG

public static final short COMPOSITE_MAG

FadeType: Fade on composite magnification.

See Also:

Constant Field Values

ABSOLUTE_SCREEN_SIZE

public static final short ABSOLUTE_SCREEN_SIZE

FadeType: Fade on absolute screen size in pixels.

See Also:

Constant Field Values

PERCENT_OF_CAMERA

public static final short PERCENT_OF_CAMERA

FadeType: Fade on percentage of camera size.

See Also:

Constant Field Values

fadeType_DEFAULT

public static final short fadeType_DEFAULT

See Also:

Constant Field Values

alpha_DEFAULT

public static final double alpha_DEFAULT

See Also:

Constant Field Values

minMag_DEFAULT

public static final double minMag_DEFAULT

See Also:

Constant Field Values

maxMag_DEFAULT

public static final double maxMag_DEFAULT

See Also:

Constant Field Values

fadeRange_DEFAULT

public static final double fadeRange_DEFAULT

See Also:

Constant Field Values

ZFadeGroup

public ZFadeGroup()

Constructs a new empty fade group node.

ZFadeGroup

public ZFadeGroup(ZNode child)

Constructs a new fade group node with the specified node as a child of the new group.

Parameters:

child - Child of the new group node.

getAlpha

public double getAlpha()

Get the alpha value (opacity) for this node. Alpha values are applied multiplicitively with the current alpha values at render time.

Returns:

The alpha value for this node.

setAlpha

public void setAlpha(double alpha)

Set the alpha value (opacity) for this node. Alpha values are applied multiplicitively with the current alpha values at render time. Alpha valus range from 0 to 1 where 0 represents a node being completely transparent, and 1 represents a node being completely opaque. Alpha is clamped to the range [0, 1].

Parameters:

alpha - The new alpha value for this node.

getMinMag

public double getMinMag()

Get the minimumn magnification for this node, as defined by the fade type.

Returns:

The minimum magnification of this node

setMinMag

public void setMinMag(double minMag)

Set the minimumn magnification for this node.
This node will not be rendered when the current rendering camera's magnification is less than then specified minimum magnification for this node. The node with smoothly fade from its regular opacity to completely transparent during a small magnification range just before the minimum magnification is reached. This transparency control affects the entire sub-tree rooted at this node. The minimum magnification has a minimum value of 0, and is clamped to that value.

If fade type is CAMERA_MAG, then minMag is the minimum magnification for this node.
If fade type is COMPOSITE_MAG, then minMag is the minimum composite magnification for this node.
if fade type is ABSOLUTE_SCREEN_SIZE, then minMag is the minimum size of the node in pixels.
if fade type is PERCENT_OF_CAMERA, then minMag is the minimum size, as a percentage of the camera size.

Parameters:

minMag - The new minimumn magnification for this node.

getMaxMag

public double getMaxMag()

Get the maximum magnification for this node, as defined by the fade type.

Returns:

The maximum magnification of this node

setMaxMag

public void setMaxMag(double maxMag)

Set the maximumn magnification for this node.
This node will not be rendered when the current rendering camera's magnification is greater than then specified maximum magnification for this node. The node with smoothly fade from its regular opacity to completely transparent during a small magnification range just before the maximum magnification is reached. This transparency control affects the entire sub-tree rooted at this node. To disable the maximum magnification feature, set the value to any negative value.

If fade type is CAMERA_MAG, then maxMag is the maximum magnification for this node.
If fade type is COMPOSITE_MAG, then maxMag is the maximum composite magnification for this node.
if fade type is ABSOLUTE_SCREEN_SIZE, then maxMag is the maximum size of the node in pixels.
if fade type is PERCENT_OF_CAMERA, then maxMag is the maximum size, as a percentage of the camera size.

Parameters:

maxMag - The new maximumn magnification for this node.

setFadeRange

public void setFadeRange(double fadeRange)

Sets the percentage of magnification change over which an object is faded in or out as it reaches its minimum or maximum magnification. A value of 0 means there is no fading at all and the object just jumps in and out of visibility. A value of 0.3 is reasonable, meaning it fades in and out over 30% of its size. The input is clamped between 0 and 1.

Parameters:

fadeRange - the new fade range [0, 1]

getFadeRange

public double getFadeRange()

Returns the current fade range of this node.

Returns:

the current fade range

See Also:

setFadeRange(double)

setFadeType

public void setFadeType(short aFadeType)

Set the type of fading that this node implements. Must be CAMERA_MAG, COMPOSITE_MAG, ABSOLUTE_SCREEN_SIZE or PERCENT_OF_CAMERA.
CAMERA_MAG fades a node on camera magnification.
COMPOSITE_MAG fades on composite camera magnification.
ABSOLUTE_SCREEN_SIZE fades on absolute screen size in pixels.
PERCENT_OF_CAMERA fades on percentage of the camera size.

getFadeType

public int getFadeType()

Determine the type of fading that this node implements.

Returns:

They fade type.

isVisible

public boolean isVisible(ZSceneGraphPath path)

Determines if this fade node is visible.

Parameters:

path - A scenegraph path.

Returns:

True if this node is visible at the current magnification.

isVisible

public boolean isVisible(double metric)

Internal method: determines if this fade node is visible at the specified magnification.

Parameters:

metric - The magnification, as defined by fade type.

Returns:

True if this node is visible at the specified magnification.

getComposite

protected java.awt.Composite getComposite(java.awt.Composite currentComposite,
                                          double metric)

Internal method to compute and access an alpha Composite given the current rendering composite, and the current metric. The metric can be magnification, composite magnification, absolute size in pixels, or percentage of camera size in pixels, depending on fadeType. This method determines the alpha based on this node's alpha value, minimum metric, and maximum metric.

Parameters:

currentComposite - The composite in the current render context

Returns:

Composite The Composite to use to render this node

render

public void render(ZRenderContext renderContext)

Renders this node which results in the node's visual component getting rendered, followed by its children getting rendered.

The transform, clip, and composite will be set appropriately when this object is rendered. It is up to this object to restore the transform, clip, and composite of the Graphics2D if this node changes any of them. However, the color, font, and stroke are unspecified by Jazz. This object should set those things if they are used, but they do not need to be restored.

Overrides:

render in class ZGroup

Parameters:

renderContext - The graphics context to use for rendering.

pick

public boolean pick(java.awt.geom.Rectangle2D rect,
                    ZSceneGraphPath path)

Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this as searched in reverse (front-to-back) order. This performs a depth-first search, first picking children. Only returns a node if this is "pickable". If no nodes in the sub-tree are picked, then this node's visual component is picked.

If childrenPickable is false, then this will never return a child as the picked node. Instead, this node will be returned if any children are picked, or if this node's visual component is picked. Else, it will return null.

Overrides:

pick in class ZGroup

Parameters:

rect - Coordinates of pick rectangle in local coordinates

path - The path through the scenegraph to the picked node. Modified by this call.

Returns:

The picked node, or null if none

See Also:

ZDrawingSurface.pick(int, int)

writeObject

public void writeObject(ZObjectOutputStream out)
                 throws java.io.IOException

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

Overrides:

writeObject in class ZGroup

Parameters:

out - The stream that this object writes into

java.io.IOException

writeObjectRecurse

public void writeObjectRecurse(ZObjectOutputStream out)
                        throws java.io.IOException

Specify which objects this object references in order to write out the scenegraph properly

Specified by:

writeObjectRecurse in interface ZSerializable

Overrides:

writeObjectRecurse in class ZGroup

Parameters:

out - The stream that this object writes into

java.io.IOException

setState

public void setState(java.lang.String fieldType,
                     java.lang.String fieldName,
                     java.lang.Object fieldValue)

Set some state of this object as it gets read back in. After the object is created with its default no-arg constructor, this method will be called on the object once for each bit of state that was written out through calls to ZObjectOutputStream.writeState() within the writeObject method.

Specified by:

setState in interface ZSerializable

Overrides:

setState in class ZGroup

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field