%
% manual for XVirtual, corrected and clarified by Peter Chang -
%  peterc@a3.ph.man.ac.uk
%
% Concepts changed: rotation-object = surface of revolution
%                   sweep-object    = extruded surface or prism
%
% Lots of spelling amended, some grammar, nouns, whole sentences modified
% or deleted. Some comments on things that I'm confused by are enclosed
% in square brackets - [* - PC].
%
\documentstyle{article}
\sloppy
\begin{document}
\title{X-Virtual 1.0}
\author{Marcus Roth}
\date{20th Sep 1994}
\maketitle
\begin{abstract}
X-Virtual is a program to visualize and animate 3D-objects. This document
describes the key-bindings and the definition/animation language.

I hope this documentation is understandable. It needs some experience to
generate complex objects and animate them. The best way to get a knowledge
of this, is to have a look at the demo files.

Maybe there is someone whose English is better then mine, who wants to 
improve this \LaTeX-document. Please send it to me. I'm also interested
in good animation files. If you have changed the source code, please
let me know, if you have done something to make the program better.
\begin{tabbing}
\\
Email: roth@beholder2.rz.uni-mannheim.de\\
\end{tabbing}
I hope you enjoy XVirtual. 
\end{abstract}
\thanks{Thanks to Axel Ahal and Frank Roth}
\\
\newpage
\tableofcontents
\newpage

\section{Start program}
>From a X-terminal, type\\
\tt{xvirtual file} ( without .3d )   
 
\section{Key-bindings}
\begin{tabbing}
$\leftarrow$\=turn right\\
$\rightarrow{}$\>turn left\\
$\uparrow{}$\>go forward\\
$\downarrow{}$\>go back\\
$+$\>go up\\
$-$\>go down\\
$\Uparrow{}$\>look up\\
$\Downarrow{}$\>look down\\
\end{tabbing}
\section{Definition language}

\subsection{Syntax}
The program reads its data from a file with the extension .3d. This file can
be generated and modified with an editor. In each line, only one command can
be used.

If you write a command which the interpreter doesn't know, it tries to find
a file with the extension .3d. If this file exists, it will be executed
(interpreted). The file is searched for, first, in the current directory
then, if there is no matching file, the 3d/ is searched.

Command parameters should be enclosed by spaces.
\tt{command parm1 parm2 ...}. Numbers are written as shown below.
\tt{
\\
$1.23$\\
$-5$\\
$0.25$\\
$.5$ this is wrong !!!
}

\subsection{Coordinates and angles}
In the normal context, x points to right, y forward and z up.
In generating revolved or extruded surfaces, x points to right, y points up.

All angles should be specified in degrees.

\subsection{Comments}
\tt{; comment .... }

After `;' you can write anything until the end of the line.

\subsection{Definition-commands}
\subsubsection{OBJECT}
\tt{object name}

With the OBJECT command you begin an object definition. All elements which
are in an object block, can be manipulated together, by manipulating the
object. Objects are allowed to be defined within objects. Thus it is
possible to define hierarchical objects. Names are character strings with
maximum length of 14 chars. With your chosen name you can access the object
at a later time.

\subsubsection{ENDOBJECT}
\tt{endobject}
This command closes an object block, started by OBJECT.

\subsubsection{POINT}
\tt{point x y z}

Defines a point with the coordinates x,y,z in the current object. Every 
point in an object has an index number. The first point is indexed as 1. You
need this number to access a point.

\subsubsection{POLYGON}
\tt{polygon p1 p2 p3 [p4 . . .]}\\
p is the number of a point

Defines a polygon through the points p1 p2 p3 ... Visible polygons are
defined clockwise [not sure what this means - PC].
\tt{
\begin{tabbing}
object \=square\\
\>color lightgreen\\
\>point 100 100 0\\
\>point 100 -100 0\\
\>point -100 -100 0\\
\>point -100 100 0\\
\>polygon 1 2 3 4\\
endobject\\
\end{tabbing}
}

\subsubsection{STONE}
\tt{stone [name] x y z}

Makes a cuboid with height z, width x and depth y. The centre of the
cuboid has the coordinates 0,0,0.

\subsubsection{PYRAMID}
\tt{pyramide [name] width height}

Generates a pyramid with a square base. The base size is width and the
height is height.

\subsubsection{TEXT}
\tt{text [name] ``text'' [charset dir]}\\
name = Name of an object.

dir = directory in which the character set is located. If dir is omitted, the
character set must be located in 3d/standard.\\
\tt{
\\
text ``this is an example text''\\
text ``this is line two. It is moved down.''\\
move 0 0 -20
}

\subsubsection{ROTPOINT}
\tt{rotpoint x y}

Defines a point on the curve for a surface of revolution. The commands
ROTOBJECT and ROTARC use this points.

\subsubsection{ROTARC}
\tt{rotarc x y a s}

The last point defined with ROTPOINT will be rotated with an arc of a and
with s steps, about the point x,y. This draws an arc as part of the curve
to be revolved.\\
\tt{
\\
rotpoint 0 10\\
rotarc 0 0 180 5\\
rotobject ball 10\\
}

\subsubsection{ROTOBJECT}
\tt{rotobject[name] s}

Generates a surface of revolution with s segments. The points defined with
ROTPOINT and ROTARC form a curve which will be rotated to generate an
object.\\
\tt{
\\
rotpoint 20 10\\
rotpoint 20 2\\
rotpoint 25 0\\
rotobject socket 10\\
}

If the start and end points of the curve aren't equal the resultant surface
gets capped by top and bottom surfaces. Otherwise you can define objects like
a torus.
\tt{
\\
rotpoint 10 0\\*
rotarc 20 0 360 6\\*
rotobject torus 12
}

\subsubsection{SWEEPPOINT}
\tt{sweeppoint x y}

It is possible to define a surface with a few points. These points are
used to generate an object with SWEEPOBJECT. This forms an extruded object,
a kind of prism whose cross-section is the defining surface.

\subsubsection{SWEEPARC}
\tt{sweeparc x y arc seg}

Like ROTARC this command rotates a sweep-point with seg segments.\\
\tt{
sweeppoint -10 0\\*
sweeparc 0 0 180 8\\*
sweepobject halfcircle 2
}

\subsubsection{SWEEPOBJECT}
\tt{sweepobject [name] h}

The sweep-points are used to generate an object. [what colours here? - PC]
\tt{
\\
color white\\*
sweeppoint 10 0\\*
sweeppoint 0 10\\*
sweeppoint -10 0\\*
color red\\*
sweepobject triangle 2
}

\subsubsection{COLOR}
\tt{color col-name}

Defines a colour for the following object. The following colours can be
used.\\
\\
red lightred\\
blue lightblue\\
green lightgreen\\
yellow\\
brown\\
orange\\
white gray black\\
violet

\subsubsection{COPY}
\tt{copy f t}

Copies the object f to the new object t. All object information is copied
including animation information.

\subsection{Manipulation commands}
All commands to manipulate objects have their effect on the last object
(closed with ENDOBJECT). If you use names with the manipulation commands, the
object which you wish to manipulate must be located in the current object
or in a deeper hierarchy [eh? - PC].

\subsubsection{MOVE}
\tt{move [object] x y z}

The current object will be moved to a new position with an offset of x y z
relative to its old position.

\subsubsection{ROTATE}
\tt{rotate [object] x y z}

Rotates the current object through a set of angles about axes going through
the centre of the object.
\tt{
\begin{tabbing}
object \=leg1\\*
\>object leg2\\*
\>leg\\*
\>endobject\\*
\>rotate 0 45 0\\*	
endobject\\*
\>rotate 0 0 30	
\end{tabbing}
}

\subsubsection{SCALE}
\tt{scale [object] x [y z]}

Stretches the current object. If only x is specified, the object is stretched
in all directions equally.

\subsubsection{CENTRE}
\tt{centre [object] x y z}

This command moves the centre of an object. This centre is used for rotation.
It is the local origin for the set of axes which ROTATE uses.

\subsubsection{SELECT}
\tt{select object}

Defines the named object as the current object.

\subsubsection{HIDE}
\tt{hide [object]}

Hides the current object. It will not be visible.

\subsubsection{SHOW}
\tt{show [object]}

Opposition to HIDE.

\subsection{Animation commands}
All animation commands uses the last object (closed with ENDOBJECT or
with SELECT selected objects). Within an animation command you can use
all the manipulation commands.

\subsubsection{ANIM}
\tt{
\begin{tabbing}
anim s [loop] [speedup|slowdown] [command|wait] [parameter] \\
or \\
anim \=s [loop] [speedup|slowdown]\\
\>command [parameter]\\
\>command [parameter]\\
endanim
\end{tabbing}}

Starts an animation sequence. The sequence is s seconds long. If loop is used
the sequence is executed endlessly.\\
\tt{
\begin{tabbing}
stone box 10 10 10\\*
anim \=6 loop\\*
\>anim 1 \= rotate 0 360 0 \=;Start after 0 seconds\\*
\>anim 2\>\>; Start after 1 second\\*
\>\>move 0 0 100\>; These commands are executed in parallel\\*
\>\>rotate 180 0 0\\*
\>\>scale 4\\*
\>endanim\\*
\>anim 3\>\>; Start after 3 seconds\\*
\>\>move 0 0 -100\\*
\>\>rotate -180 0 0\\*
\>\>scale 0.25\\*
\>endanim\\*
endanim
\end{tabbing}
}
You can simulate falling objects with speedup and slowdown.
\tt{
\begin{tabbing}
select \=ball\\*
\>anim \=4 loop\\*
\>\>anim 2 slowdown move 0 0 100 \=; the ball flies up and slows down.\\*
\>\>anim 2 speedup move 0 0 -100\>; the ball falls down and speeds up.\\*
\>endanim
\end{tabbing}
}

After the end of a loop the objects should be located at the same point
as at the beginning. Otherwise the animation is unpredictable. With WAIT
you can generate a pause.\\
\tt{
\\
anim 5 wait
}

\subsubsection{ENDANIM}
\tt{endanim}

Closes an anim block.

\subsubsection{ANIMSET}
\tt{animset s}

The animation of the current object starts at s seconds.

\subsection{Standard objects}
\subsubsection{szene}
You can select the whole scene with the object name szene.

\subsubsection{light}
You can select and animate the light.
\tt{
\begin{tabbing}
select \=light\\*
  \>rotate 0 0 180\\*
\end{tabbing}
}
or within an animation.
\tt{
\begin{tabbing}
select \=light\\*
\>anim \=loop 5\\*
\>\>rotate 0 0 360\\*
\>endanim
\end{tabbing}
}
\end{document}

