Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-shadings.tex

raw
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: