* The Soundscape application region, different from a Sound node's scheduling * region, is used to select which Soundscape (and thus which aural attribute * object) is to be applied to the sounds being rendered. This selection is * based on the position of the ViewPlatform (i.e., the listener), not the * position of the sound. *
* It will be common that multiple Soundscape regions are contained within a * scene graph. For example, two Soundscape regions within a single space the * listener can move about: a region with a large open area on the right, and * a smaller more constricted, less reverberant area on the left. The rever- * beration attributes for these two regions could be set to approximate their * physical differences so that active sounds are rendered differently depending * on which region the listener is in. */ public class Soundscape extends Leaf { // Constants // // These flags, when enabled using the setCapability method, allow an // application to invoke methods that respectively read and write the // application region and the aural attributes. These capability flags // are enforced only when the node is part of a live or compiled scene // graph. /** * For Soundscape component objects, specifies that this object * allows read access to its application bounds */ public static final int ALLOW_APPLICATION_BOUNDS_READ = CapabilityBits.SOUNDSCAPE_ALLOW_APPLICATION_BOUNDS_READ; /** * For Soundscape component objects, specifies that this object * allows write access to its application bounds */ public static final int ALLOW_APPLICATION_BOUNDS_WRITE = CapabilityBits.SOUNDSCAPE_ALLOW_APPLICATION_BOUNDS_WRITE; /** * For Soundscape component objects, specifies that this object * allows the reading of it's aural attributes information */ public static final int ALLOW_ATTRIBUTES_READ = CapabilityBits.SOUNDSCAPE_ALLOW_ATTRIBUTES_READ; /** * For Soundscape component objects, specifies that this object * allows the writing of it's aural attribute information */ public static final int ALLOW_ATTRIBUTES_WRITE = CapabilityBits.SOUNDSCAPE_ALLOW_ATTRIBUTES_WRITE; // Array for setting default read capabilities private static final int[] readCapabilities = { ALLOW_APPLICATION_BOUNDS_READ, ALLOW_ATTRIBUTES_READ }; /** * Constructs and initializes a new Sound node using following * defaults: *
cloneTree to duplicate the current node.
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree 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) {
Soundscape s = new Soundscape();
s.duplicateNode(this, forceDuplicate);
return s;
}
/**
* Copies all node information from originalNode into
* the current node. This method is called from the
* cloneNode method which is, in turn, called by the
* cloneTree method.
*
* For any NodeComponent objects
* contained by the object being duplicated, each NodeComponent
* object's duplicateOnCloneTree value is used to determine
* whether the NodeComponent should be duplicated in the new node
* or if just a reference to the current node should be placed in the
* new node. This flag can be overridden by setting the
* forceDuplicate parameter in the cloneTree
* method to true.
*
* NOTE: Applications should not call this method directly.
* It should only be called by the cloneNode method.
*
* @param originalNode the original node to duplicate.
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree variable determines whether
* NodeComponent data is duplicated or copied.
* @exception ClassCastException if originalNode is not an instance of
* Soundscape
*
* @see Node#cloneTree
* @see Node#cloneNode
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
public void duplicateNode(Node originalNode, boolean forceDuplicate) {
checkDuplicateNode(originalNode, forceDuplicate);
}
/**
* Copies all Soundscape information from
* originalNode into
* the current node. This method is called from the
* cloneNode method which is, in turn, called by the
* cloneTree method.
*
* @param originalNode the original node to duplicate.
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree variable determines whether
* NodeComponent data is duplicated or copied.
*
* @exception RestrictedAccessException if this object is part of a live
* or compiled scenegraph.
*
* @see Node#duplicateNode
* @see Node#cloneTree
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
super.duplicateAttributes(originalNode, forceDuplicate);
SoundscapeRetained attr = (SoundscapeRetained) originalNode.retained;
SoundscapeRetained rt = (SoundscapeRetained) retained;
rt.setApplicationBounds(attr.getApplicationBounds());
rt.setAuralAttributes((AuralAttributes) getNodeComponent(
attr.getAuralAttributes(),
forceDuplicate,
originalNode.nodeHashtable));
// the following reference will set correctly in updateNodeReferences
rt.setApplicationBoundingLeaf(attr.getApplicationBoundingLeaf());
}
/**
* Callback used to allow a node to check if any scene graph objects
* referenced
* by that node have been duplicated via a call to cloneTree.
* This method is called by cloneTree after all nodes in
* the sub-graph have been duplicated. The cloned Leaf node's method
* will be called and the Leaf node can then look up any object references
* by using the getNewObjectReference method found in the
* NodeReferenceTable object. If a match is found, a
* reference to the corresponding object in the newly cloned sub-graph
* is returned. If no corresponding reference is found, either a
* DanglingReferenceException is thrown or a reference to the original
* object is returned depending on the value of the
* allowDanglingReferences parameter passed in the
* cloneTree call.
*
* NOTE: Applications should not call this method directly.
* It should only be called by the cloneTree method.
*
* @param referenceTable a NodeReferenceTableObject that contains the
* getNewObjectReference method needed to search for
* new object instances.
* @see NodeReferenceTable
* @see Node#cloneTree
* @see DanglingReferenceException
*/
@Override
public void updateNodeReferences(NodeReferenceTable referenceTable) {
SoundscapeRetained rt = (SoundscapeRetained) retained;
BoundingLeaf bl = rt.getApplicationBoundingLeaf();
if (bl != null) {
Object o = referenceTable.getNewObjectReference(bl);
rt.setApplicationBoundingLeaf((BoundingLeaf) o);
}
}
}