mnl@IDTSUN.E-TECHNIK.TH-DARMSTADT.DE ("Michael N. Lipp") (03/28/91)
My original question was:
Michael> We want to implement the tpic-commands for our dvi-to-laserjet. We
Michael> know about tpic only from xdvi and we feel a little unsafe about
Michael> reverse engeneering tpic from there. Is there any documentation about
Michael> tpic?
Thanks to all for anwering. I simply had not been aware that tpic was
a program of its own, as I know tpic-specials only from transfig, a
program that converts xfig-output to tpic-specials.
There is a manual coming with the tpic program that explains the tpic
specials in the appendix. jourdan@MINOS.INRIA.FR sent me an extraction
that I append at the end of this message.
Again thanks to all who answered.
Michael
-------------------------------------------------------------------------------
\section{Output Specification}
This section defines the output language which is generated by
\tpic/. It is intended only for use by writers of
{\sc dvi} device drivers. The first lines of output will
execute a \tcom{newbox} command to define \tcom{graph} if it
has not already been defined. Each picture is enclosed in a \tcom{vtop}
which is assigned to \tcom{graph}. The width and height of this box are
the size of the picture as known to \tpic/ (text doesn't count because
\tpic/ can't know how wide it may be). Inside this box are a
sequence of \tcom{special} commands which define all the graphics,
along with \tcom{hbox} commands setting the text left, right, or center
of a given point.
Each graphical element is placed relative to \TeX's idea of the location
of this \tcom{special} on the page. Each \tcom{special} is set at the
top left corner of the \tcom{graph} box. This point is considered the
origin of the graph. The $x$ axis is positive to the right, and the $y$
axis is positive moving down the page. Thus the coordinates in the
graphics commands are in terms of a virtual page with axes oriented the
same as on many printers and workstation screens, like this:
.PS
"0,0" at (0,0) above
arrow from (0,0) to (0.5,0)
"\ $+x$" at (0.5,0) ljust
arrow from (0,0) to (0,-0.5)
"$+y$" at end of last arrow below
.PE
\centerline{\box\graph}
Angles are measured in the conventional way, from $+x$ towards $+y$.
Unfortunately, that reverses the meaning of "counterclockwise" from
what you see in the output. Angle measurements are in radians, from
0 to $2\pi$. A complete circle or ellipse will have
$\hbox{\it start angle}=0$ and $\hbox{\it end angle} \ge 2\pi$.
Thus, each distance (expressed in milli-inches) will be a positive number,
since the box encloses all of the graphical elements.
The possible \tcom{special} commands which must be implemented are
as follows. All numbers which represent distances
are integers except where noted. Angles are always measured in radians,
and they are measured in the conventional way from $+x$ towards $+y$.
Normally, this would be ``counterclockwise''.
Unfortunately, since the $y$ axis points down
instead of up, this turns out to be backwards.
This is especially confusing because in the input language, $+y$
point upwards. Device driver writers should beware of this point.
It is best to do all arithmetic in the coordinates of \tpic/'s output,
then convert the resulting endpoints to the device's coordinates
for printing; this should produce correct results in all cases.
\begin{description}
\item[pn $s$] Sets the pen size to $s$ milli-inches.
\item[pa $x$ $y$] Add point $(x,y)$ to a ``path'' which is
being stored in the {\sc dvi} interpreter.
The values of $x$ and $y$ are in milli-inches.
\item[fp] Flush (i.e., print using the current pen size)
a previously defined path. The number of path
elements is reset to zero. If shading has been
specified, and if the path is closed, then the
enclosed area should be shaded. Currently,
\tpic/ can only specify closed regions which are
rectangles using the {\tt pa} command, and
circles/ellipses are specified with the {\tt ar}
command; however, device driver writers should
not rely on this restriction. Someday, \tpic/
may be able to specify arbitrary closed areas
using {\tt pa} commands. Currently, the only
example of this is the shading of arrowheads,
which are triangular.
\item[ip] This is the same as {\tt fp} except that the
path is not actually drawn. Shading of the defined
region is performed if it has been specified.
\item[da $f$] This is the same as {\tt fp} except that the line
is drawn as a dashed line with $f$ inches per dash
($f$ is a real number).
\item[dt $f$] This is the same as {\tt da} except that a dotted
line is drawn, with $f$ inches between each
dot ($f$ is a real number).
\item[sp $d$] This is the same as {\tt fp} except that a spline
is drawn through the points. The spline is guaranteed
to go through only the first and last points,
depending on the relative positions of any
intermediate points. The argument $d$ is an
optional real value. If $d=0$ or the argument
is omitted,
the spline is drawn normally, as a solid line.
If $d>0$, it is dashed with $d$ as the dashwid, else
if $d<0$, the spline is dotted with $-d$ as the dotwid.
\item[ar $x$ $y$ $r_x$ $r_y$ $s$ $e$]
Draw an arc with center at $(x,y)$, from
starting angle $s$ to ending angle $e$.
If it's a complete circle or ellipse, then
$r_x$ and $r_y$ determine the $x$ and $y$ radii,
respectively. Otherwise, $r_x=r_y$ will hold,
and an arc from $s$ to $e$ should be drawn.
\item[ia $x$ $y$ $r_x$ $r_y$ $s$ $e$] The {\tt ia} command is to {\tt ar} what
{\tt ip} is to {\tt fp}.
\end{description}
The following command is optional in {\sc dvi} driver implementations
of \tpic/. Drivers which do not implement it should silently ignore it.
\begin{description}
\item[sh $s$] Shade the interior of the next closed figure defined
with three or more {\tt pa} commands followed
by a {\tt fp} or {\tt ip} command, or by an
{\tt ar} or {\tt ia} command. The value $s$ is
a floating point number from 0 to 1. Zero implies
a completely white interior (including erasing
anything underneath), while 1 implies completely
black. A value of 0.5 is a default
``normal'' gray shading. If $s$ is not specified,
a value of 0.5 should be used. NB: Shading applies
to the interior of the object only; the borders of
the object are still drawn using the current pen,
which is particularly important for dvi drivers
which do not support the {\tt sh} command. The
pixels generated by the shading value should be
``ANDed'' with the pixels already in the area.
Subsequent text pixels should be ``ORed''. Thus,
text {\it followed\/} by a ``{\tt sh 0}'' command
covering the same area will disappear. Any shading
value greater than zero should add the shading
to the existing text, with the text remaining
visible. Of course, a shading value of one will
be completely black, so any text that is there
won't be distinguishable.
\end{description}
The following two opcodes are considered obsolete, but they probably should be
implemented for backwards compatibility:
\begin{description}
\item[wh] This is the same as ``{\tt sh 0}''.
\item[bk] This is the same as ``{\tt sh 1}''.
\item[tx] This command was used to specify a texture
to be used in shading instead of the default
one. Its use was limited to
only one particular Imagen device driver,
and it was very device-specific. Its
implementation is discouraged in favor of
support for the argument to the {\tt sh} command.
\end{description}
-----------------,------------------------------,------------------------------
Michael N. Lipp ! Institut fuer Datentechnik ! Phone: 49-6151-163776
! Merckstr. 25 ,----------' Fax: 49-6151-164976
! D-6100 Darmstadt ! E-Mail: xdatmnlx@ddathd21.bitnet
! (Germany) ! mnl@idtsun.e-technik.th-darmstadt.de
-----------------'-------------------'-----------------------------------------