diff options
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.tex | 152 |
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} |