summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pstricks/psd-cust.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pstricks/psd-cust.tex406
1 files changed, 406 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex b/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex
new file mode 100644
index 00000000000..03441baca4f
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex
@@ -0,0 +1,406 @@
+%% BEGIN psd-cust.tex
+
+\part{Custom graphics\label{P-custom}}
+
+\Section{The basics}
+
+PSTricks contains a large palette of graphics objects, but sometimes you need
+something special. For example, you might want to shade the region between two
+curves. The
+ \Mac \pscustom`*[par]'{commands}
+command lets you ``roll you own'' graphics object.
+
+Let's review how PostScript handles graphics. A \emph{path} is a line, in the
+mathematical sense rather than the visual sense. A path can have several
+disconnected segments, and it can be open or closed. PostScript has various
+operators for making paths. The end of the path is called the \emph{current
+point}, but if there is no path then there is no current point. To turn the
+path into something visual, PostScript can \emph{fill} the region enclosed by
+the path (that is what \p{fillstyle} and such are about), and \emph{stroke} the
+path (that is what \p{linestyle} and such are about).
+
+At the beginning of \n\pscustom, there is no path. There are various commands
+that you can use in \n\pscustom{} for drawing paths. Some of these (the open
+curves) can also draw arrows. \n\pscustom{} fills and strokes the path at the
+end, and for special effects, you can fill and stroke the path along the way
+using \n\fill{} and \n\stroke{} (see below).
+
+\begin{drivers}
+\n\pscustom{} uses \n\pstverb{} and \n\pstunit. There are system-dependent
+limits on how long the argument of "\special" can be. You may run into this
+limit using \n\pscustom{} because all the PostScript code accumulated by
+\n\pscustom{} is the argument of a single "\special" command.
+\end{drivers}
+
+\Section{Parameters}
+
+You need to keep the separation between drawing, stroking and filling paths in
+mind when setting graphics parameters. The \p{linewidth} and \p{linecolor}
+parameters affect the drawing of arrows, but since the path commands do not
+stroke or fill the paths, these parameters, and the \p{linestyle},
+\p{fillstyle} and related parameters, do not have any other effect (except
+that in some cases \p{linewidth} is used in some calculations when drawing the
+path). \n\pscustom{} and \n\fill{} make use of \p{fillstyle} and related
+parameters, and \n\pscustom{} and \n\stroke{} make use of p{linestyle} and
+related parameters.
+
+For example, if you include
+\begin{LVerbatim}
+ \psline[linewidth=2pt,linecolor=blue,fillstyle=vlines]{<-}(3,3)(4,0)
+\end{LVerbatim}
+in \n\pscustom, then the changes to \p{linewidth} and \p{linecolor} will
+affect the size and color of the arrow but not of the line when it is stroked,
+and the change to \p{fillstyle} will have no effect at all.
+
+The \p{shadow}, \p{border}, \p{doubleline} and \p{showpoints} parameters are
+disabled in \n\pscustom, and the \p{origin} and \p{swapaxes} parameters only
+affect \n\pscustom{} itself, but there are commands (described below) that let
+you achieve these special effects.
+
+The \p{dashed} and \p{dotted} line styles need to know something about the
+path in order to adjust the dash or dot pattern appropriately. You can give
+this information by setting the
+\begin{Ex}
+ \Par{linetype=int}
+\end{Ex}
+parameter. If the path contains more than one disconnected segment, there is
+no appropriate way to adjust the dash or dot pattern, and you might as well
+leave the default value of \p{linetype}. Here are the values for simple paths:
+\begin{center}
+\begin{tabular}{cl}
+ \emph{Value} & \emph{Type of path}\\
+ 0 & Open curve without arrows.\\
+ -1 & Open curve with an arrow at the beginning.\\
+ -2 & Open curve with an arrow at the end.\\
+ -3 & Open curve with an arrow at both ends.\\
+ 1 & Closed curve with no particular symmetry.\\
+ $n$\textgreater 1 & Closed curve with $n$ symmetric segments.
+\end{tabular}
+\end{center}
+
+\Section{Graphics objects}
+
+You can use most of the graphics objects in \n\pscustom. These draw paths and
+making arrows, but do not fill and stroke the paths.
+
+There are three types of graphics objects:
+\begin{description}
+\item[Special]
+ Special graphics objects include \n\psgrid, \n\psdots, \n\qline{} and
+\n\qdisk. You cannot use special graphics objects in \n\pscustom.
+
+\item[Closed]
+ You are allowed to use closed graphics objects in \n\pscustom, but their
+effect is unpredictable.\footnote{%
+The closed objects never use the current point as an coordinate, but typically
+they will close any existing paths, and they might draw a line between the
+currentpoint and the closed curved.}
+Usually you would use the open curves plus \n\closepath{} (see below) to draw
+closed curves.
+
+\item[Open]The open graphics objects are the most useful commands for drawing
+paths with \n\pscustom. By piecing together several open curves, you can draw
+arbitrary paths. The rest of this section pertains to the open graphics
+objects.
+\end{description}
+
+ By default, the open curves draw a straight line between the current point,
+if it exists, and the beginning of the curve, except when the curve begins
+with an arrow. For example
+\begin{MEx*}(3,3)
+ \pscustom{%
+ \psarc(0,0){1.5}{5}{85}
+ \psarcn{->}(0,0){3}{85}{5}}
+\end{MEx*}
+
+Also, the following curves make use of the current point, if it exists, as a
+first coordinate:
+\begin{quote}
+ \n\psline{} and \n\pscurve.\\
+ The plot commands, with the "line" or "curve" \p{plotstyle}.\\
+ \n\psbezier\, if you only include three coordinates.\\
+\end{quote}
+For example:
+\begin{MEx*}(4,3)
+ \pscustom[linewidth=1.5pt]{%
+ \psplot[plotstyle=curve]{.67}{4}{2 x div}
+ \psline(4,3)}
+\end{MEx*}
+We'll see later how to make that one more interesting. Here is another example
+\begin{MEx*}(4,3)
+ \pscustom{%
+ \psline[linearc=.2]{|-}(0,2)(0,0)(2,2)
+ \psbezier{->}(2,2)(3,3)(1,0)(4,3)}
+\end{MEx*}
+
+However, you can control how the open curves treat the current point with the
+\begin{Ex}
+ \Par{liftpen=0/1/2}
+\end{Ex}
+parameter.
+
+If \p{liftpen=0}, you get the default behavior described above. For example
+\begin{MEx*}(4,3)
+ \pscustom[linewidth=2pt,fillstyle=solid,fillcolor=gray]{%
+ \pscurve(0,2)(1,2.5)(2,1.5)(4,3)
+ \pscurve(4,1)(3,0.5)(2,1)(1,0)(0,.5)}
+\end{MEx*}
+
+If \p{liftpen=1}, the curves do not use the current point as the first
+coordinate (except \n\psbezier, but you can avoid this by explicitly including
+the first coordinate as an argument). For example:
+\begin{MEx*}(4,3)
+ \pscustom[linewidth=2pt,fillstyle=solid,fillcolor=gray]{%
+ \pscurve(0,2)(1,2.5)(2,1.5)(4,3)
+ \pscurve[liftpen=1](4,1)(3,0.5)(2,1)(1,0)(0,.5)}
+\end{MEx*}
+
+If \p{liftpen=2}, the curves do not use the current point as the first
+coordinate, and they do not draw a line between the current point and the
+beginning of the curve. For example
+\begin{MEx*}(4,3)
+ \pscustom[linewidth=2pt,fillstyle=solid,fillcolor=gray]{%
+ \pscurve(0,2)(1,2.5)(2,1.5)(4,3)
+ \pscurve[liftpen=2](4,1)(3,0.5)(2,1)(1,0)(0,.5)}
+\end{MEx*}
+
+Later we will use the second example to fill the region between the two
+curves, and then draw the curves.
+
+\Section{Safe tricks}
+
+The commands described under this heading, which can only be used in
+\n\pscustom, do not run a risk of PostScript errors (assuming your document
+compiles without \TeX{} errors).
+
+Let's start with some path, fill and stroke commands:
+\begin{description}
+
+\mitem \newpath
+
+Clear the path and the current point.
+
+\mitem \moveto(coor)
+
+ This moves the current point to \c{}.
+
+\mitem \closepath
+
+ This closes the path, joining the beginning and end of each piece (there may
+be more than one piece if you use \n\moveto).\footnote{%
+Note that the path is automatically closed when the region is filled. Use
+\n\closepath{} if you also want to close the boundary.}
+
+\mitem \stroke`[par]'
+
+ This strokes the path (non-destructively). \n\pscustom{} automatically
+strokes the path, but you might want to stroke it twice, e.g., to add a
+border. Here is an example that makes a double line and adds a border (this
+example is kept so simple that it doesn't need \n\pscustom{} at all):
+\begin{MEx*}(4,3)
+ \psline(0,3)(4,0)
+ \pscustom[linecolor=white,linewidth=1.5pt]{%
+ \psline(0,0)(4,3)
+ \stroke[linewidth=5\pslinewidth]
+ \stroke[linewidth=3\pslinewidth,linecolor=black]}
+\end{MEx*}
+
+\mitem \fill`[par]'
+
+ This fills the region (non-destructively). \n\pscustom{} automatically fills
+the region as well.
+
+\mitem \gsave
+
+ This saves the current graphics state (i.e., the path, color, line width,
+coordinate system, etc.) \n\grestore{} restores the graphics state. \n\gsave{}
+and \n\grestore{} must be used in pairs, properly nested with respect to \TeX{}
+groups. You can have have nested \n\gsave-\n\grestore{} pairs.
+
+\mitem \grestore
+
+ See above.
+
+Here is an example that fixes an earlier example, using \n\gsave{} and
+\n\grestore:
+\begin{MEx}(4,3)
+ \psline{<->}(0,3)(0,0)(4,0)
+ \pscustom[linewidth=1.5pt]{
+ \psplot[plotstyle=curve]{.67}{4}{2 x div}
+ \gsave
+ \psline(4,3)
+ \fill[fillstyle=solid,fillcolor=gray]
+ \grestore}
+\end{MEx}
+Observe how the line added by "\psline(4,3)" is never stroked, because it is
+nested in "\gsave" and "\grestore".
+
+Here is another example:
+\begin{MEx*}(4,3)
+ \pscustom[linewidth=1.5pt]{
+ \pscurve(0,2)(1,2.5)(2,1.5)(4,3)
+ \gsave
+ \pscurve[liftpen=1](4,1)(3,0.5)(2,1)(1,0)(0,.5)
+ \fill[fillstyle=solid,fillcolor=gray]
+ \grestore}
+ \pscurve[linewidth=1.5pt](4,1)(3,0.5)(2,1)(1,0)(0,.5)
+\end{MEx*}
+Note how I had to repeat the second \n\pscurve{} (I could have repeated it
+within \n\pscustom, with \p{liftpen=2}), because I wanted to draw a line
+between the two curves to enclose the region but I didn't want this line to be
+stroked.
+\end{description}
+
+The next set of commands modify the coordinate system.
+\begin{description}
+
+\mitem \translate(coor)
+
+ Translate coordinate system by \c{}. This shifts everything that comes later
+by \c{}, but doesn't affect what has already been drawn.
+
+\mitem \scale{num1 `num2'}
+
+ Scale the coordinate system in both directions by <num1>, or horizontally by
+<num1> and vertically by <num2>.
+
+\mitem \rotate{angle}
+
+ Rotate the coordinate system by <angle>.
+
+\mitem \swapaxes
+
+ Switch the x and y coordinates. This is equivalent to
+\begin{LVerb}
+ \rotate{-90}
+ \scale{-1 1 scale}
+\end{LVerb}
+
+\mitem \msave
+
+ Save the current coordinate system. You can then restore it with
+\n\mrestore. You can have nested \n\msave-\n\mrestore{} pairs. \n\msave{} and
+\n\mrestore{} do not have to be properly nested with respect to \TeX{} groups or
+\n\gsave{} and \n\grestore. However, remember that \n\gsave{} and \n\grestore
+also affect the coordinate system. \n\msave-\n\mrestore{} lets you change the
+coordinate system while drawing part of a path, and then restore the old
+coordinate system without destroying the path. \n\gsave-\n\grestore, on the
+other hand, affect the path and all other componments of the graphics state.
+
+\mitem \mrestore
+
+ See above.
+\end{description}
+
+And now here are a few shadow tricks:
+\begin{description}
+\mitem \openshadow`[par]'
+
+Strokes a replica of the current path, using the various shadow parameters.
+
+\mitem \closedshadow`[par]'
+
+Makes a shadow of the region enclosed by the current path as if it were opaque
+regions.
+
+\mitem \movepath(coor)
+
+Moves the path by \c{}. Use \n\gsave-\n\grestore{} if you don't want to lose
+the original path.
+\end{description}
+
+\Section{Pretty safe tricks}
+
+The next group of commands are safe, \emph{as long as there is a current
+point}!
+
+\begin{description}
+\mitem \lineto(coor)
+
+ This is a quick version of "\psline(<coor>)".
+
+\mitem \rlineto(coor)
+
+ This is like \n\lineto, but \c{} is interpreted relative to the current
+point.
+
+\mitem \curveto\c1\c2\c3
+
+ This is a quick version of "\psbezier"\c1\c2\c3.
+
+\mitem \rcurveto\c1\c2\c3
+
+ This is like \n\curveto, but \c1, \c2 and \c3 are interpreted relative to
+the current point.
+\end{description}
+
+\Section{For hackers only}
+
+For PostScript hackers, there are a few more commands. Be sure to read
+Appendix \ref{S-raw} before using these. Needless to say:
+\begin{Warning}
+Misuse of the commands in this section can cause PostScript errors.
+\end{Warning}
+
+ The PostScript environment in effect with \n\pscustom{} has one unit equal to
+one \TeX{} "pt".
+
+\begin{description}
+
+\mitem \code{code}
+ Insert the raw PostScript code.
+
+\mitem \dim{dim}
+
+ Convert the PSTricks dimension to the number of "pt"'s, and inserts it in
+the PostScript code.
+
+\mitem \coor\c1`\c2...\cn'
+
+Convert one or more PSTricks coordinates to a pair of numbers (using "pt"
+units), and insert them in the PostScript code.
+
+\mitem \rcoor\c1`\c2...\cn'
+
+Like \n\coor, but insert the coordinates in reverse order.
+
+\mitem \file{file}
+
+ This is like \n\code, but the raw PostScript is copied verbatim (except
+comments delimited by "%") from <file>.
+
+\mitem \arrows{arrows}
+
+ This defines the PostScript operators "ArrowA" and "ArrowB" so that
+\begin{LVerb}
+ x2 y2 x1 y1 ArrowA
+ x2 y2 x1 y1 ArrowB
+\end{LVerb}
+each draws an arrow(head) with the tip at \c1 and pointing from \c2. "ArrowA"
+leaves the current point at end of the arrowhead, where a connect line should
+start, and leaves \c2 on the stack. "ArrowB" does not change the current
+point, but leaves
+\begin{LVerb}
+ x2 y2 x1' y1'
+\end{LVerb}
+on the stack, where \c{1'} is the point where a connecting line should join.
+To give an idea of how this work, the following is roughly how PSTricks draws
+a bezier curve with arrows at the end:
+\begin{MEx*}(4,3)
+ \pscustom{
+ \arrows{|->}
+ \code{
+ 80 140 5 5 ArrowA
+ 30 -30 110 75 ArrowB
+ curveto}}
+\end{MEx*}
+
+\mitem \setcolor{color}
+
+ Set the color to <color>.
+
+\end{description}
+
+\endinput
+
+%% END psd-cust.tex