% This file was converted from HTML to LaTeX with Nathan Torkington's
% html2latex program
% Version 0.9b
\chapter{PostScript Operators}

\section*{Operator: add}
{\it num1} {\it num2} {\bf add} {\it num3}

This operator returns the addition of the two arguments.

\begin{itemize}
\item stackunderflow
\item typecheck
\item undefinedresult

\end{itemize}
See also:
\begin{itemize}
\item {\bf div}
\item {\bf mul}
\item {\bf sub}
\end{itemize}

\section*{Operator: arc}
{\it x-coord} {\it y-coord} {\it r} {\it ang1} {\it ang2} {\bf arc} {\bf -}
 
This operator adds an arc to the current path.  The arc is generated 
by sweeping a line segment of length {\it r}, and tied at the point 
({\it x-coord} {\it y-coord}), in a counter-clockwise direction from 
an angle {\it ang1} to and angle {\it ang2}.  Note: a straight line 
segment will connect the current point to the first point of the arc, 
if they are not the same.
\begin{itemize}
\item limitcheck
\item stackunderflow
\item typecheck
\end{itemize}

\section*{Operator: begin}
{\it dict} {\bf begin} {\bf -}
 
This operator pushes the dictionary {\it dict} onto the
dictionary stack. Where it can be used for
{\bf def} and name lookup. This operator
allows an operator to set up a dictionary for its own use (e.g. for
local variables).
 
Errors:
\begin{itemize}
\item dictstackoverflow
\item invalidaccess
\item stackunderflow
\item typecheck
\end{itemize}

\section*{Operator: bind}
{\it procedure1} {\bf bind} {\it procedure2}
 
The {\bf bind} operator goes through {\it procedure1} and replaces any
operator names with their associate operators. Names which do not
refer to operators are left alone. Operators within
{\it procedure1} which have unrestricted access will have {\bf bind}
called on themselves before they are inserted into the procedure. The
new procedure with operators instead of operator names is returned on
the stack as {\it procedure2}. \par 
The main effect and use of this operator is to reduce the amount of
name lookup done by the interpreter. This speeds up execution and ties
down the behavior of operators. \par 
Errors:
\begin{itemize}
\item typecheck
\end{itemize}

\section*{Operator: clip} {\bf -} {\bf clip} {\bf -}

This operator intersects the current clipping path with the current
path and sets the current clipping path to the results. Any part of a
path drawn after calling this operator which extends outside this new
clipping area will simply not be drawn. If the given path is open,
{\bf clip} will treat it as if it were closed. Also, {\bf clip} does not destroy
the current path when it is finished... it may be used for other 
activities. 

It is important to note that there is no easy way to restore the clip
path to a larger size once it has been set. The best way to set the
clip path is to wrap it in a
{\bf gsave} and
{\bf grestore} pair. 

Errors:
\begin{itemize}
\item limitcheck
\end{itemize}

\section*{Operator: closepath}
- {\bf closepath} - 

This operator adds a line segment to the current path from the current
point to the first point in the path. This closes the path so that it
may be filled. 

Errors:\begin{itemize}
\item limitcheck
\end{itemize}

Also see the following operators:
\begin{itemize}
\item {\bf newpath}
\item {\bf moveto}
\item {\bf lineto}
\end{itemize}

\section*{Operator: charpath}
{\it string} {\it bool} {\bf charpath} {\bf -}

This operator takes the given string and appends the path which the
characters define to the current path. The result is can be used as
any other path for stroking, filling, or clipping.
 
The boolean argument informs {\bf charpath} what to do if the font was not
designed to be stoked. If the boolean is true, the path will be
modified to be filled and clipped (but not stroked). If the boolean
is false, the path will be suitable to be stroked (but not filled or
clipped).

\begin{itemize}
\item limitcheck
\item nocurrentpoint
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf clip}
\item {\bf fill}
\item {\bf show}
\item {\bf stroke}
\end{itemize}

\section*{Operator: curveto}
{\it x1} {\it y1} {\it x2} {\it y2} {\it x3} {\it y3} {\bf curveto} {\bf -}

This operator draws a curve from the current point to the point
({\it x3}, {\it y3}) using points
({\it x1}, {\it y1}) and
({\it x2}, {\it y2})
as control points.
The curve is a B{\'e}zier cubic curve.
In such a curve, the tangent of the curve at the current point will
be a line segment running from the current point to
({\it x1}, {\it y1})
and the tangent at ({\it x3}, {\it y3}) is the line running
from ({\it x3}, {\it y3}) to ({\it x2}, {\it y2}). 

\begin{itemize}
\item limitcheck
\item nocurrentpoint
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf arc}
\item {\bf lineto}
\item {\bf moveto}
\end{itemize}

\section*{Operator: def}
{\it name} {\it value} {\bf def} {\bf -} 

This operator associates the {\it name } with {\it value} in
the dictionary at the top of the dictionary stack. This operator
essentially defines names to have values in the dictionary and is used
to define variables and operators.
 
Errors:
\begin{itemize}
\item dictfull
\item invalidaccess
\item limitcheck
\item stackunderflow
\item typecheck
\item VMerror
\end{itemize}

\section*{Operator: div}
{\it num1} {\it num2} {\bf div} {\it num3}

This operator returns the result of dividing {\it num1} by
{\it num2}. The result is always a real.

\begin{itemize}
\item stackunderflow
\item typecheck
\item undefinedresult
\end{itemize}

See also:

\begin{itemize}
\item {\bf add}
\item {\bf mul}
\item {\bf sub}
\end{itemize}

\section*{Operator: dup}
{\it object} {\bf dup} {\it object} {\it object} 

This operate pushes a second copy of the topmost object on the operand
stack. If the object is a reference to an array, string, or similar
composite object, only the reference is duplicated; both references
will still refer to the same object.
 
Errors:
\begin{itemize}
\item stackoverflow
\item stackunderflow
\end{itemize}

\section*{Operator: end}
{\bf -} {\bf end} {\bf -}
 
This operator pops the topmost dictionary off of the dictionary stack.
The dictionary below it becomes the new current dictionary.

Errors:
\begin{itemize}
\item dictstackunderflow
\end{itemize}

\section*{Operator: fill}
{\bf -} {\bf fill} {\bf -} 

This operator closes and fills the current path with the current
color. Any ink within the path is obliterated. Note that {\bf fill} blanks
out the current path as if it had called
{\bf newpath}.
If you want the current path preserved, you should use
{\bf gsave} and
{\bf grestore}
to preserve the path.

Errors:
\begin{itemize}
\item limitcheck
\end{itemize}

\section*{Operator: findfont}
{\it name} {\bf findfont} {\it font} 

This operator looks for the named font in the font dictionary. If it
finds the font, it pushes the font on the stack for later
processing. It signals an error if the font can not be found.

Errors:
\begin{itemize}
\item invalidfont
\item stackunderflow
\item typecheck
\end{itemize}

Also see the following operators:

\begin{itemize}
\item {\bf scalefont}
\item {\bf setfont}
\end{itemize}

\section*{Operator: for}
{\it initial} {\it increment} {\it limit} {\it proc} {\bf for} {\bf -}

This operator will execute {\it proc} repeatedly.
The first time {\it proc} is executed, it will be given
{\it initial} as the top operand.
Each time it is executed after that, the top operand will be
incremented by {\it increment}.
This process will continue until the argument would have exceeded
{\it limit}.

\begin{itemize}
\item stackoverflow
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf if}
\item {\bf ifelse}
\end{itemize}

\section*{Operator: grestore}
{\bf -} {\bf grestore} {\bf -}

Sets the current graphics state to the topmost graphics state on
graphics state stack and pops that state off the stack. This operator
is almost always used in conjunction with 
{\bf gsave}.

\section*{Operator: gsave}
{\it -} {\bf gsave} {\bf -}

This operator pushes a copy of the current graphics state onto the
graphics state stack. The graphics state consists of (among other
things):
\begin{itemize}
\item Current Transformation Matrix
\item Current Path
\item Clip Path
\item Current Color
\item Current Font
\item Current Gray Value
\end{itemize}
{\bf gsave} is typically used with
{\bf grestore}
whenever you need to change the
graphics state temporarily and return to the original.

Errors:
\begin{itemize}
\item limitcheck
\end{itemize}

\section*{Operator: if}
{\it bool} {\it proc} {\bf if} {\bf -}

This operator will execute {\it proc} if {\it bool} is true.
\begin{itemize}
\item stackunderflow
\item typecheck
\end{itemize}

\section*{Operator: ifelse}
{\it bool} {\it proc1} {\it proc2} {\bf ifelse} {\bf -}

This operator will execute {\it proc1} if {\it bool} is true
and {\it proc2} otherwise.
\begin{itemize}
\item stackunderflow
\item typecheck
\end{itemize}

\section*{Operator: lineto}
{\it x-coord} {\it y-coord} {\bf lineto} -

This operator adds a line into the path. The line is from the current
point to the point ({\it x-coord} {\it y-coord}). After the
line is added to the path, the current point is set to ({\it x-coord
} {\it y-coord}). It is an error to call {\bf lineto}
without having a current point.

Errors:
\begin{itemize}
\item limitcheck
\item nocurrentpoint
\item stackunderflow
\item typecheck
\end{itemize}

Also see the following operators:
\begin{itemize}
\item {\bf rlineto}
\item {\bf moveto}
\item {\bf rmoveto}
\item {\bf curveto}
\item {\bf arc}
\item {\bf closepath}
\end{itemize}

\section*{Operator: moveto}
{\it x-coord} {\it y-coord} {\bf moveto} -

This operator moves the current point of the current path to the given
point in user space. If a {\bf moveto} operator
immediately follows another {\bf moveto} operator, the
previous one is erased.

Errors:
\begin{itemize}
\item limitcheck
\item stackunderflow
\item typecheck
\end{itemize}

Also see the following operators:
\begin{itemize}
\item {\bf rmoveto}
\item {\bf lineto}
\item {\bf curveto}
\item {\bf arc}
\item {\bf closepath}
\end{itemize}

\section*{Operator: mul}
{\it value1} {\it value2} {\bf mul} {\it product}

This operator multiplies the first two operands on the stack and
pushes the result back onto the stack. The result is an integer if
both operands are integers and the product is not out of range. If the
product is too big, or one of the operands is a real, the result will
be a real.

Errors:
\begin{itemize}
\item stackunderflow
\item typecheck
\item undefinedresult
\end{itemize}

\section*{Operator: newpath}
{\bf -} {\bf newpath} {\bf -}

The newpath operator clears out the current path and prepares the
system to start a new current path. This operator should be called
before starting {\it any} new path, even though some operators
call it implicitly.

\section*{Operator: restore}
{\it state} {\bf restore} -

This restores the total state of the PostScript system to the state 
saved in {\it state}.

Errors:
\begin{itemize}
\item invalidrestore
\item stackunderflow
\item typecheck
\end{itemize}

See also:
\begin{itemize}
\item {\bf save}
\end{itemize}

\section*{Operator: rlineto}
{\it dx} {\it dy} {\bf rlineto} -

This operator adds a line into the path. The line is from the current
point to a point found by adding {\it dx} to the current {\it x} 
and {\it dy} to the current {\it y}. After
line is added to the path, the current point is set to the new point. 
It is an error to call {\bf lineto}
without having a current point.

Errors:
\begin{itemize}
\item limitcheck
\item nocurrentpoint
\item stackunderflow
\item typecheck
\end{itemize}

Also see the following operators:

\begin{itemize}
\item {\bf lineto}
\item {\bf moveto}
\item {\bf rmoveto}
\item {\bf curveto}
\item {\bf arc}
\item {\bf closepath}
\end{itemize}

\section*{Operator: rmoveto}
{\it dx} {\it dy} {\bf rmoveto} -

This operator moves the current point of the current path by adding
{\it dx} to the current {\it x} and {\it dy} to the
current {\it y}.

Errors:
\begin{itemize}
\item limitcheck
\item stackunderflow
\item typecheck
\end{itemize}

Also see the following operators:

\begin{itemize}
\item {\bf moveto}
\item {\bf lineto}
\item {\bf curveto}
\item {\bf arc}
\item {\bf closepath}
\end{itemize}

\section*{Operator: rotate}
{\it angle} {\bf rotate} {\bf -} 

This operator has the effect of rotating the user space
counter-clockwise by {\it angle} degrees (negative angles rotate
clockwise). The rotation occurs around the current origin.
\begin{itemize}
\item rangecheck
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf scale}
\item {\bf translate}
\end{itemize}

\section*{Operator: save}
- {\bf save} {\it state}

This operator gathers up the complete state of the PostScript system
and saves it in {\it state}.

Errors:
\begin{itemize}
\item limitcheck
\item stackoverflow
\end{itemize}

See Also:

\begin{itemize}
\item {\bf restore}
\end{itemize}

\section*{Operator: scale}
{\it sx} {\it sy} {\bf scale} {\bf -}

This operator has the effect of scaling the user coordinates.
All coordinates will be multiplied by {\it sx} in the horizontal
direction, and {\it sy} in the vertical.

The origin will not be affected by this operation.
\begin{itemize}
\item rangecheck
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf rotate}
\item {\bf translate}
\end{itemize}

\section*{Operator: scalefont}
{\it font} {\it size} {\bf scalefont} {\it font}

This operator takes the given font and scales it by the given scale
factor. The resulting scaled font is pushed onto the stack. A {\it 
size}
of one produces the same sized characters as the original
font, 0.5 produces half-size characters, and so on. 

Errors:
\begin{itemize}
\item invalidfont
\item stackunderflow
\item typecheck
\item undefined
\end{itemize}

Also see the following operators:

\begin{itemize}
\item {\bf findfont}
\item {\bf setfont}
\end{itemize}

\section*{Operator: setfont}
{\it font} {\bf setfont} -

This operator sets the current font to be {\it font}. This font
can be the result of any font creation or modification operator. This
font is used in all subsequent character operations like
show.

\begin{itemize}
\item invalidfont
\item stackunderflow
\item typecheck
\end{itemize}

Also see:

\begin{itemize}
\item {\bf findfont}
\item {\bf scalefont}
\end{itemize}

\section*{Operator: setgray}
{\it gray-value} {\bf setgray} -

This operator sets the current intensity of the ink to {\it 
gray-value}.
{\it gray-value} must be a number from 0 (black) to 1
(white). This will affect all markings stroked or filled onto the
page. This applies even to path components created before the call to
{\bf setgray} as long as they have not yet been stroked.

\begin{itemize}
\item stackunderflow
\item typecheck
\item undefined
\end{itemize}

\section*{Operator: setlinewidth}
{\it width} {\bf setlinewidth} -

This operator sets the width of all lines to be stroked to
{\it width}, which must be specified in points. A line width of
zero is possible and is interpreted to be a hairline, as thin as can
be rendered on the given device.

\begin{itemize}
\item stackunderflow
\item typecheck
\end{itemize}

\section*{Operator: show}
{\it string} {\bf show} {\bf -}

This operator draws the given string onto the page.
The current graphics state applies, so the current font, fontsize,
gray value, and
current transformation matrix
all apply.

The location for the text is set by the current point.
The current point will specify the leftmost point of the baseline
for the text.

\begin{itemize}
\item invalidaccess
\item invalidfont
\item nocurrentpoint
\item rangecheck
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf charpath}
\item {\bf moveto}
\item {\bf setfont}
\end{itemize}

\section*{Operator: showpage}
- {\bf showpage} -

This operator commits the current page to print and ejects the page
from printing device. {\bf showpage} also prepares a new
blank page.

\section*{Operator: stroke}
{\bf -} {\bf stroke} {\bf -}

This operator draws a line along the current path using the current
settings. This includes the current line thickness, current pen color,
current dash pattern, current settings for how lines should be joined,
and what kind of caps they should have. These settings are the
settings at the time the stroke operator is invoked.

A closed path consisting of two or more points at the same location is
a degenerate path. A degenerate path will be drawn only if you have
set the line caps to round caps. If your line caps are not round caps,
or if the path is not closed, the path will not be drawn. If the path
is drawn, it will appear as a filled circle center at the point.

Errors:
\begin{itemize}
\item limitcheck
\end{itemize}

\section*{Operator: sub}
{\it num1} {\it num2} {\bf sub} {\it num3}

This operator returns the result of subtracting {\it num2}
from {\it num1}.

\begin{itemize}
\item stackunderflow
\item typecheck
\item undefinedresult
\end{itemize}

See also:

\begin{itemize}
\item {\bf add}
\item {\bf div}
\item {\bf mul}
\end{itemize}

\section*{Operator: translate}
{\it x-coord} {\it y-coord} {\bf translate} {\bf -}

This operator has the affect of moving the origin to the point
({\it x-coord}, {\it y-coord}) in the current user space. 

\begin{itemize}
\item rangecheck
\item stackunderflow
\item typecheck
\end{itemize}

See also:

\begin{itemize}
\item {\bf rotate}
\item {\bf scale}
\end{itemize}
