<!-- Converted by db4-upgrade version 1.0 -->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="vdraw">

<refmeta>
  <refentrytitle>VDRAW</refentrytitle>
  <manvolnum>nged</manvolnum>
  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
  <refmiscinfo class="manual">BRL-CAD MGED Commands</refmiscinfo>
</refmeta>

<refnamediv xml:id="name">
  <refname>vdraw</refname>
  <refpurpose>Allows drawing of lines and polygons (optionally with per
vertex normals) in the MGED graphics display. It is used to build a named list of
drawing commands for MGED, send the list to the MGED display, modify the list, or
delete all or part of the list.   </refpurpose>
</refnamediv>

<!-- body begins here -->
<refsynopsisdiv xml:id="synopsis">
  <cmdsynopsis sepchar=" ">
    <command>vdraw</command>    
    
    <arg choice="req" rep="norepeat"><replaceable>command</replaceable></arg>
    <arg choice="opt" rep="norepeat"><replaceable>args</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection xml:id="description"><info><title>DESCRIPTION</title></info>
  
  <para>Allows drawing of lines and polygons (optionally with per
vertex normals) in the MGED graphics display. It is used to build a named list of
drawing commands for MGED, send the list to the MGED display, modify the list, or
delete all or part of the list. All vertices in the <emphasis>vdraw</emphasis> command are in millimeters.
The MGED drawing commands are represented by integers in the <emphasis>vdraw</emphasis> command.
The MGED drawing commands and the integers that <emphasis>vdraw</emphasis> uses for them are:
   </para>
<table frame="all">
<tgroup cols="3" align="center" colsep="1" rowsep="1">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<thead>
<row>
	<entry>MGED Drawing Command</entry>
	<entry>Vdraw integer</entry>
	<entry>MGED Action</entry>
</row>
</thead>
<tbody>
<row>
	<entry>RT_VLIST_LINE_MOVE</entry>
	<entry>0</entry>
	<entry>Begin a new line at this point</entry>
</row>
<row>
	<entry>RT_VLIST_LINE_DRAW</entry>
	<entry>1</entry>
	<entry>Draw line from previous point to this point</entry>
</row>
<row>
	<entry>RT_VLIST_POLY_START</entry>
	<entry>2</entry>
	<entry>Start polygon (argument is surface normal)</entry>
</row>
<row>
	<entry>RT_VLIST_POLY_MOVE</entry>
	<entry>3</entry>
	<entry>move to first polygon vertex </entry>
</row>
<row>
	<entry>RT_VLIST_POLY_DRAW</entry>
	<entry>4</entry>
	<entry>Subsequent polygon vertices </entry>
</row>
<row>
	<entry>RT_VLIST_POLY_END</entry>
	<entry>5</entry>
	<entry>Last polygon vertex (should be same as first)</entry>
</row>
<row>
	<entry>RT_VLIST_POLY_VERTNORM</entry>
	<entry>6</entry>
	<entry>Vertex normal (for shading interpolation)</entry>
</row>
</tbody>
</tgroup>
</table>

<para>
The <command>vdraw</command> commands are as follows:
</para>

<itemizedlist mark="bullet">
<listitem>
	<para>open -- with no arguments, this returns 1 if there is a open list; 0 otherwise. If
	an argument is supplied, a command list is opened with the provided name.
	</para>
</listitem>

<listitem>
	<para>write-- with arguments of <emphasis> i c x y z</emphasis>, the MGED drawing command <command>#c</command> is placed in the <emphasis>ith</emphasis> position of the command list with the vertex as (<emphasis> x y z</emphasis>).
	</para>
	<para>-- with arguments of <emphasis> next c x y z</emphasis>, the command is placed at the end of the list.
	</para>
</listitem>

<listitem>
<para>insert -- with arguments of<emphasis> i c x y z</emphasis>, the MGED drawing command <emphasis>#c</emphasis> is inserted
just before the <emphasis>ith </emphasis>position of the command list.
</para>
</listitem>

<listitem>
<para>delete -- with an integer argument of i, the <emphasis>ith</emphasis> command is deleted.</para>
<para>-- with an argument of "last," the last command on the list is deleted.</para>
<para>-- with an argument of "all," all the commands on the list are deleted.</para>
</listitem>

<listitem>
<para>params -- with an argument of <emphasis> color rrggbb</emphasis>, the color of all objects on this list is
set. The <emphasis>rrggbb</emphasis> is a hex number representing the color, "ffffff" is white, "ff0000"
is red, "00ff00" is green, etc.</para>
<para>-- with a single string argument, the name of the current list is changed.
</para>
</listitem>
<listitem>
<para>read -- with an integer argument of <emphasis>i</emphasis>, the <emphasis>ith</emphasis> command is returned.</para>
<para>-- with an argument of "color," the current color is returned.</para>
<para>-- with an argument of "length," the number of commands in the current list is returned.</para>
<para>-- with an argument of "name," the name of the current command list is returned.</para>
</listitem>
<listitem>
<para>send -- send the current command list to the MGED display manager.
</para>
</listitem>

<listitem>
<para>vlist -- with an argument of "list," return a list of the names of all existing
command lists.</para>
<para>-- with an argument of <emphasis>delete list_name</emphasis>, delete the specified command list.
</para>
</listitem>
</itemizedlist>
<para>All textual arguments may be abbreviated by their first letter.</para>

</refsection>

<refsection xml:id="examples"><info><title>EXAMPLES</title></info>
  
  <para>The eight examples show the use of the <command>vdraw</command> command with four different commands and various arguments to build a list of commands to draw a square.
   </para>
  
       
  <example><info><title>Open a specified list.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw open square</userinput>
    </para>
    <para>Opens a list named <emphasis>square</emphasis>.
    </para>
  </example>
 <example><info><title>Set the color.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw params color ff00</userinput>
    </para>
    <para>Sets the color to green.
    
    </para>
  </example>
<example><info><title>Start a line at the origin.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw write next 0 0 0 0</userinput>
    </para>
    <para>Starts a line at the origin.
       
    </para>
  </example>
<example><info><title>Draw a line from the previous point to a specified point.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw write next 1 100 0 0</userinput>
    </para>
    <para>Draws a line from the origin to (100 0 0).
       
    </para>
  </example>
<example><info><title>Draw a line from the previous point to a specified point.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw write next 1 100 100 0</userinput>
    </para>
    <para>Draws a line from the previous point to (100 100 0).
       
    </para>
  </example>
<example><info><title>Draw a line from the previous point to a specified point.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw write next 1 0 100 0</userinput>
    </para>
    <para> Draws a line from the previous point to (0 100 0).
       
    </para>
  </example>
<example><info><title>Draw a line from the previous point to the origin.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw write next 1 0 0 0</userinput>
    </para>
    <para>
       Draws a line from the previous point to the origin.
    </para>
  </example>
<example><info><title>Send the command list to the display manager.</title></info>
    
    <para>
      <prompt>mged&gt;</prompt><userinput>vdraw send</userinput>
    </para>
    <para>Draws the square in the MGED display.
       
    </para>
  </example>


</refsection>

<info><corpauthor>BRL-CAD Team</corpauthor></info>

<refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
  
  <para>
    Reports of bugs or problems should be submitted via electronic
    mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.
  </para>
</refsection>
</refentry>
