Package sim.portrayal3d

Class SimplePortrayal3D

java.lang.Object
sim.portrayal3d.SimplePortrayal3D
All Implemented Interfaces:
Portrayal, Portrayal3D
Direct Known Subclasses:
AxesPortrayal3D, CircledPortrayal3D, CubePortrayal3D, ImagePortrayal3D, LabelledPortrayal3D, LightPortrayal3D, PrimitivePortrayal3D, SharedPortrayal3D, SwitchedPortrayal3D, TransformedPortrayal3D, WireFrameBoxPortrayal3D
public class SimplePortrayal3D extends Object implements Portrayal3D
The superclass of all 3D Simple Portrayals which by default adds nothing to the 3D scene. Since nothing is added to the scene, nothing is shown and you cannot select anything. Subclasses add items to the scene, so they can then be selected if they so choose. By default SimplePortrayal3Ds respond to requests for inspectors by providing a basic LabelledList which shows all the portrayed object's object properties (see sim.util.SimpleProperties). They also respond to inspector update requests by updating this same LabelledList. No polygonAttributes are provided by default, and setSelected always true by default.

SimplePortrayal3Ds have a getFieldPortrayal(), which is the FieldPortrayal3D which houses them. This value can be null if the SimplePortrayal3D was added directly into the Display3D's collection of portrayals rather than being used inside a field portrayal. The contract SimplePortrayal3Ds may assume is that the getFieldPortrayal(), if it exists, will have been set prior to getModel(...) being called.

Various utility functions are provided. setPickableFlags makes a Java3D object pickable (necessary for inspectability and selection). clearPickableFlags does the opposite. appearanceForColor creates a Java3D appearance that's a flat version of the color which requires no lighting -- a very basic default appearance function. If the color has a degree of transparency, the appearance will as well.

A default appearance is provided for subclasses which wish to draw themselves using a default: flat white opaque.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final javax.media.j3d.Appearance
    DEFAULT_APPEARANCE
    Flat white opaque.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SimplePortrayal3D()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static javax.media.j3d.Appearance
    appearanceForColor(Color unlitColor)
    Creates an Appearance equivalent to a flat opaque surface of the provided color, needing no lighting.
    static javax.media.j3d.Appearance
    appearanceForColors(Color ambientColor, Color emissiveColor, Color diffuseColor, Color specularColor, double shininess, double opacity)
    Creates an Appearance with the provided lit colors.
    static javax.media.j3d.Appearance
    appearanceForImage(Image image, boolean opaque)
    Creates an Appearance using the provided image.
    static void
    clearPickableFlags(javax.media.j3d.Node n)
    Utility method which makes the given Node unpickable.
    Display3D
    getCurrentDisplay()
    If the current display has been set, returns it.
    FieldPortrayal3D
    getCurrentFieldPortrayal()
     
    GUIState
    getCurrentGUIState()
    Returns the current GUIState, or null if no GUIState has been set yet.
    Inspector
    getInspector(LocationWrapper wrapper, GUIState state)
    Provide an inspector for an object.
    javax.media.j3d.TransformGroup
    getModel(Object object, javax.media.j3d.TransformGroup prev)
    Provides a TransformGroup which defines the node(s) to place in the scenegraph.
    String
    getName(LocationWrapper wrapper)
    Returns a static, one-line name for the given object that is useful for a human to distinguish it from other objects.
    String
    getStatus(LocationWrapper wrapper)
    Returns a simple, informative one-line description of the current status of the object, which may change at any time to reflect how the object is changing.
    boolean
    isSelected(Object obj)
     
    javax.media.j3d.PolygonAttributes
    polygonAttributes()
    Provides a PolygonAttributes which can be modified to change the underlying model's attributes (culling, vertex versus point versus fill).
    static void
    setAppearanceFlags(javax.media.j3d.Appearance a)
    Sets a variety of flags on an Appearance so that its features can be modified when the scene is live.
    void
    setCurrentDisplay(Display3D display)
    Sets the current Display3D.
    void
    setCurrentFieldPortrayal(FieldPortrayal3D p)
     
    static void
    setPickableFlags(javax.media.j3d.Geometry geom)
    Utility method which prepares the given Geometry to be pickable (for selection and inspection).
    static void
    setPickableFlags(javax.media.j3d.Shape3D s3d)
    Utility method which prepares the given Shape3D to be pickable (for selection and inspection).
    boolean
    setSelected(LocationWrapper wrapper, boolean selected)
    If the object is selected, adds it to a hash table of selected objects for which this SimplePortrayal3D's isSelected() method will return TRUE.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DEFAULT_APPEARANCE

      public static final javax.media.j3d.Appearance DEFAULT_APPEARANCE
      Flat white opaque.

  • Constructor Details

    • SimplePortrayal3D

      public SimplePortrayal3D()

  • Method Details

    • appearanceForColor

      public static javax.media.j3d.Appearance appearanceForColor(Color unlitColor)
      Creates an Appearance equivalent to a flat opaque surface of the provided color, needing no lighting. Opacity is determined by the opacity of the unlit color.

    • appearanceForColors

      public static javax.media.j3d.Appearance appearanceForColors(Color ambientColor, Color emissiveColor, Color diffuseColor, Color specularColor, double shininess, double opacity)
      Creates an Appearance with the provided lit colors. Objects will not appear if the scene is unlit. shininess and opacity both from 0.0 to 1.0. If any color is null, it's assumed to be black. Note that even jet black ambient color will show up as a charcoal gray under the bright white ambient light in MASON. That's Java3D for you, sorry.

    • appearanceForImage

      public static javax.media.j3d.Appearance appearanceForImage(Image image, boolean opaque)
      Creates an Appearance using the provided image. If the image should be entirely opaque, you should definitely set opaque to true. If you want to use the image's built-in transparency information, you should set opaque to false. Beware that there are bugs in Java3D's handling of transparent textures: multiple such objects often will not draw in the correct order; thus objects in the back may appear to be in the front.

    • polygonAttributes

      public javax.media.j3d.PolygonAttributes polygonAttributes()
      Description copied from interface: Portrayal3D
      Provides a PolygonAttributes which can be modified to change the underlying model's attributes (culling, vertex versus point versus fill). This is an optional function: you are free to return null
      Specified by:
      polygonAttributes in interface Portrayal3D

    • getModel

      public javax.media.j3d.TransformGroup getModel(Object object, javax.media.j3d.TransformGroup prev)
      Description copied from interface: Portrayal3D
      Provides a TransformGroup which defines the node(s) to place in the scenegraph. This is the Portrayal3D equivalent of Portrayal2D's draw(object, graphics, drawinfo) method.

      You should hang your model off of the TransformGroup provided. You should not transform that TransformGroup in any way -- it is used elsewhere. Instead if you wish to transform your model (rotate it etc.) you should add your own additional TransformGroup as necessary.

      The provided TransformGroup can be null; in this case you need to create and return the outer TransformGroup for the object. If the provided TransformGroup is non-null, you should modify it and return the same.

      SimplePortrayals should assume the following contract: at the point that getModel(...) is called, the field portrayal and display will have already been set if it exists, else it will be null.

      Specified by:
      getModel in interface Portrayal3D

    • getInspector

      public Inspector getInspector(LocationWrapper wrapper, GUIState state)
      Description copied from interface: Portrayal
      Provide an inspector for an object.
      Specified by:
      getInspector in interface Portrayal

    • getStatus

      public String getStatus(LocationWrapper wrapper)
      Description copied from interface: Portrayal
      Returns a simple, informative one-line description of the current status of the object, which may change at any time to reflect how the object is changing. A simple default would be just to return getName(wrapper).
      Specified by:
      getStatus in interface Portrayal

    • getName

      public String getName(LocationWrapper wrapper)
      Description copied from interface: Portrayal
      Returns a static, one-line name for the given object that is useful for a human to distinguish it from other objects. A simple default would be just to return "" + object.
      Specified by:
      getName in interface Portrayal

    • setCurrentFieldPortrayal

      public void setCurrentFieldPortrayal(FieldPortrayal3D p)

    • getCurrentFieldPortrayal

      public FieldPortrayal3D getCurrentFieldPortrayal()

    • setCurrentDisplay

      public void setCurrentDisplay(Display3D display)
      Description copied from interface: Portrayal3D
      Sets the current Display3D. Called by the Display3D on attach(...).
      Specified by:
      setCurrentDisplay in interface Portrayal3D

    • getCurrentDisplay

      public Display3D getCurrentDisplay()
      If the current display has been set, returns it. Else if the field portrayal is null, returns null. Else queries the field portrayal for its current display and returns that.
      Specified by:
      getCurrentDisplay in interface Portrayal3D

    • getCurrentGUIState

      public GUIState getCurrentGUIState()
      Description copied from interface: Portrayal3D
      Returns the current GUIState, or null if no GUIState has been set yet. The GUIState will be set *at least* immediately prior to getModel(...). You should implement this method as: { Display3D d = getCurrentDisplay(); return (d == null ? null : d.getSimulation()); }
      Specified by:
      getCurrentGUIState in interface Portrayal3D

    • isSelected

      public boolean isSelected(Object obj)

    • setSelected

      public boolean setSelected(LocationWrapper wrapper, boolean selected)
      If the object is selected, adds it to a hash table of selected objects for which this SimplePortrayal3D's isSelected() method will return TRUE. If the object is deselected, removes it from the hash table. Always returns TRUE. The hash table doesn't exist until this method is first called.

      There are two implications to this approach. First, it means that after you've selected an object, there's a hash table attached to its portrayal. If you're using the same portrayal for lots of stuff, that's no big deal. But if you've got per-object portrayals and a lot of objects (or if the objects are themselves SimplePortrayal3D subclasses) then that's a fair number of hash tables. This is a minor memory issue but if you don't care about testing for whether you've been selected or not, you could just override this method to always return TRUE (and don't call super.selected(...) ) and the hash table will never be created. Note that isSelected will always return FALSE for your portrayal in this situation.

      Second, though you can test for selection with the isSelected() method, if you want to, say, change the look of your portrayal based on whether or not it's selected, you will need to test isSelected() each time getModel() is called and modify the model accordingly. This could be a bit expensive. We're working on an approach for you to be able to test if the object was RECENTLY selected or deselected so you could only test then, but it's nontrivial to do without using up a lot of memory.

      Specified by:
      setSelected in interface Portrayal

    • setAppearanceFlags

      public static void setAppearanceFlags(javax.media.j3d.Appearance a)
      Sets a variety of flags on an Appearance so that its features can be modified when the scene is live. This method cannot be called on an Appearance presently used in a live scene.

    • setPickableFlags

      public static void setPickableFlags(javax.media.j3d.Shape3D s3d)
      Utility method which prepares the given Shape3D to be pickable (for selection and inspection).

    • setPickableFlags

      public static void setPickableFlags(javax.media.j3d.Geometry geom)
      Utility method which prepares the given Geometry to be pickable (for selection and inspection).

    • clearPickableFlags

      public static void clearPickableFlags(javax.media.j3d.Node n)
      Utility method which makes the given Node unpickable.