summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex152
1 files changed, 146 insertions, 6 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
index 74b555a40e9..c3af156d25a 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
@@ -8,7 +8,7 @@
% See the file doc/generic/pgf/licenses/LICENSE for more details.
-\section{Declaring and Using Shadings}
+\section{Shadings}
\label{section-shadings}
@@ -20,11 +20,11 @@ it can be used. Also similarly to an image, a shading is put into a
\TeX-box. Hence, in order to include a shading in a |{pgfpicture}|,
you have to use |\pgftext| around it.
-There are three kinds of shadings: horizontal, vertical, and radial
-shadings. However, you can rotate and clip shadings like any other
-graphics object, which allows you to create more complicated
-shadings. Horizontal shadings could be created by rotating a vertical
-shading by 90 degrees, but explicit commands for creating both
+There are different kinds of shadings: horizontal, vertical, radial,
+and functional shadings. However, you can rotate and clip shadings
+like any other graphics object, which allows you to create more
+complicated shadings. Horizontal shadings could be created by rotating
+a vertical shading by 90 degrees, but explicit commands for creating both
horizontal and vertical shadings are included for convenience.
Once you have declared a shading, you can insert it into text using
@@ -55,8 +55,11 @@ be separated using a semicolon, which may be followed by a whitespace
(like a space or a newline). Individual specifications must be given
in increasing order.
+
\subsection{Declaring Shadings}
+\subsubsection{Horizontal and Vertical Shadings}
+
\begin{command}{\pgfdeclarehorizontalshading\oarg{color list}\marg{shading
name}\marg{shading height}\marg{color specification}}
Declares a horizontal shading named \meta{shading name} of the specified
@@ -120,6 +123,8 @@ in increasing order.
\end{command}
+\subsubsection{Radial Shadings}
+
\begin{command}{\pgfdeclareradialshading\oarg{color list}\marg{shading
name}\marg{center point}\marg{color specification}}
Declares an radial shading. A radial shading is a circle whose inner
@@ -145,6 +150,141 @@ in increasing order.
\end{command}
+\subsubsection{General (Functional) Shadings}
+
+\begin{command}{\pgfdeclarefunctionalshading\oarg{color list}\marg{shading
+ name}\marg{lower left corner}\marg{upper right corner}\\
+ \marg{init code}\marg{type 4 function}}
+ \emph{Warning: These shadings are the least portable of all and they
+ put the heaviest burden of the renderer. They are slow and,
+ possibly, will not print correctly!}
+
+ This command creates a \emph{functional shading}. For such a
+ shading, the color of each point is calculated by calling a function
+ that gets the coordinates of the point as input and yields the
+ color as an output. Note that the function is evaluated by the
+ \emph{renderer}, not by \pgfname\ or \TeX or someone else at
+ compile-time. This means that the evaluation of this function has to
+ be done \emph{extremely quickly} and the funciton should be
+ \emph{very simple}. For this reason, only a very restricted set of
+ operations are possible in the function and functions should be
+ kept small. Any errors in the function will only be noticed by the
+ renderer.
+
+ The syntax for specifying functions is the following: You use a
+ simplified form of a subset of the PostScript language. This subset
+ will be understood by the PDF-renderer (yes, PDF-renderers do
+ have a basic understanding of PostScript) and also by PostScript
+ renders. This subset is detailed in Seciton 3.9.4 of the
+ PDF-specification (version 1.7). In essence, the specificaiton
+ states that these functions may contain ``expressions involving
+ integers, real numbers, and boolean values only. There are no
+ composite data structures such as strings or arrays, no procedures,
+ and no variables or names.'' The allowed operators are (exactly) the
+ following: \texttt{abs}, \texttt{add}, \texttt{atan},
+ \texttt{ceiling}, \texttt{cos}, \texttt{cvi}, \texttt{cvr},
+ \texttt{div}, \texttt{exp}, \texttt{floor}, \texttt{idiv},
+ \texttt{ln}, \texttt{log}, \texttt{mod}, \texttt{mul}, \texttt{neg},
+ \texttt{round}, \texttt{sin}, \texttt{sqrt}, \texttt{sub},
+ \texttt{truncate}, \texttt{and}, \texttt{bitshift}, \texttt{eq},
+ \texttt{false}, \texttt{ge}, \texttt{gt}, \texttt{le}, \texttt{lt},
+ \texttt{ne}, \texttt{not}, \texttt{or}, \texttt{true}, \texttt{xor},
+ \texttt{if}, \texttt{ifelse}, \texttt{copy}, \texttt{dup},
+ \texttt{exch}, \texttt{index}, \texttt{pop}.
+
+ When the function is evaluated, the top two stack elements are the
+ coordinates of the point for which the color should be computed. The
+ coordinates are dimensionless and given in big points, so for the
+ coordinate $(50bp, 72.27pt)$ the top two stack elements would be
+ \texttt{50.0} and \texttt{72.0}. Ohterwise, the (virtual) stack is
+ empty (or should be treated as if it were empty). The function
+ should then replace these two values by three values, representing
+ the red, green, and blue color of the point. The numbers should be
+ real values, not integers since Apple's PDF renderer is broken in
+ this regard (use cvr at the end if necessary).
+
+ Conceptually, the function will be evaluated once for each point of
+ the rectangle \meta{lower left corner} to \meta{upper right corner},
+ which should be a \pgfname-point expression like
+ |\pgfpoint{100bp}{100bp}|. A renderer may choose to evaluate the
+ function at less points, but, in principle, the function will be
+ evaluated for each pixel independently.
+
+ Because of the rather difficult PostScript syntax, use this macro
+ only \emph{if you know what you are doing} (or if you are
+ advanterous, of course).
+
+ As for other shadings, the optional \meta{color list} is used to
+ determine whether a shading needs to be recalculated when a color
+ has changed.
+
+ The \meta{init code} is executed each time a shading is
+ (re)calculated. Typically, it will contain code to extract
+ coordinates from colors (see below).
+
+ Inside the PostScript function \meta{type 4 function} you cannot use
+ colors directly. Rather, you must push the color components on the
+ stack. For this, it is useful to call |\pgfshadecolorrgb| in the
+ \meta{init code}. The macro takes a color name as input and stores
+ the color's red/green/blue components real numbers between 0.0 and
+ 1.0 separated by spaces (which is exactly what you need if you want
+ to push it on a stack) in a macro. You can then use this macro in
+ the argument \meta{type 4 function}.
+
+\begin{codeexample}[]
+\pgfdeclarefunctionalshading{twospots}
+ {\pgfpointorigin}{\pgfpoint{4cm}{4cm}}{}{
+ % Save coordinates for later
+ 2 copy
+ % Compute distance from (40bp,45bp), with x doubled
+ 45 sub dup mul exch
+ 40 sub dup mul 0.5 mul add sqrt
+ % expontial decay
+ dup mul neg 1.0005 exch exp 1.0 exch sub
+ % Compute distance form (70bp,70bp) from stored coordiante, scaled
+ 3 1 roll
+ 70 sub dup mul .5 mul exch
+ 70 sub dup mul add sqrt
+ % Decay
+ dup mul neg 1.002 exch exp 1.0 exch sub
+ % red component
+ 1.0 3 1 roll
+}
+\pgfuseshading{twospots}
+\end{codeexample}
+
+\begin{codeexample}[]
+\pgfdeclarefunctionalshading[mycol]{sweep}{\pgfpoint{-1cm}{-1cm}}
+{\pgfpoint{1cm}{1cm}}{\pgfshadecolortorgb{mycol}{\myrgb}}{
+ 2 copy % whirl
+ atan
+ 3 1 roll
+ dup mul exch
+ dup mul add sqrt
+ 30 mul
+ add
+ sin
+ 1 add 2 div
+ dup
+ \myrgb % push mycol
+ 5 4 roll % multiply all components by calculated value
+ mul
+ 3 1 roll
+ 3 index
+ mul
+ 3 1 roll
+ 4 3 roll
+ mul
+ 3 1 roll
+}
+\colorlet{mycol}{white}%
+\pgfuseshading{sweep}%
+\colorlet{mycol}{red}%
+\pgfuseshading{sweep}
+\end{codeexample}
+\end{command}
+
+
\subsection{Using Shadings}
\label{section-shading-a-path}