Displayable

Files:	Displayable.h, Displayable.C
Derived from:	\bf ColorUser, \bf Pickable
Global instance (if any):	none
Used in optional component:	Part of main VMD code

Description

The Displayable base class is the parent class for all items which need to be drawn to a DisplayDevice. For example, the set of axes which appear in the corner of the VMD display screen are maintained as a Displayable, and each Molecule is one as well. The Scene (section 24.7) object maintains a list of all the Displayable's that are to be drawn to the screen. Each Displayable consists of the following components:

• A transformation matrix which describes how the graphical object represented by the Displayable is transformed (via translations, rotations, and scaling).
• A display list which contains a set of drawing tokens, in a device-independent format. The display list is used by a DisplayDevice to actually draw the object.
• A parent Displayable, which acts as an `owner'; transformations applied to the parent are also applied to its children. If an object does not have a parent, it is a top-level Displayable.
• A set of child Displayable objects.

The Displayable class is the fundamental building block for all items which want to draw something to the screen. Consequently, it is a rather complicated beast.

Constructors

• Displayable::Displayable(TransMethod, char *, int, Scene *, int)
  TransMethod is an enumeration value indicating how the objects transformation matrix should affect the matrix of the DisplayDevice (either it should multiply the matrix (MULT), replace it (LOAD), or it should be ignored altogether (NONE)). The following arguments are the name of the object, the dimension (2 or 3), the Scene with which this object should register, and the initial size of the display list storage (in kilobytes).
• Displayable::Displayable(TransMethod, char *, int, Displayable *, int)
  This is the same as the first constructor, but instead of specifying a Scene to register with, a parent Displayable is given. The new Displayable will become a child of the given parent, instead of registering with a Scene.

Enumerations, lists or character name arrays

TransMethod is a public enumeration which is used to indicate the method of use of the objects transformation matrix. It is one of the following:

• MULT: multiply the DisplayDevice's transformation matrix by this object's matrix when the object is drawn.
• LOAD: replace the DisplayDevice's transformation matrix by this object's matrix when the object is drawn.
• NONE: do not use the object's transformation matrix when rendering.

Internal data structures

• Displayable *parent - each Displayable has a parent, which may be null. The parent is in charge of collecting children and displaying them as a single entity with separate display lists. Operations which are applied to the parent are also applied ot the children, such as rotations, commands to turn the item on or off, etc. Note that the reverse is NOT true: operations applied to children are not applied to their parent. Thus, if you rotate a parent, all the children will rotate in the same way, but it is possible to rotate each child separately.

• ResizeArray<Displayable *> children - the list of children for this object. This is quite often empty. But other Displayable's have many children, for example MoleculeList has as its children all the Molecule objects.

• void *cmdListBeg - the start of the display list for this object

• void *cmdListPos - the location in the display list where the next drawing command should be placed

• Scene *origScene - each Displayable must register itself with a Scene object, and this item stores a pointer to that Scene

• ResizeArray<Scene *> sceneList - if the Displayable is registered with more than one Scene, they are stored here

• Matrix4 tm - the current transformation matrix. This is a public variable so it may be accessed quickly. The transformation matrix is actually just four different matrices multiplied together; these matrices are centm, rotm, globm, and scalem. The order of multiplication is as follows:
  tm = globm * rotm * scalem * centm
  When a vector is multiplied by tm, the operations these matrices represent are:
  • centm - a centering translation. When tm multiplies a vector, this centering translation is applied first.
  • scalem - scales the vector. This is done after the centering translation, so the 'units' for the centering are in the same units as used for the `world' coordinates.
  • rotm - rotates the vector. This follows the scaling operation (although the two may be done in either order).
  • globm - a 'global' translation, which is the last operation done to the vector. Since this is done after the scaling, the units are in post-scaled world coordinates.
  Displayable contains many routines which add to or set the values of these matrices.

• char *name - the name of the object

• TransMethod transMethod - the method for use of the transmforamtion matrix. At the beginning of each display list is placed commands to either multiply the current DisplayDevice's trans matrix, or to replace it, or to not modify it at all. This variable indicates how this should be done. In almost all cases it should be MULT

• doCent, doRot, doGlob, doScale - flags indicating whether this object should obey commands to modify the respective transformation components. Routines exist to toggle them on or off

• int *displayObj, *isFixed, *Dim - flags indicating whether to draw the object, whether to keep it fixed (so that it does not respond to any transformation commands), and of what dimension it is (2 or 3). These values are actually stored at the beginning of the display list, and these pointers reference those locations

Virtual member functions

• virtual void prepare(DisplayDevice *) - this should be supplied by each derived class that needs to do some preparation before drawing. It is called by the Scene right before the scene is to be rendered. By default, it does nothing.

Method of use

A Displayable must either be registered with a parent (i.e. be a child of some parent), or it must be registered with a Scene (in which case it cannot be the child of any other Displayable). To create a new class derived from Displayable, you need to provide two constructors, one taking a Scene pointer, one a Displayable pointer.

Once created, then in the derived-class-provided prepare routine, the display list of for the Displayable must be set up. If this display list will never change during the program, it can be done just once in the constructor and no prepare is necessary. The display list is created by using DispCmd objects.

The display list for each Displayble must be given to a Scene, regardless of whether it is child or parent or both. It is these display lists which are given to the DisplayDevice to be rendered. The Scene keeps a list of registered Displayable's as well so that it can prepare them for drawing. When a parent is prepared for drawing, it also prepares all its children, so only top-level parents need to be registered with the Scene.

Since this class is derived from Pickable and ColorUser, there are several virtual functions which may need to be supplied in order for the derived Displayable to be picked by the pointers, or to have access to the color database. See the descriptions of these objects for more info.

One note about the display lists: the reason they are done in the current scheme is that the CAVE requires the use of shared memory to hold the information for the rendering processes to draw, while a separate update process keeps track of updating the information in shared memory. Since the shared memory cannot have pointers to non-shared memory locations, the display lists are designed to ONLY hold integer and floating-point data. When drawing in the CAVE, a special CaveScene supplies shared memory blocks for the Displayable's to use for their display lists.

Suggestions for future changes/additions

Right now every item is redrawn each time through the VMD event loop. However, there are times when nothing changes, and no redraw is necessary. The prepare routine might be modified to have it return TRUE if a redraw is needed, so that if none of the current Displayable's need a redraw, that extra work is avoided.

Also, this class is kind of a mess, but most of it is necessary ...