DispCmd

Files:	DispCmds.h, DispCmd.C
Derived from:	none
Global instance (if any):	none
Used in optional component:	Part of main VMD code

Description

DispCmd is a base class for a large number of objects which are used to create the display lists in Displayable objects. Each subclass represents a particular drawing primitive, such as plotting a line, changing the current color, or applying a rotation. These objects take the data required for the particular primitive they represent (for example, the endpoints of a line, or the index of a color) and append this data to the end of the display list for a given Displayable. Routines are available to permit a DispCmd to be used more than once, and also to have the DispCmd remember the location where the data was most recently appended so that new data may be copied over existing data in a display list.

Constructors

• DispCmd::DispCmd(int code, int size)
  code is a special index used to distinguish what type of DispCmd this is; it is supplied by the derived class, and should be one of the enumeration values listed at the top of the file DispCmds.h. size is the number of bytes that the data will occupy when placed into the display list; it is also supplied by the derived class. It can be zero.

Enumerations, lists or character name arrays

At the beginning of DispCmds.h is an enumeration with entries for all the different DispCmd-derived classes. These names are used by the render routine in each DisplayDevice to determine what the commands are in a display list. When new drawing primitives are added, a new name should be put in this list, and that name should be specified in the DispCmd base class constructor.

Following this are enumerations describing the different types of spheres that may be drawn, and the different types of lines.

Internal data structures

• int cmdCode - the unique integer ID of the command; this is one of the names in the main enumeration described above.
• int cmdSize - the number of bytes which the data will occupy when copied into a given display list.
• void *Data - a block of cmdSize bytes which stores the data to be copied into a given display list.
• void *dataLoc - a pointer to the last place into which the bytes in Data were copied. If it is NULL, the data has not yet been copied. This is stored so that the reput command can copy new data over previously-stored data, instead of just appending the data to the end of a display list.

Nonvirtual member functions

• void put(Displayable *dobj) - This is the main function in each DispCmd object. It copies the values stored in Data to the end of the specified Displayable object's display list. As well, the integer code indicating which primitive this is is copied into the list, and also the size of the data (in bytes). The order of copying data is as follows:
  1. cmdCode (one integer)
  2. cmdSize (one integer)
  3. Data (cmdSize bytes)

• reput(Displayable *dobj) - Same as put, except that if the same DispCmd has had the put routine called, this command will copy the data into the same location as was used previously. This can be used to copy data over previously-copied data. A particular example is in Displayable, which uses reput to replace the matrix data in the multiply-transformation-matrix command used at the beginning of each Displayable's display list. If put has NOT been called prior to calling reput, then reput does exactly the same thing as put.

Method of use

Each class derived from DispCmd should have two constructors:

• A default constructor, with no arguments - this will just initialize all the internal storage to default values.
• A data constructor, which takes arguments with the data necessary for the command. This will copy the arguments into the internal data storage of the object.

If a derived class does not require any arguments (for example, the PUSH command, which just signals to push the top transformation matrix, but does not require any data itself), only the default constructor is used. Otherwise, each derived class should also provide two new functions;

• void putdata(args, Displayable *dobj) - This should copy the data specifed in args, and then call put(dobj). This is used when an instance of this class is created with a default constructor, and the instance is to be used more than once. Each time the instance it used, putdata is called to append new data to the end of dobj's display list.
• void reputdata(args, Displayable *dobj) - Same as putdata, but it should call reput after copying the given data instead of put.

Within the put and reput functions, DispCmd uses several routines in Displayable to start the action of writing a new command to the end of the display list, to copy over the data itself, and to signal the data is copied.

Suggestions for future changes/additions

At present, most Displayable objects contain instances of these commands as private members, which are used to create their internal display lists. This is not really necessary, it would probably be better if there were one global instance of each different DispCmd, available for use by the Displayable objects. This would decrease the memory used, and the time for construction of the Displayable using the global instances instead of a local copy.