| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Shadings} |
| 12 |
\label{section-shadings} |
| 13 |
|
| 14 |
\subsection{Overview} |
| 15 |
|
| 16 |
A shading is an area in which the color changes smoothly between different |
| 17 |
colors. Similarly to an image, a shading must first be declared before it can |
| 18 |
be used. Also similarly to an image, a shading is put into a \TeX-box. Hence, |
| 19 |
in order to include a shading in a |{pgfpicture}|, you have to use |\pgftext| |
| 20 |
around it. |
| 21 |
|
| 22 |
There are different kinds of shadings: horizontal, vertical, radial, and |
| 23 |
functional shadings. However, you can rotate and clip shadings like any other |
| 24 |
graphics object, which allows you to create more complicated shadings. |
| 25 |
Horizontal shadings could be created by rotating a vertical shading by 90 |
| 26 |
degrees, but explicit commands for creating both horizontal and vertical |
| 27 |
shadings are included for convenience. |
| 28 |
|
| 29 |
Once you have declared a shading, you can insert it into the text using the |
| 30 |
command |\pgfuseshading|. This command cannot be used directly in a |
| 31 |
|{pgfpicture}|, you have to put a |\pgftext| around it. The second command for |
| 32 |
using shadings, |\pgfshadepath|, on the other hand, can only be used inside |
| 33 |
|{pgfpicture}| environments. It will ``fill'' the current path with the |
| 34 |
shading. |
| 35 |
|
| 36 |
A horizontal shading is a horizontal bar of a certain height whose color |
| 37 |
changes smoothly. You must at least specify the colors at the left and at the |
| 38 |
right end of the bar, but you can also add color specifications for points in |
| 39 |
between. For example, suppose you wish to create a bar that is red at the left |
| 40 |
end, green in the middle, and blue at the end, and you would like the bar to be |
| 41 |
4cm long. This could be specified as follows: |
| 42 |
% |
| 43 |
\begin{codeexample}[code only] |
| 44 |
rgb(0cm)=(1,0,0); rgb(2cm)=(0,1,0); rgb(4cm)=(0,0,1) |
| 45 |
\end{codeexample} |
| 46 |
% |
| 47 |
This line means that at 0cm (the left end) of the bar, the color should be red, |
| 48 |
which has red-green-blue (rgb) components (1,0,0). At 2cm, the bar should be |
| 49 |
green, and at 4cm it should be blue. Instead of |rgb|, you can currently also |
| 50 |
specify |cmyk| as color model, in which case four values are needed, |
| 51 |
|gray| as color model, in which case only one value is needed, or |
| 52 |
|color|, in which case you must provide the name of a color in parentheses. In |
| 53 |
a color specification the individual specifications must be separated using a |
| 54 |
semicolon, which may be followed by a whitespace (like a space or a newline). |
| 55 |
Individual specifications must be given in increasing order. |
| 56 |
|
| 57 |
\subsubsection{Color models} |
| 58 |
|
| 59 |
\noindent\emph{by David Purton} |
| 60 |
|
| 61 |
An attempt is made to produce shadings consistent with the currently selected |
| 62 |
|xcolor| package color model. The |rgb|, |cmyk|, and |gray| color models from |
| 63 |
the |xcolor| package are supported. |
| 64 |
|
| 65 |
\textbf{Note:} The color model chosen for a shading is based on the |xcolor| |
| 66 |
color model \emph{at the time the shading is created}. This is either when |
| 67 |
|\pgfdeclare*shading| is called with no optional argument or when |
| 68 |
|\pgfuseshading| is called if |\pgfdeclare*shading| was called with an |
| 69 |
optional argument. |
| 70 |
|
| 71 |
If the |xcolor| package |natural| color model is in use then the shading color |
| 72 |
model will be \textsc{rgb} by default. In practice this means that if you are |
| 73 |
using the |natural| color model of the |xcolor| package you can get mismatched |
| 74 |
colors if you, for example, create a shading from green (which is defined as |
| 75 |
\textsc{rgb}) to magenta (which is defined as \textsc{cmyk}). The shading will |
| 76 |
finish with \textsc{rgb} magenta which will look different to the |
| 77 |
\textsc{cmyk} magenta used in solid colors. |
| 78 |
|
| 79 |
You can avoid mismatched colors by loading the |xcolor| package first with an |
| 80 |
explicit color model (|rgb|, |cmyk|, or |gray|). |
| 81 |
|
| 82 |
\begin{codeexample}[code only] |
| 83 |
\begin{tikzpicture} |
| 84 |
\fill[green] (0,0) rectangle (1,1); |
| 85 |
\shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1); |
| 86 |
\fill[magenta] (4,0) rectangle (5,1); |
| 87 |
\end{tikzpicture} |
| 88 |
\end{codeexample} |
| 89 |
|
| 90 |
\begin{center} |
| 91 |
\begin{minipage}{5cm} |
| 92 |
|xcolor| |natural| color model:\medskip |
| 93 |
|
| 94 |
\begin{tikzpicture} |
| 95 |
\fill[green] (0,0) rectangle (1,1); |
| 96 |
\shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1); |
| 97 |
\fill[magenta] (4,0) rectangle (5,1); |
| 98 |
\end{tikzpicture} |
| 99 |
\end{minipage}\hspace{2cm}% |
| 100 |
\begin{minipage}{5cm} |
| 101 |
|xcolor| |cmyk| color model:\medskip |
| 102 |
|
| 103 |
\selectcolormodel{cmyk} |
| 104 |
\begin{tikzpicture} |
| 105 |
\fill[green] (0,0) rectangle (1,1); |
| 106 |
\shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1); |
| 107 |
\fill[magenta] (4,0) rectangle (5,1); |
| 108 |
\end{tikzpicture} |
| 109 |
\end{minipage}\medskip |
| 110 |
|
| 111 |
\begin{minipage}{5cm} |
| 112 |
|xcolor| |rgb| color model:\medskip |
| 113 |
|
| 114 |
\selectcolormodel{rgb} |
| 115 |
\begin{tikzpicture} |
| 116 |
\fill[green] (0,0) rectangle (1,1); |
| 117 |
\shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1); |
| 118 |
\fill[magenta] (4,0) rectangle (5,1); |
| 119 |
\end{tikzpicture} |
| 120 |
\end{minipage}\hspace{2cm}% |
| 121 |
\begin{minipage}{5cm} |
| 122 |
|xcolor| |gray| color model:\medskip |
| 123 |
|
| 124 |
\selectcolormodel{gray} |
| 125 |
\begin{tikzpicture} |
| 126 |
\fill[green] (0,0) rectangle (1,1); |
| 127 |
\shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1); |
| 128 |
\fill[magenta] (4,0) rectangle (5,1); |
| 129 |
\end{tikzpicture} |
| 130 |
\end{minipage} |
| 131 |
\end{center} |
| 132 |
|
| 133 |
\subsection{Declaring Shadings} |
| 134 |
|
| 135 |
\subsubsection{Horizontal and Vertical Shadings} |
| 136 |
|
| 137 |
\begin{command}{\pgfdeclarehorizontalshading\oarg{color list}\marg{shading name}\marg{shading height}\marg{color specification}} |
| 138 |
Declares a horizontal shading named \meta{shading name} of the specified |
| 139 |
\meta{height} with the specified colors. The width of the bar is deduced |
| 140 |
automatically from the maximum dimension in the specification. |
| 141 |
% |
| 142 |
\begin{codeexample}[] |
| 143 |
\pgfdeclarehorizontalshading{myshadingA} |
| 144 |
{1cm}{rgb(0cm)=(1,0,0); color(2cm)=(green); color(4cm)=(blue)} |
| 145 |
\pgfuseshading{myshadingA} |
| 146 |
\end{codeexample} |
| 147 |
|
| 148 |
The effect of the \meta{color list}, which is a comma-separated list of |
| 149 |
colors, is the following: Normally, when this list is empty, once a shading |
| 150 |
has been declared, it becomes ``frozen''. This means that even if you |
| 151 |
change a color that was used in the declaration of the shading later on, |
| 152 |
the shading will not change. By specifying a \meta{color list} you can |
| 153 |
specify that the shading should be recalculated whenever one of the colors |
| 154 |
listed in the list changes (this includes effects like color mixins and |
| 155 |
|xcolor| color models). Thus, when you specify a \meta{color list}, |
| 156 |
whenever the shading is used, \pgfname\ first converts the colors in the |
| 157 |
list to tuples in the current |xcolor| color model using the current |
| 158 |
values of the colors and taking any mixins and blends into account. If the |
| 159 |
resulting tuples have not yet been used, |
| 160 |
a new shading is internally created and used. Note that if the option |
| 161 |
\meta{color list} is used, then no shading is created until the first use |
| 162 |
of |\pgfuseshading|. In particular, the colors mentioned in the shading |
| 163 |
need not be defined when the declaration is given. |
| 164 |
|
| 165 |
When a shading is recalculated because of a change in the colors mentioned |
| 166 |
in \meta{color list}, the complete shading is recalculated. Thus even |
| 167 |
colors not mentioned in the list will be used with their current values, |
| 168 |
not with the values they had upon declaration. |
| 169 |
% |
| 170 |
\begin{codeexample}[] |
| 171 |
\pgfdeclarehorizontalshading[mycolor]{myshadingB} |
| 172 |
{1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)} |
| 173 |
\colorlet{mycolor}{green} |
| 174 |
\pgfuseshading{myshadingB} |
| 175 |
\colorlet{mycolor}{blue} |
| 176 |
\pgfuseshading{myshadingB} |
| 177 |
\end{codeexample} |
| 178 |
% |
| 179 |
\end{command} |
| 180 |
|
| 181 |
\begin{command}{\pgfdeclareverticalshading\oarg{color list}\marg{shading name}\marg{shading width}\marg{color specification}} |
| 182 |
Declares a vertical shading named \meta{shading name} of the specified |
| 183 |
\meta{width}. The height of the bar is deduced automatically. The effect of |
| 184 |
\meta{color list} is the same as for horizontal shadings. |
| 185 |
% |
| 186 |
\begin{codeexample}[] |
| 187 |
\pgfdeclareverticalshading{myshadingC} |
| 188 |
{4cm}{rgb(0cm)=(1,0,0); rgb(1.5cm)=(0,1,0); rgb(2cm)=(0,0,1)} |
| 189 |
\pgfuseshading{myshadingC} |
| 190 |
\end{codeexample} |
| 191 |
% |
| 192 |
\end{command} |
| 193 |
|
| 194 |
|
| 195 |
\subsubsection{Radial Shadings} |
| 196 |
|
| 197 |
\begin{command}{\pgfdeclareradialshading\oarg{color list}\marg{shading name}\marg{center point}\marg{color specification}} |
| 198 |
Declares a radial shading. A radial shading is a circle whose inner color |
| 199 |
changes as specified by the color specification. Assuming that the center |
| 200 |
of the shading is at the origin, the color of the center will be the color |
| 201 |
specified for 0cm and the color of the border of the circle will be the |
| 202 |
color for the maximum dimension given in the \meta{color specified}. This |
| 203 |
maximum will also be the radius of the circle. If the \meta{center point} |
| 204 |
is not at the origin, the whole shading inside the circle (whose size |
| 205 |
remains exactly the same) will be distorted such that the given center now |
| 206 |
has the color specified for 0cm. The effect of \meta{color list} is the |
| 207 |
same as for horizontal shadings. |
| 208 |
% |
| 209 |
\begin{codeexample}[] |
| 210 |
\pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}% |
| 211 |
{rgb(0cm)=(0.9,0,0); |
| 212 |
rgb(0.7cm)=(0.7,0,0); |
| 213 |
rgb(1cm)=(0.5,0,0); |
| 214 |
rgb(1.05cm)=(1,1,1)} |
| 215 |
\pgfuseshading{sphere} |
| 216 |
\end{codeexample} |
| 217 |
% |
| 218 |
\end{command} |
| 219 |
|
| 220 |
|
| 221 |
\subsubsection{General (Functional) Shadings} |
| 222 |
|
| 223 |
\begin{command}{\pgfdeclarefunctionalshading\oarg{color list}\marg{shading |
| 224 |
name}\marg{lower left corner}\marg{upper right corner}\\ |
| 225 |
\marg{init code}\marg{type 4 function}% |
| 226 |
} |
| 227 |
\emph{Warning: These shadings are the least portable of all and they put |
| 228 |
the heaviest burden of the renderer. They are slow and, possibly, will not |
| 229 |
print correctly!} |
| 230 |
|
| 231 |
This command creates a \emph{functional shading}. For such a shading, the |
| 232 |
color of each point is calculated by calling a function that takes the |
| 233 |
coordinates of the point as input and yields the color as an output. Note |
| 234 |
that the function is evaluated by the \emph{renderer}, not by \pgfname\ or |
| 235 |
\TeX\ or someone else at compile-time. This means that the evaluation of |
| 236 |
this function has to be done \emph{extremely quickly} and the function |
| 237 |
should be \emph{very simple}. For this reason, only a very restricted set |
| 238 |
of operations are possible in the function and functions should be kept |
| 239 |
small. Any errors in the function will only be noticed by the renderer. |
| 240 |
|
| 241 |
The syntax for specifying functions is the following: You use a simplified |
| 242 |
form of a subset of the PostScript language. This subset will be understood |
| 243 |
by the PDF-renderer (yes, PDF-renderers do have a basic understanding of |
| 244 |
PostScript) and also by PostScript renders. This subset is detailed in |
| 245 |
Section~3.9.4 of the PDF-specification (version~1.7). In essence, the |
| 246 |
specification states that these functions may contain ``expressions |
| 247 |
involving integers, real numbers, and boolean values only. There are no |
| 248 |
composite data structures such as strings or arrays, no procedures, and no |
| 249 |
variables or names.'' The allowed operators are (exactly) the following: |
| 250 |
\texttt{abs}, \texttt{add}, \texttt{atan}, \texttt{ceiling}, \texttt{cos}, |
| 251 |
\texttt{cvi}, \texttt{cvr}, \texttt{div}, \texttt{exp}, \texttt{floor}, |
| 252 |
\texttt{idiv}, \texttt{ln}, \texttt{log}, \texttt{mod}, \texttt{mul}, |
| 253 |
\texttt{neg}, \texttt{round}, \texttt{sin}, \texttt{sqrt}, \texttt{sub}, |
| 254 |
\texttt{truncate}, \texttt{and}, \texttt{bitshift}, \texttt{eq}, |
| 255 |
\texttt{false}, \texttt{ge}, \texttt{gt}, \texttt{le}, \texttt{lt}, |
| 256 |
\texttt{ne}, \texttt{not}, \texttt{or}, \texttt{true}, \texttt{xor}, |
| 257 |
\texttt{if}, \texttt{ifelse}, \texttt{copy}, \texttt{dup}, \texttt{exch}, |
| 258 |
\texttt{index}, \texttt{pop}, \texttt{roll}. |
| 259 |
|
| 260 |
When the function is evaluated, the top two stack elements are the |
| 261 |
coordinates of the point for which the color should be computed. The |
| 262 |
coordinates are dimensionless and given in big points, so for the |
| 263 |
coordinate $(50bp, 72.27pt)$ the top two stack elements would be |
| 264 |
\texttt{50.0} and \texttt{72.0}. Otherwise, the (virtual) stack is empty |
| 265 |
(or should be treated as if it were empty). The function should then |
| 266 |
replace these two values by three values, representing the red, green, and |
| 267 |
blue color of the point for an \textsc{rgb} shading, four colors, |
| 268 |
representing the cyan, magenta, yellow, and black color of the point for a |
| 269 |
\textsc{cmyk} shading, or one value representing the gray color for a |
| 270 |
grayscale shading. The numbers should be real values, not integers |
| 271 |
since, Apple's PDF renderer is broken in this regard (use \texttt{cvr} at |
| 272 |
the end if necessary). |
| 273 |
|
| 274 |
Conceptually, the function will be evaluated once for each point of the |
| 275 |
rectangle \meta{lower left corner} to \meta{upper right corner}, which |
| 276 |
should be a \pgfname-point expression like |\pgfpoint{100bp}{100bp}|. A |
| 277 |
renderer may choose to evaluate the function at less points, but, in |
| 278 |
principle, the function will be evaluated for each pixel independently. |
| 279 |
|
| 280 |
Because of the rather difficult PostScript syntax, use this macro only |
| 281 |
\emph{if you know what you are doing} (or if you are adventurous, of |
| 282 |
course). |
| 283 |
|
| 284 |
As for other shadings, the optional \meta{color list} is used to determine |
| 285 |
whether a shading needs to be recalculated when a color has changed. |
| 286 |
|
| 287 |
The \meta{init code} is executed each time a shading is (re)calculated. |
| 288 |
Typically, it will contain code to extract components from colors. |
| 289 |
% |
| 290 |
\begin{codeexample}[] |
| 291 |
\pgfdeclarefunctionalshading{twospots} |
| 292 |
{\pgfpointorigin}{\pgfpoint{4cm}{4cm}}{}{ |
| 293 |
% Save coordinates for later |
| 294 |
2 copy |
| 295 |
% Compute distance from (40bp,45bp), with x doubled |
| 296 |
45 sub dup mul exch |
| 297 |
40 sub dup mul 0.5 mul add sqrt |
| 298 |
% exponential decay |
| 299 |
dup mul neg 1.0005 exch exp 1.0 exch sub |
| 300 |
% Compute distance from (70bp,70bp) from stored coordinate, scaled |
| 301 |
3 1 roll |
| 302 |
70 sub dup mul .5 mul exch |
| 303 |
70 sub dup mul add sqrt |
| 304 |
% Decay |
| 305 |
dup mul neg 1.002 exch exp 1.0 exch sub |
| 306 |
% red component |
| 307 |
1.0 3 1 roll |
| 308 |
} |
| 309 |
\pgfuseshading{twospots} |
| 310 |
\end{codeexample} |
| 311 |
|
| 312 |
Inside the PostScript function \meta{type 4 function} you cannot use colors |
| 313 |
directly. Rather, you must push the color components on the stack. For |
| 314 |
this, it is useful to call one of |\pgfshadecolortorgb|, |
| 315 |
|\pgfshadecolortocmyk|, or |\pgfshadecolortogray| in the \meta{init code}: |
| 316 |
|
| 317 |
\begin{command}{\pgfshadecolortorgb\marg{color name}\marg{macro}} |
| 318 |
This command takes \meta{color name} as input, converts it to |
| 319 |
\textsc{rgb} and stores the color's |
| 320 |
red/green/blue components real numbers between 0.0 and 1.0 separated by |
| 321 |
spaces (which is exactly what you need if you want to push it on a |
| 322 |
stack) in \meta{macro}. This macro can then be used inside the |
| 323 |
\meta{type 4 function} argument for |\pgfdeclarefunctionalshading|. |
| 324 |
% |
| 325 |
\begin{codeexample}[] |
| 326 |
\pgfdeclarefunctionalshading[mycol]{sweep}{\pgfpoint{-1cm}{-1cm}} |
| 327 |
{\pgfpoint{1cm}{1cm}}{\pgfshadecolortorgb{mycol}{\myrgb}}{ |
| 328 |
2 copy % whirl |
| 329 |
% Calculate "safe" atan of position |
| 330 |
2 copy abs exch abs add 0.0001 ge { atan } { pop } ifelse |
| 331 |
3 1 roll |
| 332 |
dup mul exch |
| 333 |
dup mul add sqrt |
| 334 |
30 mul |
| 335 |
add |
| 336 |
sin |
| 337 |
1 add 2 div |
| 338 |
dup |
| 339 |
\myrgb % push mycol |
| 340 |
5 4 roll % multiply all components by calculated value |
| 341 |
mul |
| 342 |
3 1 roll |
| 343 |
3 index |
| 344 |
mul |
| 345 |
3 1 roll |
| 346 |
4 3 roll |
| 347 |
mul |
| 348 |
3 1 roll |
| 349 |
} |
| 350 |
\colorlet{mycol}{white}% |
| 351 |
\pgfuseshading{sweep}% |
| 352 |
\colorlet{mycol}{red}% |
| 353 |
\pgfuseshading{sweep} |
| 354 |
\end{codeexample} |
| 355 |
|
| 356 |
In addition, three macros suffixed with |red|, |green| and |blue| are |
| 357 |
defined, which store the individual components of \meta{color name}. |
| 358 |
These can also be used in the \meta{type 4 function} argument. |
| 359 |
% |
| 360 |
\begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}] |
| 361 |
\pgfshadecolortorgb{orange}{\mycol} |
| 362 |
|\mycol|=\mycol |\mycolred|=\mycolred |\mycolgreen|=\mycolgreen |\mycolblue|=\mycolblue |
| 363 |
\end{codeexample} |
| 364 |
\end{command} |
| 365 |
|
| 366 |
\begin{codeexample}[] |
| 367 |
\pgfdeclarefunctionalshading[col1,col2,col3,col4]{bilinear interpolation} |
| 368 |
{\pgfpointorigin}{\pgfpoint{100bp}{100bp}} |
| 369 |
{ |
| 370 |
\pgfshadecolortorgb{col1}{\first}\pgfshadecolortorgb{col2}{\second} |
| 371 |
\pgfshadecolortorgb{col3}{\third}\pgfshadecolortorgb{col4}{\fourth} |
| 372 |
}{ |
| 373 |
100 div exch 100 div 2 copy % Calculate y/100 x/100. |
| 374 |
neg 1 add exch neg 1 add % Calculate 1-y/100 1-x/100. |
| 375 |
3 1 roll 2 copy exch 5 2 roll 6 copy 6 copy % Set up stack. |
| 376 |
\firstred mul exch \secondred mul add mul % Process red component. |
| 377 |
4 1 roll |
| 378 |
\thirdred mul exch \fourthred mul add mul |
| 379 |
add |
| 380 |
13 1 roll |
| 381 |
\firstgreen mul exch \secondgreen mul add mul % Process green component. |
| 382 |
4 1 roll |
| 383 |
\thirdgreen mul exch \fourthgreen mul add mul |
| 384 |
add |
| 385 |
7 1 roll |
| 386 |
\firstblue mul exch \secondblue mul add mul % Process blue component. |
| 387 |
4 1 roll |
| 388 |
\thirdblue mul exch \fourthblue mul add mul |
| 389 |
add |
| 390 |
} |
| 391 |
|
| 392 |
\colorlet{col1}{blue} |
| 393 |
\colorlet{col2}{yellow} |
| 394 |
\colorlet{col3}{red} |
| 395 |
\colorlet{col4}{green} |
| 396 |
\pgfuseshading{bilinear interpolation} |
| 397 |
\end{codeexample} |
| 398 |
|
| 399 |
\begin{command}{\pgfshadecolortocmyk\marg{color name}\marg{macro}} |
| 400 |
This command takes \meta{color name} as input, converts it to |
| 401 |
\textsc{cmyk} and stores the color's cyan/magenta/yellow/black |
| 402 |
components real numbers between 0.0 and 1.0 separated by spaces. |
| 403 |
|
| 404 |
In addition, four macros suffixed with |cyan|, |magenta|, |yellow| and |
| 405 |
|black| are defined, which store the individual components of |
| 406 |
\meta{color name}. |
| 407 |
% |
| 408 |
\end{command} |
| 409 |
|
| 410 |
\begin{command}{\pgfshadecolortogray\marg{color name}\marg{macro}} |
| 411 |
This command takes \meta{color name} as input converts it to grayscale |
| 412 |
and stores the color's value as a real number between 0.0 and 1.0. |
| 413 |
|
| 414 |
Although it's not needed, for consistency a second macro suffixed with |
| 415 |
|gray| is also defined. |
| 416 |
% |
| 417 |
\end{command} |
| 418 |
% |
| 419 |
\end{command} |
| 420 |
|
| 421 |
\paragraph{Color model independent functional shadings.} |
| 422 |
|
| 423 |
By nature, the PostScript code used in functional shadings must output one of |
| 424 |
\textsc{rgb}, \textsc{cmyk}, or grayscale data. Therefore, |
| 425 |
|\pgfdeclarefunctionalshading| is \emph{not} portable across color models. |
| 426 |
|
| 427 |
Take particular care that the same color model is in use at declaration time |
| 428 |
and use time for functional shadings declared with an optional argument as |
| 429 |
otherwise the PostScript data will not match the declared color space and |
| 430 |
you will end up with a malformed PDF. |
| 431 |
|
| 432 |
Having said this, it \emph{is} possible to create portable functional shadings |
| 433 |
by providing conditional code to append color transformations to the |
| 434 |
PostScript data. A variety of |\pgffuncshading*to*| (e.g., |
| 435 |
|\pgffuncshadingrgbtocmyk|) macros along with |\ifpgfshadingmodel*| (e.g., |
| 436 |
|\ifpgfshadingmodelcmyk|) conditionals are provided to assist with these |
| 437 |
transformations. Obviously, this will make the PostScript code less efficient |
| 438 |
than if you work in your intended color model. |
| 439 |
|
| 440 |
\pgfdeclarefunctionalshading[black]{portabletwospots} |
| 441 |
{\pgfpointorigin}{\pgfpoint{3.5cm}{3.5cm}}{}{ |
| 442 |
2 copy |
| 443 |
45 sub dup mul exch |
| 444 |
40 sub dup mul 0.5 mul add sqrt |
| 445 |
dup mul neg 1.0005 exch exp 1.0 exch sub |
| 446 |
3 1 roll |
| 447 |
70 sub dup mul .5 mul exch |
| 448 |
70 sub dup mul add sqrt |
| 449 |
dup mul neg 1.002 exch exp 1.0 exch sub |
| 450 |
1.0 3 1 roll |
| 451 |
\ifpgfshadingmodelcmyk |
| 452 |
\pgffuncshadingrgbtocmyk |
| 453 |
\fi |
| 454 |
\ifpgfshadingmodelgray |
| 455 |
\pgffuncshadingrgbtogray |
| 456 |
\fi |
| 457 |
} |
| 458 |
\begin{center} |
| 459 |
\begin{minipage}{3.5cm} |
| 460 |
|xcolor| |rgb| model:\medskip |
| 461 |
|
| 462 |
\selectcolormodel{rgb} |
| 463 |
\pgfuseshading{portabletwospots} |
| 464 |
\end{minipage}\hspace{2cm} |
| 465 |
\begin{minipage}{3.5cm} |
| 466 |
|xcolor| |cmyk| model:\medskip |
| 467 |
|
| 468 |
\selectcolormodel{cmyk} |
| 469 |
\pgfuseshading{portabletwospots} |
| 470 |
\end{minipage}\hspace{2cm} |
| 471 |
\begin{minipage}{3.5cm} |
| 472 |
|xcolor| |gray| model:\medskip |
| 473 |
|
| 474 |
\selectcolormodel{gray} |
| 475 |
\pgfuseshading{portabletwospots} |
| 476 |
\end{minipage} |
| 477 |
\end{center} |
| 478 |
|
| 479 |
\begin{codeexample}[code only] |
| 480 |
\pgfdeclarefunctionalshading[black]{portabletwospots}{\pgfpointorigin}{\pgfpoint{3.5cm}{3.5cm}}{}{ |
| 481 |
2 copy |
| 482 |
45 sub dup mul exch |
| 483 |
40 sub dup mul 0.5 mul add sqrt |
| 484 |
dup mul neg 1.0005 exch exp 1.0 exch sub |
| 485 |
3 1 roll |
| 486 |
70 sub dup mul .5 mul exch |
| 487 |
70 sub dup mul add sqrt |
| 488 |
dup mul neg 1.002 exch exp 1.0 exch sub |
| 489 |
1.0 3 1 roll |
| 490 |
\ifpgfshadingmodelcmyk |
| 491 |
\pgffuncshadingrgbtocmyk |
| 492 |
\fi |
| 493 |
\ifpgfshadingmodelgray |
| 494 |
\pgffuncshadingrgbtogray |
| 495 |
\fi |
| 496 |
} |
| 497 |
\end{codeexample} |
| 498 |
|
| 499 |
\begin{command}{\pgffuncshadingrgbtocmyk} |
| 500 |
Within the \meta{type 4 function} argument of |
| 501 |
|\pgfdeclarefunctionalshading|, this command can be used to convert the |
| 502 |
top 3 elements on the stack from \textsc{rgb} to \textsc{cmyk}. In |
| 503 |
combination with the |\ifpgfshadingmodelcmyk| conditional this macro can |
| 504 |
be used to make functional shading declarations more portable across color |
| 505 |
models. |
| 506 |
\end{command} |
| 507 |
|
| 508 |
\begin{command}{\pgffuncshadingrgbtogray} |
| 509 |
Within the \meta{type 4 function} argument of |
| 510 |
|\pgfdeclarefunctionalshading|, this command can be used to convert the |
| 511 |
top 3 elements on the stack from \textsc{rgb} to grayscale. In combination |
| 512 |
with the |\ifpgfshadingmodelgray| conditional this macro can be used to |
| 513 |
make functional shading declarations more portable across color models. |
| 514 |
\end{command} |
| 515 |
|
| 516 |
\begin{command}{\pgffuncshadingcmyktorgb} |
| 517 |
Within the \meta{type 4 function} argument of |
| 518 |
|\pgfdeclarefunctionalshading|, this command can be used to convert the |
| 519 |
top 4 elements on the stack from \textsc{cmyk} to \textsc{rgb}. In |
| 520 |
combination with the |\ifpgfshadingmodelrgb| conditional this macro can be |
| 521 |
used to make functional shading declarations more portable across color |
| 522 |
models. |
| 523 |
\end{command} |
| 524 |
|
| 525 |
\begin{command}{\pgffuncshadingcmyktogray} |
| 526 |
Within the \meta{type 4 function} argument of |
| 527 |
|\pgfdeclarefunctionalshading|, this command can be used to convert the |
| 528 |
top 4 elements on the stack from \textsc{cmyk} to grayscale. In combination |
| 529 |
with the |\ifpgfshadingmodelgray| conditional this macro can be used to |
| 530 |
make functional shading declarations more portable across color models. |
| 531 |
\end{command} |
| 532 |
|
| 533 |
\begin{command}{\pgffuncshadinggraytorgb} |
| 534 |
Within the \meta{type 4 function} argument of |
| 535 |
|\pgfdeclarefunctionalshading|, this command can be used to convert the |
| 536 |
top element on the stack from grayscale to \textsc{rgb}. In combination with |
| 537 |
the |\ifpgfshadingmodelrgb| conditional this macro can be used to make |
| 538 |
functional shading declarations more portable across color models. |
| 539 |
\end{command} |
| 540 |
|
| 541 |
\begin{command}{\pgffuncshadinggraytocmyk} |
| 542 |
Within the \meta{type 4 function} argument of |
| 543 |
|\pgfdeclarefunctionalshading|, this command can be used to convert the |
| 544 |
top element on the stack from grayscale to \textsc{cmyk}. In combination |
| 545 |
with the |\ifpgfshadingmodelcmyk| conditional this macro can be used to |
| 546 |
make functional shading declarations more portable across color models. |
| 547 |
\end{command} |
| 548 |
|
| 549 |
{\let\ifpgfshadingmodelrgb=\relax |
| 550 |
\let\ifpgfshadingmodelcmyk=\relax |
| 551 |
\let\ifpgfshadingmodelgray=\relax |
| 552 |
\begin{command}{\ifpgfshadingmodelrgb} |
| 553 |
Within the \meta{type 4 function} argument of |
| 554 |
|\pgfdeclarefunctionalshading|, this command can be used to test if the |
| 555 |
|xcolor| color model is |rgb| \emph{at the time the shading is created}. |
| 556 |
This can be used to ensure that the data output in the \meta{type 4 |
| 557 |
function} correctly matches the active color model. |
| 558 |
\end{command} |
| 559 |
|
| 560 |
\begin{command}{\ifpgfshadingmodelcmyk} |
| 561 |
Within the \meta{type 4 function} argument of |
| 562 |
|\pgfdeclarefunctionalshading|, this command can be used to test if the |
| 563 |
|xcolor| color model is |cmyk| \emph{at the time the shading is created}. |
| 564 |
This can be used to ensure that the data output in the \meta{type 4 |
| 565 |
function} correctly matches the active color model. |
| 566 |
\end{command} |
| 567 |
|
| 568 |
\begin{command}{\ifpgfshadingmodelgray} |
| 569 |
Within the \meta{type 4 function} argument of |
| 570 |
|\pgfdeclarefunctionalshading|, this command can be used to test if the |
| 571 |
|xcolor| color model is |gray| \emph{at the time the shading is created}. |
| 572 |
This can be used to ensure that the data output in the \meta{type 4 |
| 573 |
function} correctly matches the active color model. |
| 574 |
\end{command} |
| 575 |
} |
| 576 |
|
| 577 |
\subsection{Using Shadings} |
| 578 |
\label{section-shading-a-path} |
| 579 |
|
| 580 |
\begin{command}{\pgfuseshading\marg{shading name}} |
| 581 |
Inserts a previously declared shading into the text. If you wish to use it |
| 582 |
in a |pgfpicture| environment, you should put a |\pgftext| around it. |
| 583 |
% |
| 584 |
\begin{codeexample}[] |
| 585 |
\begin{pgfpicture} |
| 586 |
\pgfdeclareverticalshading{myshadingD} |
| 587 |
{20pt}{color(0pt)=(red); color(20pt)=(blue)} |
| 588 |
\pgftext[at=\pgfpoint{1cm}{0cm}] {\pgfuseshading{myshadingD}} |
| 589 |
\pgftext[at=\pgfpoint{2cm}{0.5cm}]{\pgfuseshading{myshadingD}} |
| 590 |
\end{pgfpicture} |
| 591 |
\end{codeexample} |
| 592 |
% |
| 593 |
\end{command} |
| 594 |
|
| 595 |
\begin{command}{\pgfshadepath\marg{shading name}\marg{angle}} |
| 596 |
This command must be used inside a |{pgfpicture}| environment. The effect |
| 597 |
is a bit complex, so let us go over it step by step. |
| 598 |
|
| 599 |
First, \pgfname\ will set up a local scope. |
| 600 |
|
| 601 |
Second, it uses the current path to clip everything inside this scope. |
| 602 |
However, the current path is once more available after the scope, so it can |
| 603 |
be used, for example, to stroke it. |
| 604 |
|
| 605 |
Now, the \meta{shading name} should be a shading whose width and height are |
| 606 |
100\,bp, that is, 100 big points. \pgfname\ has a look at the bounding box |
| 607 |
of the current path. This bounding box is computed automatically when a |
| 608 |
path is computed; however, it can sometimes be (quite a bit) too large, |
| 609 |
especially when complicated curves are involved. |
| 610 |
|
| 611 |
Inside the scope, the low-level transformation matrix is modified. The |
| 612 |
center of the shading is translated (moved) such that it lies on the center |
| 613 |
of the bounding box of the path. The low-level coordinate system is also |
| 614 |
scaled such that the shading ``covers'' the path (the details are a bit |
| 615 |
more complex, see below). Then, the coordinate system is rotated by |
| 616 |
\meta{angle}. Finally, if the macro |\pgfsetadditionalshadetransform| has |
| 617 |
been used, an additional transformation is applied. |
| 618 |
|
| 619 |
After everything has been set up, the shading is inserted. Due to the |
| 620 |
transformations and clippings, the effect will be that the shading seems |
| 621 |
to ``fill'' the path. |
| 622 |
|
| 623 |
If both the path and the shadings were always rectangles and if rotations |
| 624 |
were never involved, it would be easy to scale shadings such they always |
| 625 |
cover the path. However, when a vertical shading is rotated, it must |
| 626 |
obviously be ``magnified'' so that it still covers the path. Things get |
| 627 |
worse when the path is not a rectangle itself. |
| 628 |
|
| 629 |
For these reasons, things work slightly differently ``in reality''. The |
| 630 |
shading is scaled and translated such that the point |
| 631 |
$(50\mathrm{bp},50\mathrm{bp})$, which is the middle of the shading, is at |
| 632 |
the middle of the path and such that the point |
| 633 |
$(25\mathrm{bp},25\mathrm{bp})$ is at the lower left corner of the path and |
| 634 |
that $(75\mathrm{bp},75\mathrm{bp})$ is at upper right corner. |
| 635 |
|
| 636 |
In other words, only the center quarter of the shading will actually |
| 637 |
``survive the clipping'' if the path is a rectangle. If the path is not a |
| 638 |
rectangle, but, say, a circle, even less is seen of the shading. Here is an |
| 639 |
example that demonstrates this effect: |
| 640 |
% |
| 641 |
\begin{codeexample}[] |
| 642 |
\pgfdeclareverticalshading{myshadingE}{100bp} |
| 643 |
{color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} |
| 644 |
\pgfuseshading{myshadingE} |
| 645 |
\hskip 1cm |
| 646 |
\begin{pgfpicture} |
| 647 |
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} |
| 648 |
\pgfshadepath{myshadingE}{0} |
| 649 |
\pgfusepath{stroke} |
| 650 |
\pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{1cm}{2cm}} |
| 651 |
\pgfshadepath{myshadingE}{0} |
| 652 |
\pgfusepath{stroke} |
| 653 |
\pgfpathrectangle{\pgfpoint{5cm}{0cm}}{\pgfpoint{2cm}{2cm}} |
| 654 |
\pgfshadepath{myshadingE}{45} |
| 655 |
\pgfusepath{stroke} |
| 656 |
\pgfpathcircle{\pgfpoint{9cm}{1cm}}{1cm} |
| 657 |
\pgfshadepath{myshadingE}{45} |
| 658 |
\pgfusepath{stroke} |
| 659 |
\end{pgfpicture} |
| 660 |
\end{codeexample} |
| 661 |
|
| 662 |
As can be seen above in the last case, the ``hidden'' part of the shading |
| 663 |
actually \emph{can} become visible if the shading is rotated. The reason is |
| 664 |
that it is scaled as if no rotation took place, then the rotation is done. |
| 665 |
|
| 666 |
The following graphics show which part of the shading are actually shown: |
| 667 |
% |
| 668 |
\begin{codeexample}[] |
| 669 |
\pgfdeclareverticalshading{myshadingF}{100bp} |
| 670 |
{color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} |
| 671 |
\begin{tikzpicture} |
| 672 |
\draw (50bp,50bp) node {\pgfuseshading{myshadingF}}; |
| 673 |
\draw[white,thick] (25bp,25bp) rectangle (75bp,75bp); |
| 674 |
\draw (50bp,0bp) node[below] {first two applications}; |
| 675 |
|
| 676 |
\begin{scope}[xshift=5cm] |
| 677 |
\draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; |
| 678 |
\draw[rotate around={45:(50bp,50bp)},white,thick] (25bp,25bp) rectangle (75bp,75bp); |
| 679 |
\draw (50bp,0bp) node[below] {third application}; |
| 680 |
\end{scope} |
| 681 |
|
| 682 |
\begin{scope}[xshift=10cm] |
| 683 |
\draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; |
| 684 |
\draw[white,thick] (50bp,50bp) circle (25bp); |
| 685 |
\draw (50bp,0bp) node[below] {fourth application}; |
| 686 |
\end{scope} |
| 687 |
\end{tikzpicture} |
| 688 |
\end{codeexample} |
| 689 |
|
| 690 |
An advantage of this approach is that when you rotate a radial shading, no |
| 691 |
distortion is introduced: |
| 692 |
% |
| 693 |
\begin{codeexample}[] |
| 694 |
\pgfdeclareradialshading{ballshading}{\pgfpoint{-10bp}{10bp}} |
| 695 |
{color(0bp)=(red!15!white); color(9bp)=(red!75!white); |
| 696 |
color(18bp)=(red!70!black); color(25bp)=(red!50!black); color(50bp)=(black)} |
| 697 |
\pgfuseshading{ballshading} |
| 698 |
\hskip 1cm |
| 699 |
\begin{pgfpicture} |
| 700 |
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{1cm}{1cm}} |
| 701 |
\pgfshadepath{ballshading}{0} |
| 702 |
\pgfusepath{} |
| 703 |
\pgfpathcircle{\pgfpoint{3cm}{0cm}}{1cm} |
| 704 |
\pgfshadepath{ballshading}{0} |
| 705 |
\pgfusepath{} |
| 706 |
\pgfpathcircle{\pgfpoint{6cm}{0cm}}{1cm} |
| 707 |
\pgfshadepath{ballshading}{45} |
| 708 |
\pgfusepath{} |
| 709 |
\end{pgfpicture} |
| 710 |
\end{codeexample} |
| 711 |
|
| 712 |
If you specify a rotation of $90^\circ$ and if the path is not a square, |
| 713 |
but an elongated rectangle, the ``desired'' effect results: The shading |
| 714 |
will exactly vary between the colors at the 25bp and 75bp boundaries. Here |
| 715 |
is an example: |
| 716 |
% |
| 717 |
\begin{codeexample}[] |
| 718 |
\pgfdeclareverticalshading{myshadingG}{100bp} |
| 719 |
{color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} |
| 720 |
\begin{pgfpicture} |
| 721 |
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} |
| 722 |
\pgfshadepath{myshadingG}{0} |
| 723 |
\pgfusepath{stroke} |
| 724 |
\pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{2cm}{1cm}} |
| 725 |
\pgfshadepath{myshadingG}{90} |
| 726 |
\pgfusepath{stroke} |
| 727 |
\pgfpathrectangle{\pgfpoint{6cm}{0cm}}{\pgfpoint{2cm}{1cm}} |
| 728 |
\pgfshadepath{myshadingG}{45} |
| 729 |
\pgfusepath{stroke} |
| 730 |
\end{pgfpicture} |
| 731 |
\end{codeexample} |
| 732 |
|
| 733 |
As a final example, let us define a ``rainbow spectrum'' shading for use |
| 734 |
with \tikzname. |
| 735 |
% |
| 736 |
\begin{codeexample}[] |
| 737 |
\pgfdeclareverticalshading{rainbow}{100bp} |
| 738 |
{color(0bp)=(red); color(25bp)=(red); color(35bp)=(yellow); |
| 739 |
color(45bp)=(green); color(55bp)=(cyan); color(65bp)=(blue); |
| 740 |
color(75bp)=(violet); color(100bp)=(violet)} |
| 741 |
\begin{tikzpicture}[shading=rainbow] |
| 742 |
\shade (0,0) rectangle node[white] {\textsc{pride}} (2,1); |
| 743 |
\shade[shading angle=90] (3,0) rectangle +(1,2); |
| 744 |
\end{tikzpicture} |
| 745 |
\end{codeexample} |
| 746 |
|
| 747 |
Note that rainbow shadings are \emph{way} too colorful in almost all |
| 748 |
applications. |
| 749 |
\end{command} |
| 750 |
|
| 751 |
\begin{command}{\pgfsetadditionalshadetransform\marg{transformation}} |
| 752 |
This command allows you to specify an additional transformation that should |
| 753 |
be applied to shadings when the |\pgfshadepath| command is used. The |
| 754 |
\meta{transformation} should be transformation code like |
| 755 |
|\pgftransformrotate{20}|. |
| 756 |
\end{command} |
| 757 |
|
| 758 |
|
| 759 |
%%% Local Variables: |
| 760 |
%%% mode: latex |
| 761 |
%%% TeX-master: "pgfmanual" |
| 762 |
%%% End: |