001: /*
002: * $RCSfile: Switch.java,v $
003: *
004: * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.6 $
028: * $Date: 2008/02/28 20:17:31 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.util.BitSet;
035:
036: /**
037: * The Switch node controls which of its children will be rendered.
038: * It defines a child selection value (a switch value) that can either
039: * select a single child, or it can select 0 or more children using a
040: * mask to indicate which children are selected for rendering.
041: * The Switch node contains an ordered list of children, but the
042: * index order of the children in the list is only used for selecting
043: * the appropriate child or children and does not specify rendering
044: * order.
045: */
046:
047: public class Switch extends Group {
048:
049: /**
050: * Specifies that this node allows reading its child selection
051: * and mask values and its current child.
052: */
053: public static final int ALLOW_SWITCH_READ = CapabilityBits.SWITCH_ALLOW_SWITCH_READ;
054:
055: /**
056: * Specifies that this node allows writing its child selection
057: * and mask values.
058: */
059: public static final int ALLOW_SWITCH_WRITE = CapabilityBits.SWITCH_ALLOW_SWITCH_WRITE;
060:
061: /**
062: * Specifies that no children are rendered.
063: * This value may be used in place of a non-negative child
064: * selection index.
065: */
066: public static final int CHILD_NONE = -1;
067:
068: /**
069: * Specifies that all children are rendered. This setting causes
070: * the switch node to function as an ordinary group node.
071: * This value may be used in place of a non-negative child
072: * selection index.
073: */
074: public static final int CHILD_ALL = -2;
075:
076: /**
077: * Specifies that the childMask BitSet is
078: * used to select which children are rendered.
079: * This value may be used in place of a non-negative child
080: * selection index.
081: */
082: public static final int CHILD_MASK = -3;
083:
084: // Array for setting default read capabilities
085: private static final int[] readCapabilities = { ALLOW_SWITCH_READ };
086:
087: /**
088: * Constructs a Switch node with default parameters.
089: * The default values are as follows:
090: * <ul>
091: * child selection index : CHILD_NONE<br>
092: * child selection mask : false (for all children)<br>
093: * </ul>
094: */
095: public Switch() {
096: // set default read capabilities
097: setDefaultReadCapabilities(readCapabilities);
098: }
099:
100: /**
101: * Constructs and initializes a Switch node using the specified
102: * child selection index.
103: * @param whichChild the initial child selection index
104: */
105: public Switch(int whichChild) {
106: // set default read capabilities
107: setDefaultReadCapabilities(readCapabilities);
108:
109: ((SwitchRetained) this .retained)
110: .setWhichChild(whichChild, true);
111: }
112:
113: /**
114: * Constructs and initializes a Switch node using the specified
115: * child selection index and mask.
116: * @param whichChild the initial child selection index
117: * @param childMask the initial child selection mask
118: */
119: public Switch(int whichChild, BitSet childMask) {
120: // set default read capabilities
121: setDefaultReadCapabilities(readCapabilities);
122:
123: ((SwitchRetained) this .retained)
124: .setWhichChild(whichChild, true);
125: ((SwitchRetained) this .retained).setChildMask(childMask);
126: }
127:
128: /**
129: * Creates the retained mode SwitchRetained object that this
130: * Switch object will point to.
131: */
132: void createRetained() {
133: this .retained = new SwitchRetained();
134: this .retained.setSource(this );
135: }
136:
137: /**
138: * Sets the child selection index that specifies which child is rendered.
139: * If the value is out of range, then no children are drawn.
140: * @param child a non-negative integer index value, indicating a
141: * specific child, or one of the following constants: CHILD_NONE,
142: * CHILD_ALL, or CHILD_MASK.
143: * @exception CapabilityNotSetException if appropriate capability is
144: * not set and this object is part of live or compiled scene graph
145: *
146: * @see #CHILD_NONE
147: * @see #CHILD_ALL
148: * @see #CHILD_MASK
149: */
150: public void setWhichChild(int child) {
151: if (isLiveOrCompiled())
152: if (!this .getCapability(ALLOW_SWITCH_WRITE))
153: throw new CapabilityNotSetException(J3dI18N
154: .getString("Switch0"));
155:
156: ((SwitchRetained) this .retained).setWhichChild(child, false);
157: }
158:
159: /**
160: * Retrieves the current child selection index that specifies which
161: * child is rendered.
162: * @return a non-negative integer index value, indicating a
163: * specific child, or one of the following constants: CHILD_NONE,
164: * CHILD_ALL, or CHILD_MASK
165: * @exception CapabilityNotSetException if appropriate capability is
166: * not set and this object is part of live or compiled scene graph
167: *
168: * @see #CHILD_NONE
169: * @see #CHILD_ALL
170: * @see #CHILD_MASK
171: */
172: public int getWhichChild() {
173: if (isLiveOrCompiled())
174: if (!this .getCapability(ALLOW_SWITCH_READ))
175: throw new CapabilityNotSetException(J3dI18N
176: .getString("Switch1"));
177:
178: return ((SwitchRetained) this .retained).getWhichChild();
179: }
180:
181: /**
182: * Sets the child selection mask. This mask is used when
183: * the child selection index is set to CHILD_MASK.
184: * @param childMask a BitSet that specifies which children are rendered
185: * @exception CapabilityNotSetException if appropriate capability is
186: * not set and this object is part of live or compiled scene graph
187: */
188: public void setChildMask(BitSet childMask) {
189: if (isLiveOrCompiled())
190: if (!this .getCapability(ALLOW_SWITCH_WRITE))
191: throw new CapabilityNotSetException(J3dI18N
192: .getString("Switch2"));
193:
194: ((SwitchRetained) this .retained).setChildMask(childMask);
195: }
196:
197: /**
198: * Retrieves the current child selection mask. This mask is used when
199: * the child selection index is set to CHILD_MASK.
200: * @return the child selection mask
201: * @exception CapabilityNotSetException if appropriate capability is
202: * not set and this object is part of live or compiled scene graph
203: */
204: public BitSet getChildMask() {
205: if (isLiveOrCompiled())
206: if (!this .getCapability(ALLOW_SWITCH_READ))
207: throw new CapabilityNotSetException(J3dI18N
208: .getString("Switch3"));
209:
210: return ((SwitchRetained) this .retained).getChildMask();
211: }
212:
213: /**
214: * Retrieves the currently selected child. If the child selection index
215: * is out of range or is set to CHILD_NONE, CHILD_ALL, or CHILD_MASK,
216: * then this method returns null.
217: * @return a reference to the current child chosen for rendering
218: * @exception CapabilityNotSetException if appropriate capability is
219: * not set and this object is part of live or compiled scene graph
220: */
221: public Node currentChild() {
222: if (isLiveOrCompiled())
223: if (!this .getCapability(ALLOW_CHILDREN_READ))
224: throw new CapabilityNotSetException(J3dI18N
225: .getString("Switch4"));
226:
227: return ((SwitchRetained) this .retained).currentChild();
228: }
229:
230: /**
231: * Used to create a new instance of the node. This routine is called
232: * by <code>cloneTree</code> to duplicate the current node.
233: * @param forceDuplicate when set to <code>true</code>, causes the
234: * <code>duplicateOnCloneTree</code> flag to be ignored. When
235: * <code>false</code>, the value of each node's
236: * <code>duplicateOnCloneTree</code> variable determines whether
237: * NodeComponent data is duplicated or copied.
238: *
239: * @see Node#cloneTree
240: * @see Node#cloneNode
241: * @see Node#duplicateNode
242: * @see NodeComponent#setDuplicateOnCloneTree
243: */
244: public Node cloneNode(boolean forceDuplicate) {
245: Switch s = new Switch();
246: s.duplicateNode(this , forceDuplicate);
247: return s;
248: }
249:
250: /**
251: * Copies all Switch information from
252: * <code>originalNode</code> into
253: * the current node. This method is called from the
254: * <code>cloneNode</code> method which is, in turn, called by the
255: * <code>cloneTree</code> method.<P>
256: *
257: * @param originalNode the original node to duplicate.
258: * @param forceDuplicate when set to <code>true</code>, causes the
259: * <code>duplicateOnCloneTree</code> flag to be ignored. When
260: * <code>false</code>, the value of each node's
261: * <code>duplicateOnCloneTree</code> variable determines whether
262: * NodeComponent data is duplicated or copied.
263: *
264: * @exception RestrictedAccessException if this object is part of a live
265: * or compiled scenegraph.
266: *
267: * @see Group#cloneNode
268: * @see Node#duplicateNode
269: * @see Node#cloneTree
270: * @see NodeComponent#setDuplicateOnCloneTree
271: */
272: void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
273: super .duplicateAttributes(originalNode, forceDuplicate);
274:
275: SwitchRetained attr = (SwitchRetained) originalNode.retained;
276: SwitchRetained rt = (SwitchRetained) retained;
277:
278: rt.setChildMask(attr.getChildMask());
279: rt.setWhichChild(attr.getWhichChild(), true);
280: }
281: }
|