summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-01-05 22:40:38 +0000
committerKarl Berry <karl@freefriends.org>2019-01-05 22:40:38 +0000
commit22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch)
tree2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex
parentcf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff)
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex238
1 files changed, 114 insertions, 124 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex
index 6837464fccd..a8f85fb4cf3 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex
@@ -9,96 +9,90 @@
\section{Patterns}
-
\label{section-patterns}
\subsection{Overview}
-There are many ways of filling a path. First, you can fill it using a
-solid color and this is also the fastest method. Second, you can also
-fill it using a shading, which means that the color changes smoothly
-between two (or more) different colors. Third, you can fill it using a
-tiling pattern and it is explained in the following how this is done.
+There are many ways of filling a path. First, you can fill it using a solid
+color and this is also the fastest method. Second, you can also fill it using a
+shading, which means that the color changes smoothly between two (or more)
+different colors. Third, you can fill it using a tiling pattern and it is
+explained in the following how this is done.
-A tiling pattern can be imagined as a rectangular tile (hence the
-name) on which a small picture is painted. There is not a single tile,
-but (conceptually) an infinite number of tiles, all showing the same
-picture, and these tiles are arranged horizontally and vertically to
-fill the plane. When you use a tiling pattern to fill a path, what
-happens is that the path clips out a ``window'' through which we see
-part of this infinite plane.
+A tiling pattern can be imagined as a rectangular tile (hence the name) on
+which a small picture is painted. There is not a single tile, but
+(conceptually) an infinite number of tiles, all showing the same picture, and
+these tiles are arranged horizontally and vertically to fill the plane. When
+you use a tiling pattern to fill a path, what happens is that the path clips
+out a ``window'' through which we see part of this infinite plane.
Patterns come in two versions: \emph{inherently colored patterns} and
-\emph{form-only patterns}. (These are often called ``color patterns''
-and ``uncolored patterns,'' but these names are misleading since
-uncolored patterns do have a color and the color changes. As I said,
-the name is misleading\dots) An inherently colored pattern is just a
-colored tile like, say, a red star with a black outline. A form-only
-pattern can be imagined as a tile that is a kind of rubber stamp. When
-this pattern is used, the stamp is used to print copies of the stamp
-picture onto the plane, but we can use a different stamp color each
-time we use a form-only pattern.
-
-\pgfname\ provides a special support for patterns. You can declare a
-pattern and then use it very much like a fill color. \pgfname\
-directly maps patterns to the pattern facilities of the underlying
-graphic languages (PostScript, \textsc{pdf}, and \textsc{svg}). This
-means that filling a path using a pattern will be nearly as fast as if
-you used a uniform color.
-
-There are a number of pitfalls and restrictions when using
-patterns. First, once a pattern has been declared, you cannot change
-it anymore. In particular, it is not possible to enlarge it or change
-the line width. Such flexibility would require that the repeating of
-the pattern were not done by the graphic language, but on the
-\pgfname\ level. This would make patterns orders of magnitude slower
-to produce and to render. However, \pgfname{} does provide a
-more-or-less successful emulation of ``mutable'' patterns, although
-internally, a new (fixed) instance of a pattern is declared when
-the parameters of a pattern change.
-
-Second, the phase of patterns is not well-defined, that is, it is not
-clear where the origin of the ``first'' tile is. To be more precise,
-PostScript and \textsc{pdf} on the one hand and \textsc{svg} on the
-other hand define the origin differently. PostScript and \textsc{pdf}
-define a fixed origin that is independent of where the path lies. This
-has the highly desirable effect that if you use the same pattern to
-fill multiple paths, the outcome is the same as if you had filled a single path consisting of the union of all these paths. By
-comparison, \textsc{svg} uses the upper-left (?) corner of the path to
-be filled as the origin. However, the \textsc{svg} specification is a
-bit vague on this question.
+\emph{form-only patterns}. (These are often called ``color patterns'' and
+``uncolored patterns'', but these names are misleading since uncolored patterns
+do have a color and the color changes. As I said, the name is misleading\dots)
+An inherently colored pattern is just a colored tile like, say, a red star with
+a black outline. A form-only pattern can be imagined as a tile that is a kind
+of rubber stamp. When this pattern is used, the stamp is used to print copies
+of the stamp picture onto the plane, but we can use a different stamp color
+each time we use a form-only pattern.
+
+\pgfname\ provides a special support for patterns. You can declare a pattern
+and then use it very much like a fill color. \pgfname\ directly maps patterns
+to the pattern facilities of the underlying graphic languages (PostScript,
+\textsc{pdf}, and \textsc{svg}). This means that filling a path using a pattern
+will be nearly as fast as if you used a uniform color.
+
+There are a number of pitfalls and restrictions when using patterns. First,
+once a pattern has been declared, you cannot change it anymore. In particular,
+it is not possible to enlarge it or change the line width. Such flexibility
+would require that the repeating of the pattern were not done by the graphic
+language, but on the \pgfname\ level. This would make patterns orders of
+magnitude slower to produce and to render. However, \pgfname{} does provide a
+more-or-less successful emulation of ``mutable'' patterns, although internally,
+a new (fixed) instance of a pattern is declared when the parameters of a
+pattern change.
+
+Second, the phase of patterns is not well-defined, that is, it is not clear
+where the origin of the ``first'' tile is. To be more precise, PostScript and
+\textsc{pdf} on the one hand and \textsc{svg} on the other hand define the
+origin differently. PostScript and \textsc{pdf} define a fixed origin that is
+independent of where the path lies. This has the highly desirable effect that
+if you use the same pattern to fill multiple paths, the outcome is the same as
+if you had filled a single path consisting of the union of all these paths. By
+comparison, \textsc{svg} uses the upper-left (?) corner of the path to be
+filled as the origin. However, the \textsc{svg} specification is a bit vague on
+this question.
\subsection{Declaring a Pattern}
-Before a pattern can be used, it must be declared. The following
-command is used for this:
+Before a pattern can be used, it must be declared. The following command is
+used for this:
\begin{command}{\pgfdeclarepatternformonly%
- \opt{\oarg{variables}}%
- \marg{name}%
- \marg{bottom left}%
- \marg{top right}%
- \marg{tile size}%
- \marg{code}}
-
- This command declares a new form-only pattern. The \meta{name} is a
- name for later reference. The two parameters \meta{lower left} and
- \meta{upper right} must describe a bounding box that is large enough
- to encompass the complete tile.
-
- The size of a tile is given by \meta{tile size}, that is, a tile is
- a rectangle whose lower left corner is the origin and whose upper
- right corner is given by \meta{tile size}. This might make you
- wonder why the second and third parameters are needed. First, the
- bounding box might be smaller than the tile size if the tile is
- larger than the picture on the tile. Second, the bounding box might
- be bigger, in which case the picture will ``bleed'' over the tile.
-
- The \meta{code} should be \pgfname\ code than can be protocolled. It
- should not contain any color code.
-
-
+ \opt{\oarg{variables}}%
+ \marg{name}%
+ \marg{bottom left}%
+ \marg{top right}%
+ \marg{tile size}%
+ \marg{code}%
+}
+ This command declares a new form-only pattern. The \meta{name} is a name
+ for later reference. The two parameters \meta{lower left} and \meta{upper
+ right} must describe a bounding box that is large enough to encompass the
+ complete tile.
+
+ The size of a tile is given by \meta{tile size}, that is, a tile is a
+ rectangle whose lower left corner is the origin and whose upper right
+ corner is given by \meta{tile size}. This might make you wonder why the
+ second and third parameters are needed. First, the bounding box might be
+ smaller than the tile size if the tile is larger than the picture on the
+ tile. Second, the bounding box might be bigger, in which case the picture
+ will ``bleed'' over the tile.
+
+ The \meta{code} should be \pgfname\ code than can be protocolled. It should
+ not contain any color code.
+ %
\begin{codeexample}[]
\pgfdeclarepatternformonly{stars}
{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
@@ -120,37 +114,33 @@ command is used for this:
\end{tikzpicture}
\end{codeexample}
- The optional argument \meta{variables} consists of a comma
- separated list of macros, registers or keys, representing the
- parameters of the pattern that may vary. If a variable is a key,
- then the full path name must be used (specifically, it must start
- with |/|).
- As an example, a list might look like the following:
- |\mymacro,\mydimen,/pgf/my key|. Note that macros and keys should
- be ``simple''. They should only store values in themselves.
-
- The effect of \meta{variables}, is the following:
- Normally, when this argument is empty, once a pattern has been
- declared, it becomes ``frozen''. This means that it is not possible
- to enlarge the pattern or change the line width later on.
- By specifying \meta{variables}, no pattern is actually created.
- Instead, the arguments are stored away
- (so the macros, registers or keys do not have to be defined in advance).
-
- When the fill pattern is set, \pgfname{} checks if the pattern has
- already been created with the \meta{variables} set to their current
- values (\pgfname{} is usually ``smart enough'' to distinguish between
- macros, registers and keys). If so, this already-declared-pattern
- is used as the fill pattern.
- If not, a new instance of the pattern (which will have a
- unique internal name) is declared using the current values of
- \meta{variables}. These values are then saved and the fill pattern
- set accordingly.
-
- The following shows an example of a pattern which varies
- according to the values of the macro |\size|, the key |/tikz/radius|,
- and the \TeX{} dimension |\thickness|.
-
+ The optional argument \meta{variables} consists of a comma separated list
+ of macros, registers or keys, representing the parameters of the pattern
+ that may vary. If a variable is a key, then the full path name must be used
+ (specifically, it must start with |/|). As an example, a list might look
+ like the following: |\mymacro,\mydimen,/pgf/my key|. Note that macros and
+ keys should be ``simple''. They should only store values in themselves.
+
+ The effect of \meta{variables}, is the following: Normally, when this
+ argument is empty, once a pattern has been declared, it becomes ``frozen''.
+ This means that it is not possible to enlarge the pattern or change the
+ line width later on. By specifying \meta{variables}, no pattern is actually
+ created. Instead, the arguments are stored away (so the macros, registers
+ or keys do not have to be defined in advance).
+
+ When the fill pattern is set, \pgfname{} checks if the pattern has already
+ been created with the \meta{variables} set to their current values
+ (\pgfname{} is usually ``smart enough'' to distinguish between macros,
+ registers and keys). If so, this already-declared-pattern is used as the
+ fill pattern. If not, a new instance of the pattern (which will have a
+ unique internal name) is declared using the current values of
+ \meta{variables}. These values are then saved and the fill pattern set
+ accordingly.
+
+ The following shows an example of a pattern which varies according to the
+ values of the macro |\size|, the key |/tikz/radius|, and the \TeX{}
+ dimension |\thickness|.
+ %
\begin{codeexample}[]
\pgfdeclarepatternformonly[/tikz/radius,\thickness,\size]{rings}
{\pgfpoint{-0.5*\size}{-0.5*\size}}
@@ -175,21 +165,22 @@ command is used for this:
\filldraw [rings, radius=8pt, thickness=4pt] (2,2.5) rectangle +(1.5,2);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
-
\begin{command}{\pgfdeclarepatterninherentlycolored
- \opt{\oarg{variables}}
+ \opt{\oarg{variables}}
\marg{name}
\marg{lower left}
\marg{upper right}
\marg{tile size}
- \marg{code}}
- This command works like |\pgfdeclarepatternuncolored|, only the
- pattern will have an inherent color. To set the color, you should
- use \pgfname's color commands, not the |\color| command, since this
- fill is not protocolled.
-
+ \marg{code}%
+}
+ This command works like |\pgfdeclarepatternuncolored|, only the pattern
+ will have an inherent color. To set the color, you should use \pgfname's
+ color commands, not the |\color| command, since this fill is not
+ protocolled.
+ %
\begin{codeexample}[]
\pgfdeclarepatterninherentlycolored{green stars}
{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
@@ -209,21 +200,20 @@ command is used for this:
\filldraw[pattern=green stars] (0,0) rectangle (3,2);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
-
-
\subsection{Setting a Pattern}
Once a pattern has been declared, it can be used.
\begin{command}{\pgfsetfillpattern\marg{name}\marg{color}}
- This command specifies that paths that are filled should be filled
- with the ``color'' by the pattern \meta{name}. For an inherently
- colored pattern, the \meta{color} parameter is ignored. For
- form-only patterns, the \meta{color} parameter specifies the color
- to be used for the pattern.
+ This command specifies that paths that are filled should be filled with the
+ ``color'' by the pattern \meta{name}. For an inherently colored pattern,
+ the \meta{color} parameter is ignored. For form-only patterns, the
+ \meta{color} parameter specifies the color to be used for the pattern.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\pgfsetfillpattern{stars}{red}
@@ -233,10 +223,10 @@ Once a pattern has been declared, it can be used.
\filldraw (1.5,0) rectangle (3,2);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
-
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"