Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-transparency.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{Transparency}
12 \label{section-tikz-transparency}
13
14 \subsection{Overview}
15
16 Normally, when you paint something using any of \tikzname's commands (this
17 includes stroking, filling, shading, patterns, and images), the newly painted
18 objects totally obscure whatever was painted earlier in the same area.
19
20 You can change this behavior by using something that can be thought of as
21 ``(semi)transparent colors''. Such colors do not completely obscure the
22 background, rather they blend the background with the new color. At first
23 sight, using such semitransparent colors might seem quite straightforward, but
24 the math going on in the background is quite involved and the correct handling
25 of transparency fills some 64 pages in the PDF specification.
26
27 In the present section, we start with the different ways of specifying ``how
28 transparent'' newly drawn objects should be. The simplest way is to just
29 specify a percentage like ``60\% transparent''. A much more general way is to
30 use something that I call a \emph{fading}, also known as a soft mask or a mask.
31
32 At the end of the section we address the problem of creating so-called
33 \emph{transparency groups}. This problem arises when you paint over a position
34 several times with a semitransparent color. Sometimes you want the effect to
35 accumulate, sometimes you do not.
36
37 \emph{Note:} Transparency (or Opacity, as it may be called as well) is best
38 supported by the pdf\TeX\ driver. The \textsc{svg} driver also has some
39 support. The PostScript file format does not know about transparency. In
40 |dvips|-generated PostScript files, transparency of graphic objects is defined
41 through special commands that need further processing to become visible in the
42 \textsc{pdf} output. For this, a recent version of Ghostscript, preferably 9.52
43 or newer, is required and its command line utility |ps2pdf| must be called with
44 option |-dALLOWPSTRANSPARENCY|. Older versions may need option |-dNOSAFER|
45 instead, but some advanced features, such as \emph{transparency groups} and
46 \emph{fadings}, may not work at all. Printers and other programs will typically
47 ignore opacity settings in PostScript files.
48
49
50 \subsection{Specifying a Uniform Opacity}
51
52 Specifying a stroke and/or fill opacity is quite easy using the following
53 options.
54
55 \begin{key}{/tikz/draw opacity=\meta{value}}
56 This option sets ``how transparent'' lines should be. A value of |1| means
57 ``fully opaque'' or ``not transparent at all'', a value of |0| means
58 ``fully transparent'' or ``invisible''. A value of |0.5| yields lines that
59 are semitransparent.
60
61 Note that when you use PostScript as your output format, this option works
62 only with recent versions of Ghostscript.
63 %
64 \begin{codeexample}[]
65 \begin{tikzpicture}[line width=1ex]
66 \draw (0,0) -- (3,1);
67 \filldraw [fill=yellow!80!black,draw opacity=0.5] (1,0) rectangle (2,1);
68 \end{tikzpicture}
69 \end{codeexample}
70 %
71 \end{key}
72
73 Note that the |draw opacity| options only sets the opacity of drawn lines. The
74 opacity of fillings is set using the option |fill opacity| (documented in
75 Section~\ref{section-fill-opacity}. The option |opacity| sets both at the same
76 time.
77
78 \begin{key}{/tikz/opacity=\meta{value}}
79 Sets both the drawing and filling opacity to \meta{value}.
80
81 The following predefined styles make it easier to use this option:
82 %
83 \begin{stylekey}{/tikz/transparent}
84 Makes everything totally transparent and, hence, invisible.
85 %
86 \begin{codeexample}[]
87 \tikz{\fill[red] (0,0) rectangle (1,0.5);
88 \fill[transparent,red] (0.5,0) rectangle (1.5,0.25); }
89 \end{codeexample}
90 \end{stylekey}
91
92 \begin{stylekey}{/tikz/ultra nearly transparent}
93 Makes everything, well, ultra nearly transparent.
94 %
95 \begin{codeexample}[]
96 \tikz{\fill[red] (0,0) rectangle (1,0.5);
97 \fill[ultra nearly transparent] (0.5,0) rectangle (1.5,0.25); }
98 \end{codeexample}
99 \end{stylekey}
100
101 \begin{stylekey}{/tikz/very nearly transparent}
102 \begin{codeexample}[]
103 \tikz{\fill[red] (0,0) rectangle (1,0.5);
104 \fill[very nearly transparent] (0.5,0) rectangle (1.5,0.25); }
105 \end{codeexample}
106 \end{stylekey}
107
108 \begin{stylekey}{/tikz/nearly transparent}
109 \begin{codeexample}[]
110 \tikz{\fill[red] (0,0) rectangle (1,0.5);
111 \fill[nearly transparent] (0.5,0) rectangle (1.5,0.25); }
112 \end{codeexample}
113 \end{stylekey}
114
115 \begin{stylekey}{/tikz/semitransparent}
116 \begin{codeexample}[]
117 \tikz{\fill[red] (0,0) rectangle (1,0.5);
118 \fill[semitransparent] (0.5,0) rectangle (1.5,0.25); }
119 \end{codeexample}
120 \end{stylekey}
121
122 \begin{stylekey}{/tikz/nearly opaque}
123 \begin{codeexample}[]
124 \tikz{\fill[red] (0,0) rectangle (1,0.5);
125 \fill[nearly opaque] (0.5,0) rectangle (1.5,0.25); }
126 \end{codeexample}
127 \end{stylekey}
128
129 \begin{stylekey}{/tikz/very nearly opaque}
130 \begin{codeexample}[]
131 \tikz{\fill[red] (0,0) rectangle (1,0.5);
132 \fill[very nearly opaque] (0.5,0) rectangle (1.5,0.25); }
133 \end{codeexample}
134 \end{stylekey}
135
136 \begin{stylekey}{/tikz/ultra nearly opaque}
137 \begin{codeexample}[]
138 \tikz{\fill[red] (0,0) rectangle (1,0.5);
139 \fill[ultra nearly opaque] (0.5,0) rectangle (1.5,0.25); }
140 \end{codeexample}
141 \end{stylekey}
142
143 \begin{stylekey}{/tikz/opaque}
144 This yields completely opaque drawings, which is the default.
145 %
146 \begin{codeexample}[]
147 \tikz{\fill[red] (0,0) rectangle (1,0.5);
148 \fill[opaque] (0.5,0) rectangle (1.5,0.25); }
149 \end{codeexample}
150 \end{stylekey}
151 \end{key}
152
153 \begin{key}{/tikz/fill opacity=\meta{value}}
154 This option sets the opacity of fillings. In addition to filling
155 operations, this opacity also applies to text and images.
156
157 Note, again, that when you use PostScript as your output format, this
158 option works only with recent versions of Ghostscript.
159 %
160 \begin{codeexample}[]
161 \begin{tikzpicture}[thick,fill opacity=0.5]
162 \filldraw[fill=red] (0:1cm) circle (12mm);
163 \filldraw[fill=green] (120:1cm) circle (12mm);
164 \filldraw[fill=blue] (-120:1cm) circle (12mm);
165 \end{tikzpicture}
166 \end{codeexample}
167
168 \begin{codeexample}[]
169 \begin{tikzpicture}
170 \fill[red] (0,0) rectangle (3,2);
171
172 \node at (0,0) {\huge A};
173 \node[fill opacity=0.5] at (3,2) {\huge B};
174 \end{tikzpicture}
175 \end{codeexample}
176 %
177 \end{key}
178
179 \begin{key}{/tikz/text opacity=\meta{value}}
180 Sets the opacity of text labels, overriding the |fill opacity| setting.
181 %
182 \begin{codeexample}[]
183 \begin{tikzpicture}[every node/.style={fill,draw}]
184 \draw[line width=2mm,blue!50,line cap=round] (0,0) grid (3,2);
185
186 \node[opacity=0.5] at (1.5,2) {Upper node};
187 \node[draw opacity=0.8,fill opacity=0.2,text opacity=1]
188 at (1.5,0) {Lower node};
189 \end{tikzpicture}
190 \end{codeexample}
191 %
192 \end{key}
193
194 Note the following effect: If you set up a certain opacity for stroking or
195 filling and you stroke or fill the same area twice, the effect accumulates:
196 %
197 \begin{codeexample}[]
198 \begin{tikzpicture}[fill opacity=0.5]
199 \fill[red] (0,0) circle (1);
200 \fill[red] (1,0) circle (1);
201 \end{tikzpicture}
202 \end{codeexample}
203
204 Often, this is exactly what you intend, but not always. You can use
205 transparency groups, see the end of this section, to change this.
206
207
208 \subsection{Blend Modes}
209 \label{section-blend-modes}
210
211 A \emph{blend mode} specifies how colors mix when you paint on a canvas.
212 Normally, if you paint a red box on a green circle, the red color will
213 completely replace the green circle. However, in some situations you might also
214 wish the red color to somehow ``mix'' or ``blend'' with the green circle. We
215 already saw that, using transparency, we can draw something without completely
216 obscuring the background. \emph{Blending} is a similar operation, only here we
217 mix colors in more complicated ways.
218
219 \emph{Note:} Blending is a rather ``advanced'' feature of \textsc{pdf}. Most
220 renderers, let alone printers, will have trouble rendering blending correctly.
221
222 \begin{key}{/tikz/blend mode=\meta{mode}}
223 Sets the current blend mode to \meta{mode}. Here \meta{mode} must be one of
224 the modes listed below. More details on these modes can also be found in
225 Section~7.2.4 of the \textsc{pdf} Specification, version~1.7.
226
227 In the following example, the blend mode is only used and set inside a
228 transparency group (see also Section~\ref{section-transparency-groups}).
229 This is because most renderers (viewing programs) have trouble rendering
230 blending correctly otherwise. For instance, at the time of writing, the
231 versions of Adobe's Reader and Apple's Preview render the following drawing
232 very differently, if the transparency group is not used in the following
233 example.
234 %
235 \begin{codeexample}[]
236 \tikz {
237 \begin{scope}[transparency group]
238 \begin{scope}[blend mode=screen]
239 \fill[red!90!black] ( 90:.6) circle (1);
240 \fill[green!80!black] (210:.6) circle (1);
241 \fill[blue!90!black] (330:.6) circle (1);
242 \end{scope}
243 \end{scope}
244 }
245 \end{codeexample}
246
247 Because of the trouble with rendering blending correctly outside
248 transparency groups, there is a special key that establishes a transparency
249 group and sets a blend mode simultaneously:
250
251 \begin{key}{/tikz/blend group=\meta{mode}}
252 This key can only be used with a scope (like |transparency group|). It
253 will cause the current scope to become a transparency group and, inside
254 this group, the blend mode will be set to \meta{mode}.
255 %
256 \begin{codeexample}[]
257 \tikz [blend group=screen] {
258 \fill[red!90!black] ( 90:.6) circle (1);
259 \fill[green!80!black] (210:.6) circle (1);
260 \fill[blue!90!black] (330:.6) circle (1);
261 }
262 \end{codeexample}
263 \end{key}
264
265 Here is an overview of the effects of the different available blend modes.
266 In the examples, we always have three circles drawn on top of each other
267 (as in the example code earlier): We start with a triple of pure red,
268 green, and blue. Below it, we have a triple of light versions of these
269 three colors (|red!50|, |green!50|, and |blue!50|). Next comes the triple
270 yellow, cyan, and magenta; again with a triple of light versions below it.
271 The large example consists of three balls (produced using |ball color|)
272 having the colors red, green, and blue, are drawn on top of each other just
273 like the circles.
274
275 \definecolor{rg}{rgb}{1,1,0}
276 \definecolor{gb}{rgb}{0,1,1}
277 \definecolor{br}{rgb}{1,0,1}
278
279 \def\makeline#1#2#3{\leavevmode
280 \hbox to 40mm{#1\hss}\ \hbox to
281 20.5mm{#2\hss}\ \begin{minipage}[t]{88.5mm}\raggedright#3\end{minipage}\par
282 \textcolor{black!25}{\hrule height1pt}
283 }
284
285 \def\showmode#1#2{
286 \makeline{
287 \tikz [blend mode=#1,baseline=-.5ex] {
288 \fill[red] ( 90:.5em) circle (.75em);
289 \fill[green] (210:.5em) circle (.75em);
290 \fill[blue] (330:.5em) circle (.75em);
291 \scoped[yshift=-2.5em]{
292 \fill[red!50] ( 90:.5em) circle (.75em);
293 \fill[green!50] (210:.5em) circle (.75em);
294 \fill[blue!50] (330:.5em) circle (.75em);
295 }
296 }
297 \tikz [blend mode=#1,baseline=-.5ex] {
298 \fill[rg] ( 90:.5em) circle (.75em);
299 \fill[gb] (210:.5em) circle (.75em);
300 \fill[br] (330:.5em) circle (.75em);
301 \scoped[yshift=-2.5em]{
302 \fill[rg!50] ( 90:.5em) circle (.75em);
303 \fill[gb!50] (210:.5em) circle (.75em);
304 \fill[br!50] (330:.5em) circle (.75em);
305 }
306 }
307 \tikz [blend mode=#1,baseline=-.5ex+1.25em] {
308 \shade[ball color=red] ( 90:1em) circle (1.5em);
309 \shade[ball color=green] (210:1em) circle (1.5em);
310 \shade[ball color=blue] (330:1em) circle (1.5em);
311 }}{\verb|#1|}{#2}%
312 % this argument was changed from {|#1|}
313 % --> see <https://sourceforge.net/p/pgf/bugs/486/>
314 }
315
316 \medskip
317 \makeline{\emph{Example}}{\emph{Mode}}{\emph{Explanations quoted from
318 Table~7.2 of the \textsc{pdf} Specification, Version~1.7}}
319 \showmode{normal}{When painting a pixel with a some color (called the
320 ``source color''), the background color (called the ``backdrop'') is
321 completely ignored.}
322 \showmode{multiply}{Multiplies the backdrop and source color values. The
323 result color is always at least as dark as either of the two
324 constituent colors. Multiplying any color with black produces black;
325 multiplying with white leaves the original color unchanged. Painting
326 successive overlapping objects with a color other than black or white
327 produces progressively darker colors.}
328 \showmode{screen}{Multiplies the complements of the backdrop and source
329 color values, then complements the result. The result color is always
330 at least as light as either of the two constituent colors. Screening
331 any color with white produces white; screening with black leaves the
332 original color unchanged. The effect is similar to projecting multiple
333 photographic slides simultaneously onto a single screen.}
334 \showmode{overlay}{Multiplies or screens the colors, depending on the
335 backdrop color value. Source colors overlay the backdrop while
336 preserving its highlights and shadows. The backdrop color is not
337 replaced but is mixed with the source color to reflect the lightness or
338 darkness of the backdrop.}
339 \showmode{darken}{Selects the darker of the backdrop and source colors. The
340 backdrop is replaced with the source where the source is darker;
341 otherwise, it is left unchanged.}
342 \showmode{lighten}{Selects the lighter of the backdrop and source colors.
343 The backdrop is replaced with the source where the source is lighter;
344 otherwise, it is left unchanged.}
345 \showmode{color dodge}{Brightens the backdrop color to reflect the source
346 color. Painting with black produces no changes.}
347 \showmode{color burn}{Darkens the backdrop color to reflect the source
348 color. Painting with white produces no change.}
349 \showmode{hard light}{Multiplies or screens the colors, depending on the
350 source color value. The effect is similar to shining a harsh spotlight
351 on the backdrop.}
352 \showmode{soft light}{Darkens or lightens the colors, depending on the
353 source color value. The effect is similar to shining a diffused
354 spotlight on the backdrop.}
355 \showmode{difference}{Subtracts the darker of the two constituent colors
356 from the lighter color. Painting with white inverts the backdrop color;
357 painting with black produces no change.}
358 \showmode{exclusion}{Produces an effect similar to that of the Difference
359 mode but lower in contrast. Painting with white inverts the backdrop
360 color; painting with black produces no change.}
361 \showmode{hue}{Creates a color with the hue of the source color and the
362 saturation and luminosity of the backdrop color.}
363 \showmode{saturation}{Creates a color with the saturation of the source
364 color and the hue and luminosity of the backdrop color. Painting with
365 this mode in an area of the backdrop that is a pure gray (no
366 saturation) produces no change.}
367 \showmode{color}{Creates a color with the hue and saturation of the source
368 color and the luminosity of the backdrop color. This preserves the gray
369 levels of the backdrop and is useful for coloring monochrome images or
370 tinting color images.}
371 \showmode{luminosity}{Creates a color with the luminosity of the source
372 color and the hue and saturation of the backdrop color. This produces
373 an inverse effect to that of the Color mode.}
374 \end{key}
375
376
377 \subsection{Fadings}
378
379 For complicated graphics, uniform transparency settings are not always
380 sufficient. Suppose, for instance, that while you paint a picture, you want the
381 transparency to vary smoothly from completely opaque to completely transparent.
382 This is a ``shading-like'' transparency. For such a form of transparency I will
383 use the term \emph{fading} (as a noun). They are also known as \emph{soft
384 masks}, \emph{opacity masks}, \emph{masks}, or \emph{soft clips}.
385
386
387 \subsubsection{Creating Fadings}
388
389 How do we specify a fading? This is a bit of an art since the underlying
390 mechanism is quite powerful, but a bit difficult to use.
391
392 Let us start with a bit of terminology. A \emph{fading} specifies for each
393 point of an area the transparency of that point. This transparency can by any
394 number between 0 and 1. A \emph{fading picture} is a normal graphic that, in a
395 way to be described in a moment, determines the transparency of points inside
396 the fading. Each fading has an underlying fading picture.
397
398 The fading picture is a normal graphic drawn using any of the normal graphic
399 drawing commands. A fading and its fading picture are related as follows: Given
400 any point of the fading, the transparency of this point is determined by the
401 luminosity of the fading picture at the same position. The luminosity of a
402 point determines ``how bright'' the point is. The brighter the point in the
403 fading picture, the more opaque is the point in the fading. In particular, a
404 white point of the fading picture is completely opaque in the fading and a
405 black point of the fading picture is completely transparent in the fading. (The
406 background of the fading picture is always transparent in the fading as if the
407 background were black.)
408
409 It is rather counter-intuitive that a \emph{white} pixel of the fading picture
410 will be \emph{opaque} in the fading and a \emph{black} pixel will be
411 \emph{transparent}. For this reason, \tikzname\ defines a color called
412 |transparent| that is the same as |black|. The nice thing about this definition
413 is that the color |transparent!|\meta{percentage} in the fading picture yields
414 a pixel that is \meta{percentage} percent transparent in the fading.
415
416 Turning a fading picture into a normal picture is achieved using the following
417 commands, which are \emph{only defined in the library}, namely the library
418 |fadings|. So, to use them, you have to say |\usetikzlibrary{fadings}| first.
419
420 \begin{environment}{{tikzfadingfrompicture}\oarg{options}}
421 This command works like a |{tikzpicture}|, only the picture is not shown,
422 but instead a fading is defined based on this picture. To set the name of
423 the picture, use the |name| option (which is normally used to set the name
424 of a node).
425 %
426 \begin{key}{/tikz/name=\marg{name}}
427 Use this option with the |{tikzfadingfrompicture}| environment to set
428 the name of the fading. You \emph{must} provide this option.
429 \end{key}
430
431 The following shading is 2cm by 2cm and gets more and more transparent from
432 left to right, but is 50\% transparent for a large circle in the middle.
433 %
434 {\ifpgfmanualexternalize\tikzexternaldisable\fi
435 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
436 \begin{tikzfadingfrompicture}[name=fade right with circle]
437 \shade[left color=transparent!0,
438 right color=transparent!100] (0,0) rectangle (2,2);
439 \fill[transparent!50] (1,1) circle (0.7);
440 \end{tikzfadingfrompicture}
441
442 % Now we use the fading in another picture:
443 \begin{tikzpicture}
444 % Background
445 \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
446 \pattern [pattern=checkerboard,pattern color=black!30]
447 (-1.2,-1.2) rectangle (1.2,1.2);
448
449 \fill [path fading=fade right with circle,red] (-1,-1) rectangle (1,1);
450 \end{tikzpicture}
451 \end{codeexample}
452 %
453 In the next example we create a fading picture that contains some text.
454 When the fading is used, we only see the shading ``through it''.
455 %
456 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
457 \begin{tikzfadingfrompicture}[name=tikz]
458 \node [text=transparent!20,
459 font=\fontencoding{T1}\fontfamily{ptm}\fontsize{45}{45}\bfseries]
460 {Ti\emph{k}Z};
461 \end{tikzfadingfrompicture}
462
463 % Now we use the fading in another picture:
464 \begin{tikzpicture}
465 \fill [black!20] (-2,-1) rectangle (2,1);
466 \pattern [pattern=checkerboard,pattern color=black!30]
467 (-2,-1) rectangle (2,1);
468
469 \shade[path fading=tikz,fit fading=false,
470 left color=blue,right color=black]
471 (-2,-1) rectangle (2,1);
472 \end{tikzpicture}
473 \end{codeexample}
474 }%
475
476 The same effect can also be achieved using knockout groups, see
477 Section~\ref{section-transparency-groups}.
478 \end{environment}
479
480 \begin{plainenvironment}{{tikzfadingfrompicture}\oarg{options}}
481 The plain\TeX\ version of the environment.
482 \end{plainenvironment}
483
484 \begin{contextenvironment}{{tikzfadingfrompicture}\oarg{options}}
485 The Con\TeX t version of the environment.
486 \end{contextenvironment}
487
488 \begin{command}{\tikzfading\oarg{options}}
489 This command is used to define a fading similarly to the way a shading is
490 defined. In the \meta{options} you should
491 %
492 \begin{enumerate}
493 \item use the |name=|\meta{name} option to set a name for the fading,
494 \item use the |shading| option to set the name of the shading that you
495 wish to use,
496 \item extra options for setting the colors of the shading (typically
497 you will set them to the color |transparent!|\meta{percentage}).
498 \end{enumerate}
499 %
500 Then, a new fading named \meta{name} will be created based on the shading.
501 %
502 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
503 \tikzfading[name=fade right,
504 left color=transparent!0,
505 right color=transparent!100]
506
507 % Now we use the fading in another picture:
508 \begin{tikzpicture}
509 % Background
510 \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
511 \path [pattern=checkerboard,pattern color=black!30]
512 (-1.2,-1.2) rectangle (1.2,1.2);
513
514 \fill [red,path fading=fade right] (-1,-1) rectangle (1,1);
515 \end{tikzpicture}
516 \end{codeexample}
517
518 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
519 \tikzfading[name=fade out,
520 inner color=transparent!0,
521 outer color=transparent!100]
522
523 % Now we use the fading in another picture:
524 \begin{tikzpicture}
525 % Background
526 \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
527 \path [pattern=checkerboard,pattern color=black!30]
528 (-1.2,-1.2) rectangle (1.2,1.2);
529
530 \fill [blue,path fading=fade out] (-1,-1) rectangle (1,1);
531 \end{tikzpicture}
532 \end{codeexample}
533 %
534 \end{command}
535
536
537 \subsubsection{Fading a Path}
538
539 A fading specifies for each pixel of a certain area how transparent this pixel
540 will be. The following options are used to install such a fading for the
541 current scope or path.
542
543 \pgfdeclarefading{fade down}{%
544 \tikzset{top color=pgftransparent!0,bottom color=pgftransparent!100}
545 \pgfuseshading{axis}
546 }
547 \pgfdeclarefading{fade inside}{%
548 \tikzset{inner color=pgftransparent!90,outer color=pgftransparent!30}
549 \pgfuseshading{radial}
550 }
551
552 \begin{key}{/tikz/path fading=\meta{name} (default \normalfont scope's setting)}
553 This option tells \tikzname\ that the current path should be faded with the
554 fading \meta{name}. If no \meta{name} is given, the \meta{name} set for the
555 whole scope is used. Similarly to options like |draw| or |fill|, this
556 option is reset for each path, so you have to add it to each path that
557 should be faded. You can also specify |none| as \meta{name}, in which case
558 fading for the path will be switched off in case it has been switched on by
559 previous options or styles.
560 %
561 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
562 \begin{tikzpicture}[path fading=south]
563 % Checker board
564 \fill [black!20] (0,0) rectangle (4,3);
565 \pattern [pattern=checkerboard,pattern color=black!30]
566 (0,0) rectangle (4,3);
567
568 \fill [color=blue] (0.5,1.5) rectangle +(1,1);
569 \fill [color=blue,path fading=north] (2.5,1.5) rectangle +(1,1);
570
571 \fill [color=red,path fading] (1,0.75) ellipse (.75 and .5);
572 \fill [color=red] (3,0.75) ellipse (.75 and .5);
573 \end{tikzpicture}
574 \end{codeexample}
575
576 \begin{key}{/tikz/fit fading=\meta{boolean} (default true, initially true)}
577 When set to |true|, the fading is shifted and resized (in exactly the
578 same way as a shading) so that it covers the current path. When set to
579 |false|, the fading is only shifted so that it is centered on the
580 path's center, but it is not resized. This can be useful for
581 special-purpose fadings, for instance when you use a fading to ``punch
582 out'' something.
583 \end{key}
584
585 \begin{key}{/tikz/fading transform=\meta{transformation options}}
586 The \meta{transformation options} are applied to the fading before it
587 is used. For instance, if \meta{transformation options} is set to
588 |rotate=90|, the fading is rotated by 90 degrees.
589 %
590 \begin{codeexample}[
591 preamble={\usetikzlibrary{fadings,patterns}},
592 pre={\pgfdeclarefading{fade down}{%
593 \tikzset{top color=pgftransparent!0,bottom color=pgftransparent!100}
594 \pgfuseshading{axis}
595 }}]
596 \begin{tikzpicture}[path fading=fade down]
597 % Checker board
598 \fill [black!20] (0,0) rectangle (4,1.5);
599 \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,1.5);
600
601 \fill [red,path fading,fading transform={rotate=90}]
602 (1,0.75) ellipse (.75 and .5);
603 \fill [red,path fading,fading transform={rotate=30}]
604 (3,0.75) ellipse (.75 and .5);
605 \end{tikzpicture}
606 \end{codeexample}
607 \end{key}
608
609 \begin{key}{/tikz/fading angle=\meta{degree}}
610 A shortcut for |fading transform={rotate=|\meta{degree}|}|.
611 \end{key}
612
613 Note that you can ``fade just about anything''. In particular, you can fade
614 a shading.
615 %
616 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
617 \begin{tikzpicture}
618 % Checker board
619 \fill [black!20] (0,0) rectangle (4,4);
620 \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4);
621
622 \shade [ball color=blue,path fading=south] (2,2) circle (1.8);
623 \end{tikzpicture}
624 \end{codeexample}
625
626 The |fade inside| of the following example is more transparent in the
627 middle than on the outside.
628 %
629 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
630 \tikzfading[name=fade inside,
631 inner color=transparent!80,
632 outer color=transparent!30]
633 \begin{tikzpicture}
634 % Checker board
635 \fill [black!20] (0,0) rectangle (4,4);
636 \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4);
637
638 \shade [ball color=red] (3,3) circle (0.8);
639 \shade [ball color=white,path fading=fade inside] (2,2) circle (1.8);
640 \end{tikzpicture}
641 \end{codeexample}
642
643 Note that adding the |path fading| option to a node fades the (background)
644 path, not the text itself. To fade the text, you need to use a scope fading
645 (see below).
646 \end{key}
647
648 Note that using fadings in conjunction with patterns can create visually rather
649 pleasing effects:
650 %
651 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns,shadows}}]
652 \tikzfading[name=middle,
653 top color=transparent!50,
654 bottom color=transparent!50,
655 middle color=transparent!20]
656 \begin{tikzpicture}
657 \node [circle,circular drop shadow,
658 pattern=horizontal lines dark blue,
659 path fading=south,
660 minimum size=3.6cm] {};
661 \pattern [path fading=north,
662 pattern=horizontal lines dark gray]
663 (0,0) circle (1.8cm);
664 \pattern [path fading=middle,
665 pattern=crosshatch dots light steel blue]
666 (0,0) circle (1.8cm);
667 \end{tikzpicture}
668 \end{codeexample}
669
670
671 \subsubsection{Fading a Scope}
672
673 In addition to fading individual paths, you may also wish to ``fade a scope'',
674 that is, you may wish to install a fading that is used globally to specify the
675 transparency for all objects drawn inside a scope. This effect can also be
676 thought of as a ``soft clip'' and it works in a similar way: You add the
677 |scope fading| option to a path in a scope -- typically the first one -- and
678 then all subsequent drawings in the scope are faded. You will use a
679 |transparency group| in conjunction, see the end of this section.
680
681 \begin{key}{/tikz/scope fading=\meta{fading}}
682 In principle, this key works in exactly the same way as the |path fading|
683 key. The only difference is, that the effect of the fading will persist
684 after the current path till the end of the scope. Thus, the \meta{fading}
685 is applied to all subsequent drawings in the current scope, not just to the
686 current path. In this regard, the option works very much like the |clip|
687 option. (Note, however, that, unlike the |clip| option, fadings to not
688 accumulate unless a transparency group is used.)
689
690 The keys |fit fading| and |fading transform| have the same effect as for
691 |path fading|. Also that, just as for |path fading|, providing the
692 |scope fading| option with a |{scope}| only sets the name of the fading to
693 be used. You have to explicitly provide the |scope fading| with a path to
694 actually install a fading.
695 %
696 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
697 \begin{tikzpicture}
698 \fill [black!20] (-2,-2) rectangle (2,2);
699 \pattern [pattern=checkerboard,pattern color=black!30]
700 (-2,-2) rectangle (2,2);
701
702 % The bounding box of the shading:
703 \draw [red] (-50bp,-50bp) rectangle (50bp,50bp);
704
705 \path [scope fading=south,fit fading=false] (0,0);
706 % fading is centered at its natural size
707
708 \fill[red] ( 90:1) circle (1);
709 \fill[green] (210:1) circle (1);
710 \fill[blue] (330:1) circle (1);
711 \end{tikzpicture}
712 \end{codeexample}
713
714 In the following example we resize the fading to the size of the whole
715 picture:
716 %
717 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
718 \begin{tikzpicture}
719 \fill [black!20] (-2,-2) rectangle (2,2);
720 \pattern [pattern=checkerboard,pattern color=black!30]
721 (-2,-2) rectangle (2,2);
722
723 \path [scope fading=south] (-2,-2) rectangle (2,2);
724
725 \fill[red] ( 90:1) circle (1);
726 \fill[green] (210:1) circle (1);
727 \fill[blue] (330:1) circle (1);
728 \end{tikzpicture}
729 \end{codeexample}
730
731 Scope fadings are also needed if you wish to fade a node.
732 %
733 \begin{codeexample}[preamble={\usetikzlibrary{fadings}}]
734 \tikz \node [scope fading=south,fading angle=45,text width=3.5cm]
735 {
736 This is some text that will fade out as we go right
737 and down. It is pretty hard to achieve this effect in
738 other ways.
739 };
740 \end{codeexample}
741 %
742 \end{key}
743
744
745 \subsection{Transparency Groups}
746 \label{section-transparency-groups}
747
748 Consider the following cross and sign. They ``look wrong'' because we can see
749 how they were constructed, while this is not really part of the desired effect.
750 %
751 \begin{codeexample}[]
752 \begin{tikzpicture}[opacity=.5]
753 \draw [line width=5mm] (0,0) -- (2,2);
754 \draw [line width=5mm] (2,0) -- (0,2);
755 \end{tikzpicture}
756 \end{codeexample}
757
758 \begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
759 \begin{tikzpicture}
760 \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
761
762 \node [opacity=.5]
763 at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
764 \end{tikzpicture}
765 \end{codeexample}
766
767 Transparency groups are used to render them correctly:
768 %
769 \begin{codeexample}[]
770 \begin{tikzpicture}[opacity=.5]
771 \begin{scope}[transparency group]
772 \draw [line width=5mm] (0,0) -- (2,2);
773 \draw [line width=5mm] (2,0) -- (0,2);
774 \end{scope}
775 \end{tikzpicture}
776 \end{codeexample}
777
778 \begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
779 \begin{tikzpicture}
780 \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
781
782 \begin{scope}[opacity=.5,transparency group]
783 \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
784 {Smoking};
785 \end{scope}
786 \end{tikzpicture}
787 \end{codeexample}
788
789 \begin{key}{/tikz/transparency group=\oarg{options}}
790 This option can be given to a |scope|. It will have the following effect:
791 The scope's contents is stroked\,/\penalty0\,filled ``ignoring any outside
792 transparency''. This means, all previous transparency settings are ignored
793 (you can still set transparency inside the group, but never mind). For
794 instance, in the forbidden sign example, the whole sign is first painted
795 (conceptually) like the image on the left hand side. Note that some pixels
796 of the sign are painted multiple times (up to three times), but only the
797 last color ``wins''.
798
799 Then, when the scope is finished, it is painted as a whole. The \emph{fill}
800 transparency settings are now applied to the resulting picture. For
801 instance, the pixel that has been painted three times is just red at the
802 end, so this red color will be blended with whatever is ``behind'' the
803 group on the page.
804 %
805 \begin{codeexample}[preamble={\usetikzlibrary{patterns,shapes.symbols}}]
806 \begin{tikzpicture}
807 \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1);
808 \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
809
810 \begin{scope}[transparency group,opacity=.5]
811 \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
812 {Smoking};
813 \end{scope}
814 \end{tikzpicture}
815 \end{codeexample}
816
817 Note that in the example, the |opacity=.5| is not active inside the
818 transparency group: The group is only established at beginning of the scope
819 and all options given to the |{scope}| environment are set before the group
820 is established. To change the opacity \emph{inside} the group, you need to
821 open another scope inside it or use the |opacity| key with a command inside
822 the group:
823 %
824 \begin{codeexample}[preamble={\usetikzlibrary{patterns,shapes.symbols}}]
825 \begin{tikzpicture}
826 \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1);
827 \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
828
829 \begin{scope}[transparency group,opacity=.5]
830 \node (s) at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
831 {Smoking};
832
833 \draw [opacity=.5, line width=2ex, blue] (1.2,0) -- (2.8,0);
834 \end{scope}
835 \end{tikzpicture}
836 \end{codeexample}
837
838 The \meta{options} are a list of comma-separated options:
839 %
840 \begin{itemize}
841 \item \declare{|knockout|} When this option is given inside the
842 \meta{options}, the group becomes a so-called \emph{knockout}
843 group. This means, essentially, that inside the group everything is
844 painted as if the ``opacity'' of a line or area were just another
845 color channel. In particular, if you paint a pixel with opacity $0$
846 inside a knockout group, this pixel becomes perfectly transparent
847 immediately. In contrast, painting a pixel with something of
848 opacity $0$ normally has no effect.
849
850 Not all renderers, let alone printers, will support this. At the
851 time of writing, Apple's Preview will not show the following
852 correctly (you should see the text \tikzname\ in the middle):
853 %
854 \begin{codeexample}[]
855 \begin{tikzpicture}
856 \shade [left color=red,right color=blue] (-2,-1) rectangle (2,1);
857 \begin{scope}[transparency group=knockout]
858 \fill [white] (-1.9,-.9) rectangle (1.9,.9);
859 \node [opacity=0,
860 font=\fontencoding{T1}\fontfamily{ptm}\fontsize{45}{45}\bfseries]
861 {Ti\emph{k}Z};
862 \end{scope}
863 \end{tikzpicture}
864 \end{codeexample}
865 %
866 In the example, we first draw a large shading and then, inside the
867 transparency group ``overwrite'' most of this shading by a big
868 white rectangle. The interesting part is the text of the node,
869 which has opacity |0|. Normally, this would mean that nothing is
870 shown. However, in a knockout group, we ``paint'' the text with an
871 ``opacity zero'' color. The effect is that part of the totally
872 opaque white rectangle gets overwritten by a perfectly transparent
873 area (namely exactly the area taken up by the pixels of the text).
874 When this whole knockout group is then placed on top of the
875 shading, the shading will ``shine through'' at the knocked-out
876 pixels.
877
878 \item \declare{|isolated|}|=false| A group can be isolated or not. By
879 default, they are isolated, since this is typically what you want.
880 For details on what isolated groups are, exactly, see Section~7.3.4
881 of the \textsc{pdf} Specification, version~1.7.
882 \end{itemize}
883
884 Note that when a transparency group is created, \tikzname\ must correctly
885 determine the size of the material inside the group. Usually, this is no
886 problem, but when you use things like |overlay| or |transform canvas|,
887 trouble may result. In this case, please consult
888 Section~\ref{section-transparency} on how to sidestep this problem in such
889 cases.
890 \end{key}
891
892
893 %%% Local Variables:
894 %%% mode: latex
895 %%% TeX-master: "pgfmanual"
896 %%% End: