javax.media.j3d

## Class Shape3D

- java.lang.Object
- - javax.media.j3d.SceneGraphObject
  - - javax.media.j3d.Node
    - - javax.media.j3d.Leaf
      - - javax.media.j3d.Shape3D

- Direct Known Subclasses:
    ColorCube, OrientedShape3D, SensorBeamEcho, SensorGnomonEcho, Text2D

      public class Shape3D
      extends Leaf

  The Shape3D leaf node specifies all geometric objects. It contains a list of one or more Geometry component objects and a single Appearance component object. The geometry objects define the shape node's geometric data. The appearance object specifies that object's appearance attributes, including color, material, texture, and so on.

  The list of geometry objects must all be of the same equivalence class, that is, the same basic type of primitive. For subclasses of GeometryArray, all point objects are equivalent, all line objects are equivalent, and all polygon objects are equivalent. For other subclasses of Geometry, only objects of the same subclass are equivalent. The equivalence classes are as follows:

  - GeometryArray (point): [Indexed]PointArray
  - GeometryArray (line): [Indexed]{LineArray, LineStripArray}
  - GeometryArray (polygon): [Indexed]{TriangleArray, TriangleStripArray, TriangleFanArray, QuadArray}
  - CompressedGeometry
  - Raster
  - Text3D

  When Shape3D is used with multiple geometry components, Java 3D may choose to use individual geometry bounds instead of the shape's bounds for region of influence operations, such as lighting. For example, the individual characters of a Text3D shape object may be rendered with a different light set.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ALLOW_APPEARANCE_OVERRIDE_READ` Specifies that this node allows reading its appearance override enable flag.
    `static int` | `ALLOW_APPEARANCE_OVERRIDE_WRITE` Specifies that this node allows writing its appearance override enable flag.
    `static int` | `ALLOW_APPEARANCE_READ` Specifies that the node allows read access to its appearance information.
    `static int` | `ALLOW_APPEARANCE_WRITE` Specifies that the node allows write access to its appearance information.
    `static int` | `ALLOW_COLLISION_BOUNDS_READ` Specifies that the node allows reading its collision Bounds
    `static int` | `ALLOW_COLLISION_BOUNDS_WRITE` Specifies the node allows writing its collision Bounds
    `static int` | `ALLOW_GEOMETRY_READ` Specifies that the node allows read access to its geometry information.
    `static int` | `ALLOW_GEOMETRY_WRITE` Specifies that the node allows write access to its geometry information.

    - ### Fields inherited from class javax.media.j3d.Node

      `ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_LOCALE_READ, ALLOW_PARENT_READ, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Shape3D()` Constructs a Shape3D node with default parameters.
    `Shape3D(Geometry geometry)` Constructs and initializes a Shape3D node with the specified geometry component and a null appearance component.
    `Shape3D(Geometry geometry, Appearance appearance)` Constructs and initializes a Shape3D node with the specified geometry and appearance components.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addGeometry(Geometry geometry)` Appends the specified geometry component to this Shape3D node's list of geometry components.
    `Node` | `cloneNode(boolean forceDuplicate)` Used to create a new instance of the node.
    `void` | `duplicateNode(Node originalNode, boolean forceDuplicate)` Copies all node information from `originalNode` into the current node.
    `java.util.Enumeration` | `getAllGeometries()` Returns an enumeration of this Shape3D node's list of geometry components.
    `Appearance` | `getAppearance()` Retrieves the appearance component of this shape node.
    `boolean` | `getAppearanceOverrideEnable()` Retrieves the appearanceOverrideEnable flag for this node.
    `Bounds` | `getBounds()` See parent class for the documentation on getBounds().
    `Bounds` | `getCollisionBounds()` Returns the collision bounding object of this node.
    `Geometry` | `getGeometry()` Retrieves the geometry component at index 0 from this Shape3D node's list of geometry components.
    `Geometry` | `getGeometry(int index)` Retrieves the geometry component at the specified index from this Shape3D node's list of geometry components.
    `int` | `indexOfGeometry(Geometry geometry)` Retrieves the index of the specified geometry component in this Shape3D node's list of geometry components.
    `void` | `insertGeometry(Geometry geometry, int index)` Inserts the specified geometry component into this Shape3D node's list of geometry components at the specified index.
    `boolean` | `intersect(SceneGraphPath path, PickRay pickRay, double[] dist)` Checks whether the geometry in this shape node intersects with the specified pickRay.
    `boolean` | `intersect(SceneGraphPath path, PickShape pickShape)` Checks whether the geometry in this shape node intersects with the specified pickShape.
    `boolean` | `intersect(SceneGraphPath path, PickShape pickShape, double[] dist)` Checks whether the geometry in this shape node intersects with the specified pickShape.
    `int` | `numGeometries()` Returns the number of geometry components in this Shape3D node's list of geometry components.
    `void` | `removeAllGeometries()` Removes all geometry components from this Shape3D node.
    `void` | `removeGeometry(Geometry geometry)` Removes the specified geometry component from this Shape3D node's list of geometry components.
    `void` | `removeGeometry(int index)` Removes the geometry component at the specified index from this Shape3D node's list of geometry components.
    `void` | `setAppearance(Appearance appearance)` Sets the appearance component of this Shape3D node.
    `void` | `setAppearanceOverrideEnable(boolean flag)` Sets a flag that indicates whether this node's appearance can be overridden.
    `void` | `setCollisionBounds(Bounds bounds)` Sets the collision bounds of a node.
    `void` | `setGeometry(Geometry geometry)` Replaces the geometry component at index 0 in this Shape3D node's list of geometry components with the specified geometry component.
    `void` | `setGeometry(Geometry geometry, int index)` Replaces the geometry component at the specified index in this Shape3D node's list of geometry components with the specified geometry component.

    - ### Methods inherited from class javax.media.j3d.Node

      `cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, getBoundsAutoCompute, getCollidable, getLocale, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable`

    - ### Methods inherited from class javax.media.j3d.SceneGraphObject

      `clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString, updateNodeReferences`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### ALLOW_GEOMETRY_READ

          public static final int ALLOW_GEOMETRY_READ

      Specifies that the node allows read access to its geometry information.
      See Also:
        Constant Field Values

    - #### ALLOW_GEOMETRY_WRITE

          public static final int ALLOW_GEOMETRY_WRITE

      Specifies that the node allows write access to its geometry information.
      See Also:
        Constant Field Values

    - #### ALLOW_APPEARANCE_READ

          public static final int ALLOW_APPEARANCE_READ

      Specifies that the node allows read access to its appearance information.
      See Also:
        Constant Field Values

    - #### ALLOW_APPEARANCE_WRITE

          public static final int ALLOW_APPEARANCE_WRITE

      Specifies that the node allows write access to its appearance information.
      See Also:
        Constant Field Values

    - #### ALLOW_COLLISION_BOUNDS_READ

          public static final int ALLOW_COLLISION_BOUNDS_READ

      Specifies that the node allows reading its collision Bounds
      See Also:
        Constant Field Values

    - #### ALLOW_COLLISION_BOUNDS_WRITE

          public static final int ALLOW_COLLISION_BOUNDS_WRITE

      Specifies the node allows writing its collision Bounds
      See Also:
        Constant Field Values

    - #### ALLOW_APPEARANCE_OVERRIDE_READ

          public static final int ALLOW_APPEARANCE_OVERRIDE_READ

      Specifies that this node allows reading its appearance override enable flag.
      Since:
        Java 3D 1.2
      See Also:
        Constant Field Values

    - #### ALLOW_APPEARANCE_OVERRIDE_WRITE

          public static final int ALLOW_APPEARANCE_OVERRIDE_WRITE

      Specifies that this node allows writing its appearance override enable flag.
      Since:
        Java 3D 1.2
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Shape3D

          public Shape3D()

      Constructs a Shape3D node with default parameters. The default values are as follows:
      appearance : null
      geometry : { null }
      collision bounds : null
      appearance override enable : false
      The list of geometry components is initialized with a null geometry component as the single element with an index of 0. A null geometry component specifies that no geometry is drawn. A null appearance component specifies that default values are used for all appearance attributes.

    - #### Shape3D

          public Shape3D(Geometry geometry)

      Constructs and initializes a Shape3D node with the specified geometry component and a null appearance component. The list of geometry components is initialized with the specified geometry component as the single element with an index of 0. A null appearance component specifies that default values are used for all appearance attributes.
      Parameters:
        `geometry` - the geometry component with which to initialize this shape node.

    - #### Shape3D

          public Shape3D(Geometry geometry,
                 Appearance appearance)

      Constructs and initializes a Shape3D node with the specified geometry and appearance components. The list of geometry components is initialized with the specified geometry component as the single element with an index of 0.
      Parameters:
        `geometry` - the geometry component with which to initialize this shape node
        `appearance` - the appearance component of the shape node

  - ### Method Detail

    - #### setCollisionBounds

          public void setCollisionBounds(Bounds bounds)

      Sets the collision bounds of a node.
      Parameters:
        `bounds` - the collision bounding object for a node
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### getCollisionBounds

          public Bounds getCollisionBounds()

      Returns the collision bounding object of this node.
      Returns:
        the node's collision bounding object
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### setGeometry

          public void setGeometry(Geometry geometry)

      Replaces the geometry component at index 0 in this Shape3D node's list of geometry components with the specified geometry component. If there are existing geometry components in the list (besides the one being replaced), the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.
      Parameters:
        `geometry` - the geometry component to be stored at index 0.
      Throws:
        `java.lang.IllegalArgumentException` - if the new geometry component is not of of the same equivalence class as the existing geometry components.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### getGeometry

          public Geometry getGeometry()

      Retrieves the geometry component at index 0 from this Shape3D node's list of geometry components.
      Returns:
        the geometry component at index 0.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### setGeometry

          public void setGeometry(Geometry geometry,
                         int index)

      Replaces the geometry component at the specified index in this Shape3D node's list of geometry components with the specified geometry component. If there are existing geometry components in the list (besides the one being replaced), the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.
      Parameters:
        `geometry` - the geometry component to be stored at the specified index.
        `index` - the index of the geometry component to be replaced.
      Throws:
        `java.lang.IllegalArgumentException` - if the new geometry component is not of of the same equivalence class as the existing geometry components.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### getGeometry

          public Geometry getGeometry(int index)

      Retrieves the geometry component at the specified index from this Shape3D node's list of geometry components.
      Parameters:
        `index` - the index of the geometry component to be returned.
      Returns:
        the geometry component at the specified index.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### insertGeometry

          public void insertGeometry(Geometry geometry,
                            int index)

      Inserts the specified geometry component into this Shape3D node's list of geometry components at the specified index. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.
      Parameters:
        `geometry` - the geometry component to be inserted at the specified index.
        `index` - the index at which the geometry component is inserted.
      Throws:
        `java.lang.IllegalArgumentException` - if the new geometry component is not of of the same equivalence class as the existing geometry components.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### removeGeometry

          public void removeGeometry(int index)

      Removes the geometry component at the specified index from this Shape3D node's list of geometry components.
      Parameters:
        `index` - the index of the geometry component to be removed.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### getAllGeometries

          public java.util.Enumeration getAllGeometries()

      Returns an enumeration of this Shape3D node's list of geometry components.
      Returns:
        an Enumeration object containing all geometry components in this Shape3D node's list of geometry components.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### addGeometry

          public void addGeometry(Geometry geometry)

      Appends the specified geometry component to this Shape3D node's list of geometry components. If there are existing geometry components in the list, the new geometry component must be of the same equivalence class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.
      Parameters:
        `geometry` - the geometry component to be appended.
      Throws:
        `java.lang.IllegalArgumentException` - if the new geometry component is not of of the same equivalence class as the existing geometry components.
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### numGeometries

          public int numGeometries()

      Returns the number of geometry components in this Shape3D node's list of geometry components.
      Returns:
        the number of geometry components in this Shape3D node's list of geometry components.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### indexOfGeometry

          public int indexOfGeometry(Geometry geometry)

      Retrieves the index of the specified geometry component in this Shape3D node's list of geometry components.
      Parameters:
        `geometry` - the geometry component to be looked up.
      Returns:
        the index of the specified geometry component; returns -1 if the object is not in the list.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.3

    - #### removeGeometry

          public void removeGeometry(Geometry geometry)

      Removes the specified geometry component from this Shape3D node's list of geometry components. If the specified object is not in the list, the list is not modified.
      Parameters:
        `geometry` - the geometry component to be removed.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.3

    - #### removeAllGeometries

          public void removeAllGeometries()

      Removes all geometry components from this Shape3D node.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.3

    - #### setAppearance

          public void setAppearance(Appearance appearance)

      Sets the appearance component of this Shape3D node. Setting it to null specifies that default values are used for all appearance attributes.
      Parameters:
        `appearance` - the new appearance component for this shape node
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### getAppearance

          public Appearance getAppearance()

      Retrieves the appearance component of this shape node.
      Returns:
        the appearance component of this shape node
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph

    - #### intersect

          public boolean intersect(SceneGraphPath path,
                          PickShape pickShape)

      Checks whether the geometry in this shape node intersects with the specified pickShape.
      Parameters:
        `path` - the SceneGraphPath to this shape node
        `pickShape` - the PickShape to be intersected
      Returns:
        true if the pick shape intersects this node; false otherwise.
      Throws:
        `java.lang.IllegalArgumentException` - if pickShape is a PickPoint. Java 3D doesn't have spatial information of the surface. Use PickBounds with BoundingSphere and a small radius, instead.
        `CapabilityNotSetException` - if the Geometry.ALLOW_INTERSECT capability bit is not set in all of the Geometry objects referred to by this shape node.

    - #### intersect

          public boolean intersect(SceneGraphPath path,
                          PickRay pickRay,
                          double[] dist)

      Checks whether the geometry in this shape node intersects with the specified pickRay.
      Parameters:
        `path` - the SceneGraphPath to this shape node
        `pickRay` - the PickRay to be intersected
        `dist` - the closest distance of the intersection
      Returns:
        true if the pick shape intersects this node; false otherwise. If true, dist contains the closest distance of intersection.
      Throws:
        `CapabilityNotSetException` - if the Geometry.ALLOW_INTERSECT capability bit is not set in all of the Geometry objects referred to by this shape node.

    - #### intersect

          public boolean intersect(SceneGraphPath path,
                          PickShape pickShape,
                          double[] dist)

      Checks whether the geometry in this shape node intersects with the specified pickShape.
      Parameters:
        `path` - the SceneGraphPath to this shape node
        `pickShape` - the PickShape to be intersected
        `dist` - the closest distance of the intersection
      Returns:
        true if the pick shape intersects this node; false otherwise. If true, dist contains the closest distance of intersection.
      Throws:
        `java.lang.IllegalArgumentException` - if pickShape is a PickPoint. Java 3D doesn't have spatial information of the surface. Use PickBounds with BoundingSphere and a small radius, instead.
        `CapabilityNotSetException` - if the Geometry.ALLOW_INTERSECT capability bit is not set in all of the Geometry objects referred to by this shape node.
      Since:
        Java 3D 1.3

    - #### setAppearanceOverrideEnable

          public void setAppearanceOverrideEnable(boolean flag)

      Sets a flag that indicates whether this node's appearance can be overridden. If the flag is true, then this node's appearance may be overridden by an AlternateAppearance leaf node, regardless of the value of the ALLOW_APPEARANCE_WRITE capability bit. The default value is false.
      Parameters:
        `flag` - the apperance override enable flag.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2
      See Also:
        `AlternateAppearance`

    - #### getAppearanceOverrideEnable

          public boolean getAppearanceOverrideEnable()

      Retrieves the appearanceOverrideEnable flag for this node.
      Returns:
        true if the appearance can be overridden; false otherwise.
      Throws:
        `CapabilityNotSetException` - if appropriate capability is not set and this object is part of live or compiled scene graph
      Since:
        Java 3D 1.2

    - #### cloneNode

          public Node cloneNode(boolean forceDuplicate)

      Used to create a new instance of the node. This routine is called by `cloneTree` to duplicate the current node. `cloneNode` should be overridden by any user subclassed objects. All subclasses must have their `cloneNode` method consist of the following lines:

      >          public Node cloneNode(boolean forceDuplicate) {
      >              UserSubClass usc = new UserSubClass();
      >              usc.duplicateNode(this, forceDuplicate);
      >              return usc;
      >          }

      Overrides:
        `cloneNode` in class `Node`
      Parameters:
        `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 Also:
        `Node.cloneTree()`, `Node.duplicateNode(javax.media.j3d.Node, boolean)`, `NodeComponent.setDuplicateOnCloneTree(boolean)`

    - #### duplicateNode

          public void duplicateNode(Node originalNode,
                           boolean forceDuplicate)

      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.

      Overrides:
        `duplicateNode` in class `Node`
      Parameters:
        `originalNode` - the original node to duplicate.
        `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.
      Throws:
        `java.lang.ClassCastException` - if originalNode is not an instance of `Shape3D`
      See Also:
        `Node.cloneTree()`, `Node.cloneNode(boolean)`, `NodeComponent.setDuplicateOnCloneTree(boolean)`

    - #### getBounds

          public Bounds getBounds()

      See parent class for the documentation on getBounds().
      Overrides:
        `getBounds` in class `Node`
      Returns:
        the node's bounding object

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.