path: root/src/javax/media/j3d/ViewSpecificGroup.java

/*
 * Copyright 2001-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;

import java.util.Enumeration;

/**
 * The ViewSpecificGroup node is a Group whose descendants are
 * rendered only on a specified set of views.  It
 * contains a list of views on which its descendants are
 * rendered.  Methods are provided to add, remove, and enumerate the
 * list of views.  The list of views is initially empty, meaning that
 * the descendants of this group will not be rendered on any view.  At
 * least one view must be added to the list of views for rendering to
 * occur.
 *
 * <p>
 * All nodes except ViewPlatform may appear as a descendant of
 * ViewSpecificGroup, including another ViewSpecificGroup.  If a
 * ViewSpecificGroup is a descendant of a ViewSpecificGroup, the
 * effect is to intersect the view sets of the ViewSpecificGroup nodes
 * in the hierarchy; each ViewSpecificGroup encountered when
 * traversing the scene graph further restricts the set of views on
 * which its descendants are rendered.  More formally, descendant
 * nodes of ViewSpecificGroups are rendered in (or apply to) only
 * those views that are contained in the set of views of every
 * ViewSpecificGroup in the scene graph path from the Locale to the
 * Node.
 *
 * <p>
 * Behavior
 * nodes may appear under a ViewSpecificGroup, but are not affected by
 * it--the Behavior scheduler is per-universe rather than per-View.
 * BoundingLeaf nodes are similarly unaffected by being under a
 * ViewSpecificGroup.  A BoundingLeaf under a ViewSpecificGroup
 * provides a valid bounds for any node that refers to it,
 * irrespective of the view.
 *
 * <p>
 * The rest of the leaf nodes either: A) are only rendered within the
 * specified view(s), for example, Shape3D, Morph, and Sound; or B)
 * only affect other objects when they are rendered in the specified
 * view(s), for example, AlternateAppearance, Clip, ModelClip, Fog,
 * Light, Soundscape, Background.
 *
 * @since Java 3D 1.3
 */

public class ViewSpecificGroup extends Group {
    /**
     * Specifies that this ViewSpecificGroup node allows reading its
     * view information at runtime.
     */
    public static final int
    ALLOW_VIEW_READ = CapabilityBits.VIEW_SPECIFIC_GROUP_ALLOW_VIEW_READ;

    /**
     * Specifies that this ViewSpecificGroup node allows writing its
     * view information at runtime.
     */
    public static final int
    ALLOW_VIEW_WRITE = CapabilityBits.VIEW_SPECIFIC_GROUP_ALLOW_VIEW_WRITE;

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

    /**
     * Constructs and initializes a new ViewSpecificGroup node object.
     */
    public ViewSpecificGroup() {
        // set default read capabilities
        setDefaultReadCapabilities(readCapabilities);
    }


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


    /**
     * Replaces the view at the specified index in this node's
     * list of views with the specified View object.
     *
     * @param view the View object to be stored at the specified index.
     * @param index the index of the View object to be replaced.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void setView(View view, int index) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup1"));

	((ViewSpecificGroupRetained)this.retained).setView(view, index);
    }


    /**
     * Retrieves the View object at the specified index from this node's
     * list of views.
     *
     * @param index the index of the View object to be returned.
     * @return the View object at the specified index.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public View getView(int index) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup2"));

	return ((ViewSpecificGroupRetained)this.retained).getView(index);
    }


    /**
     * Inserts the specified View object into this node's
     * list of views at the specified index.
     *
     * @param view the View object to be inserted at the specified index.
     * @param index the index at which the View object is inserted.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void insertView(View view, int index) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup1"));

	((ViewSpecificGroupRetained)this.retained).insertView(view, index);
    }


    /**
     * Removes the View object at the specified index from this node's
     * list of views.
     * If this operation causes the list of views to become empty,
     * then the descendants of this ViewSpecificGroup node will not be
     * rendered.
     *
     * @param index the index of the View object to be removed.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void removeView(int index) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup1"));
	((ViewSpecificGroupRetained)this.retained).removeView(index);

    }


/**
 * Returns an enumeration of this ViewSpecificGroup node's list
 * of views.
 *
 * @return an Enumeration object containing all the views.
 * @exception CapabilityNotSetException if appropriate capability is
 * not set and this object is part of live or compiled scene graph
 */
public Enumeration<View> getAllViews() {
	if (isLiveOrCompiled() && !this.getCapability(ALLOW_VIEW_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup2"));

	return ((ViewSpecificGroupRetained) this.retained).getAllViews();
}


    /**
     * Appends the specified View object to this node's list of views.
     *
     * @param view the View object to be appended.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public void addView(View view) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup1"));

	((ViewSpecificGroupRetained)this.retained).addView(view);
    }


    /**
     * Returns the number of View objects in this node's list of views.
     * If this number is 0, then the list of views is empty and
     * the descendants of this ViewSpecificGroup node will not be
     * rendered.
     *
     * @return the number of views in this node's list of views.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public int numViews() {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup2"));

	return ((ViewSpecificGroupRetained)this.retained).numViews();
    }


    /**
     * Retrieves the index of the specified View object in this
     * node's list of views.
     *
     * @param view the View object to be looked up.
     * @return the index of the specified View object;
     * returns -1 if the object is not in the list.
     * @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 indexOfView(View view) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup2"));

	return ((ViewSpecificGroupRetained)this.retained).indexOfView(view);
    }


    /**
     * Removes the specified View object from this
     * node's list of views.  If the specified object is not in the
     * list, the list is not modified.
     * If this operation causes the list of views to become empty,
     * then the descendants of this ViewSpecificGroup node will not be
     * rendered.
     *
     * @param view the View object to be removed.
     * @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 removeView(View view) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup1"));

	((ViewSpecificGroupRetained)this.retained).removeView(view);
    }


    /**
     * Removes all View objects from this node's
     * list of views.
     * Since this method clears the list of views, the descendants of
     * this ViewSpecificGroup node will not be rendered.
     *
     * @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 removeAllViews() {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_VIEW_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("ViewSpecificGroup1"));

	((ViewSpecificGroupRetained)this.retained).removeAllViews();
    }


    /**
     * Used to create a new instance of the node.  This routine is called
     * by <code>cloneTree</code> to duplicate the current node.
     * @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 Node#cloneNode
     * @see Node#duplicateNode
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    @Override
    public Node cloneNode(boolean forceDuplicate) {
	ViewSpecificGroup vsg = new ViewSpecificGroup();
	vsg.duplicateNode(this, forceDuplicate);
	return vsg;
    }


    /**
     * Copies all ViewSpecificGroup information from
     * <code>originalNode</code> into
     * the current node.  This method is called from the
     * <code>cloneNode</code> method which is, in turn, called by the
     * <code>cloneTree</code> method.<P>
     *
     * @param originalNode 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.
     *
     * @exception RestrictedAccessException if this object is part of a live
     *  or compiled scenegraph.
     *
     * @see Group#cloneNode
     * @see Node#duplicateNode
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    @Override
    void duplicateAttributes(Node originalNode, boolean forceDuplicate) {

	// XXXX: implement this?
        super.duplicateAttributes(originalNode, forceDuplicate);

        ViewSpecificGroupRetained attr = (ViewSpecificGroupRetained) originalNode.retained;
	ViewSpecificGroupRetained rt = (ViewSpecificGroupRetained) retained;

	for (Enumeration<View> e = attr.getAllViews(); e.hasMoreElements(); ) {
	    rt.addView(e.nextElement());
	}
    }

}