orderedgroup.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: OrderedGroup.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:13 $
 * $State: Exp $
 */

package javax.media.j3d;

import java.util.Arrays;

/**
 * The OrderedGroup node is a Group that ensures its children render
 * in a specified order.  In addition to the list of children
 * inherited from the base Group class, OrderedGroup defines an
 * integer array of child indices that specify the order in which its
 * children are rendered.  This provides a level of indirection in
 * determining the rendering order of its children.  By default, the
 * child index order array is null, and the children are rendered in
 * increasing index order.
 *
 * <p>
 * When the child index order array is non-null, it must be the same
 * length as the number of children.  Every entry in the array must
 * have a unique value between 0 and <code>numChildren-1</code> (i.e.,
 * there must be no duplicate values and no missing indices).  The
 * order that the child indices appear in the child index order array
 * determines the order in which the children are rendered.  The child
 * at <code>childIndexOrder[0]</code> is rendered first, followed by
 * <code>childIndexOrder[1]</code>, and so on, with the child at
 * <code>childIndexOrder[numChildren-1]</code> rendered
 * last.
 *
 * <p>
 * The child index order array only affects rendering.  List
 * operations that refer to a child by index, such as getChild(index),
 * will not be altered by the entries in this array.  They will get,
 * enumerate, add, remove, etc., the children based on the actual
 * index in the group node.  However, some of the list operations,
 * such as addChild, removeChild, etc., will update the child index
 * order array as a result of their operation.  For example,
 * removeChild will remove the entry in the child index order array
 * corresponding to the removed child's index and adjust the remaining
 * entries accordingly.  See the documentation for these methods for
 * more details.
 */

public class OrderedGroup extends Group {

    private boolean checkArr[] = null;

    /**
     * Specifies that this OrderedGroup node
     * allows reading its child index order information.
     *
     * @since Java 3D 1.3
     */
    public static final int ALLOW_CHILD_INDEX_ORDER_READ =
	CapabilityBits.ORDERED_GROUP_ALLOW_CHILD_INDEX_ORDER_READ;

    /**
     * Specifies that this OrderedGroup node
     * allows writing its child index order information.
     *
     * @since Java 3D 1.3
     */
    public static final int ALLOW_CHILD_INDEX_ORDER_WRITE =
	CapabilityBits.ORDERED_GROUP_ALLOW_CHILD_INDEX_ORDER_WRITE;

    // Array for setting default read capabilities
    private static final int[] readCapabilities = {
        ALLOW_CHILD_INDEX_ORDER_READ
    };

    /**
     * Constructs and initializes a new OrderedGroup node object.
     * The childIndexOrder array is initialized to null, meaning
     * that its children are rendered in increasing index order.
     */
    public OrderedGroup() {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);        
    }


    /**
     * Sets the childIndexOrder array.  If the specified array is
     * null, this node's childIndexOrder array is set to null.  Its
     * children will then be rendered in increasing index order.  If
     * the specified array is not null, the entire array is copied to
     * this node's childIndexOrder array.  In this case, the length of
     * the array must be equal to the number of children in this
     * group, and every entry in the array must have a unique value
     * between 0 and <code>numChildren-1</code> (i.e., there must be
     * no duplicate values and no missing indices).
     *
     * @param childIndexOrder the array that is copied into this
     * node's child index order array; this can be null
     *
     * @exception IllegalArgumentException if the specified array is
     * non-null and any of the following are true:
     * <ul>
     * <li><code>childIndexOrder.length != numChildren</code>;</li>
     * <li><code>childIndexOrder[</code><i>i</i><code>] < 0</code>,
     * for <i>i</i> in <code>[0, numChildren-1]</code>;</li>
     * <li><code>childIndexOrder[</code><i>i</i><code>] >= numChildren</code>,
     * for <i>i</i> in <code>[0, numChildren-1]</code>;</li>
     * <li><code>childIndexOrder[</code><i>i</i><code>] ==
     * childIndexOrder[</code><i>j</i><code>]</code>,
     * for <i>i</i>,<i>j</i> in <code>[0, numChildren-1]</code>,
     * <i>i</i> <code>!=</code> <i>j</i>;</li>
     * </ul>
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     *
     * @since Java 3D 1.3
     */
    public void setChildIndexOrder(int[] childIndexOrder) {
	verifyChildIndexOrderArray(childIndexOrder, 0);

	((OrderedGroupRetained)retained).setChildIndexOrder(childIndexOrder);
    }


    /**
     * Retrieves the current childIndexOrder array.
     *
     * @return a copy of this node's childIndexOrder array; this
     * can be null.
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     *
     * @since Java 3D 1.3
     */
    public int[] getChildIndexOrder() {

	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_CHILD_INDEX_ORDER_READ))
		throw new 
		    CapabilityNotSetException(J3dI18N.getString("OrderedGroup5"));

	return ((OrderedGroupRetained)this.retained).getChildIndexOrder();
    }

    /**
     * Appends the specified child node to this group node's list of
     * children, and sets the child index order array to the specified
     * array.  If the specified array is null, this node's
     * childIndexOrder array is set to null.  Its children will then
     * be rendered in increasing index order.  If the specified array
     * is not null, the entire array is copied to this node's
     * childIndexOrder array.  In this case, the length of the array
     * must be equal to the number of children in this group after the
     * new child has been added, and every entry in the array must
     * have a unique value between 0 and <code>numChildren-1</code>
     * (i.e., there must be no duplicate values and no missing
     * indices).
     *
     * @param child the child to add to this node's list of children
     *
     * @param childIndexOrder the array that is copied into this
     * node's child index order array; this can be null
     *
     * @exception CapabilityNotSetException if the appropriate capability is
     * not set and this group node is part of live or compiled scene graph
     *
     * @exception RestrictedAccessException if this group node is part
     * of live
     * or compiled scene graph and the child node being added is not
     * a BranchGroup node
     *
     * @exception MultipleParentException if <code>child</code> has already
     * been added as a child of another group node.
     *
     * @exception IllegalArgumentException if the specified array is
     * non-null and any of the following are true:
     * <ul>
     * <li><code>childIndexOrder.length != numChildren</code>;</li>
     * <li><code>childIndexOrder[</code><i>i</i><code>] < 0</code>,
     * for <i>i</i> in <code>[0, numChildren-1]</code>;</li>
     * <li><code>childIndexOrder[</code><i>i</i><code>] >= numChildren</code>,
     * for <i>i</i> in <code>[0, numChildren-1]</code>;</li>
     * <li><code>childIndexOrder[</code><i>i</i><code>] ==
     * childIndexOrder[</code><i>j</i><code>]</code>,
     * for <i>i</i>,<i>j</i> in <code>[0, numChildren-1]</code>,
     * <i>i</i> <code>!=</code> <i>j</i>;</li>
     * </ul>
     *
     * @since Java 3D 1.3
     */
    public void addChild(Node child, int[] childIndexOrder) {
	
	verifyAddStates(child);
	verifyChildIndexOrderArray(childIndexOrder, 1);

	((OrderedGroupRetained)retained).addChild(child, childIndexOrder);

    }


    // Overridden methods from Group

    /**
     * Appends the specified child node to this group node's list of children.
     *
     * <p>
     * If the current child index order array is non-null, the array
     * is increased in size by one element, and a new element
     * containing the index of the new child is added to the end of
     * the array.  Thus, this new child will be rendered last.
     *
     * @param child the child to add to this node's list of children
     * @exception CapabilityNotSetException if the appropriate capability is
     * not set and this group node is part of live or compiled scene graph
     * @exception RestrictedAccessException if this group node is part
     * of live
     * or compiled scene graph and the child node being added is not
     * a BranchGroup node
     * @exception MultipleParentException if <code>child</code> has already
     * been added as a child of another group node.
     *
     * @since Java 3D 1.3
     */
    public void addChild(Node child) {
	// Just call super -- the extra work is done by the retained class
	super.addChild(child);