# NAME

vdraw - edit and display vlists from the MGED command line

# SYNOPSIS

vdraw o(pen)|w(rite)|i(nsert)|d(elete)|p(arams)|r(ead)|v(list)|s(how) args

# DESCRIPTION

Solids are displayed in MGED using vlists. These are are lists of commands and vectors which draw lines and polygons. The vdraw command allows the user to edit vlists from the command line and then display them in the MGED display window as "pseudosolids" -- vestigial entries in the in-memory list of displayed solids which have a name, color, and a display list, but which do not represent geometry.

The vectors in the vlist can represent points or normal vectors defining lines and polygons; the interpretation of each vector depends on the integer command which accompanies it. The following commands are defined in <file>raytrace.h</file>:

          NAME            COMMAND          MEANING

    RT_VLIST_LINE_MOVE       0         begin new line
    RT_VLIST_LINE_DRAW       1         draw line to this point
    RT_VLIST_POLY_START      2         give surface normal for polygon
    RT_VLIST_POLY_MOVE       3         first polygon vertex
    RT_VLIST_POLY_DRAW       4         subsequent polygon vertex
    RT_VLIST_POLY_END        5         last polygon vertex (repeat first)
    RT_VLIST_POLY_VERTNORM   6         per-vertex normal (for interpolation)

Vdraw can take a variety of arguments which specify various operations on the vlists. Note that any textual argument can be replaced by its first letter. For example, vdraw d a has the same effect as vdraw delete all.

In the following descriptions, index is an integer referring to a particular node in a vlist, command is an integer representing one of the drawing commands described above, name is a string no longer than 31 characters, and rrggbb is a six-digit hexadecimal integer representing a color.

# OPERATIONS

    vdraw open

With no argument, this command asks whether or not any vlist is currently open. Returns "1" if yes, "0" if no. The vdraw function keeps at most one vlist open at any time - this is the vlist which is operated on by all of the other commands. All other commands, except the vdraw vlist commands, return an error if there is no open vlist.

    vdraw open name

Open the named vlist for editing, creating a new vlist if it doesn't already exist, and closing the previous vlist. Returns 1 if creating a new vlist, or 0 otherwise.

    vdraw write index command x y z

Write the given command and vector into the index-th node of the current vlist. The existing nodes are numbered from 0 to n-1, where n is the length of the vlist. If the index is in the range 0 to n, there is no return value; otherwise an error message is returned.

    vdraw write next command x y z

Append the given command and vector to the end of the current vlist. No return value.

    vdraw insert index command x y z

Insert the given command and vector in front of the index-th node of the current vlist. Returns an error if the index is not in the range 0 to n, where n is the length of the vlist.

    vdraw delete index

Delete the index-th node from the current vlist. Returns an error if index is not in the range 0 to n-1.

    vdraw delete last

Delete the last node from the current vlist. Returns an error if the current vlist is empty.

    vdraw delete all

Delete all of the nodes from the current vlist.

    vdraw params color rrggbb

Set the color parameter of the current vlist with a six-digit hexadecimal integer.

    vdraw params name name

Set the name of the current vlist to name. Returns an error if a vlist with the given name already exists.

    vdraw read index

Returns the contents of the index-th node of the current vlist, in the order command x y z. Returns an error if the node does not exist.

    vdraw read color

Returns the six-digit hexadecimal integer representing the color of the current vlist.

    vdraw read length

Returns the length of the current vlist.

    vdraw read name

Returns the name of the current vlist.

    vdraw send

Displays the current vlist by creating a pseudosolid. If the name of the vlist is name, then vdraw will create a pseudosolid named _VDRWname, replacing any existing pseudosolid with the same name. If a true solid with that name exists, "-1" is returned and the vlist is not displayed. A "0" is returned if the vlist is successfully displayed.

    vdraw vlist list

Returns a list containing the names of all of the vlists being maintained by vdraw, or an empty string if there are no vlists.

    vdraw vlist delete name

Deletes the named vlist. If the vlist doesn't exist, an error is returned. Note that this only deletes the copy of the vlist maintained by vdraw -- the corresponding pseudosolid, if it exists, is not automatically deleted.

# EXAMPLES

Open a vlist called "triangle", and read its initial name and length.

    mged> vdraw o triangle
    1
    mged> vdraw r n
    triangle
    mged> vdraw r l
    0

Add the normal vector and defining points to the list, then display it.

    mged> vdraw w n 2 0.0 0.0 1.0
    mged> vdraw w n 3 0.0 0.0 0.0
    mged> vdraw w n 4 10.0 0.0 0.0
    mged> vdraw w n 4 0.0 10.0 0.0
    mged> vdraw w n 5 0.0 0.0 0.0
    mged> vdraw r l
    5
    mged> vdraw s
    0

Display it in red.

    mged> vdraw p c ff0000
    mged> vdraw s
    0