summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex
blob: 3891d1529877db08a63bfa2bec7eb9489153fa09 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Transparency}

\label{section-tikz-transparency}


\subsection{Overview}

Normally, when you paint something using any of \tikzname's commands
(this includes stroking, filling, shading, patterns, and images), the
newly painted objects totally obscure whatever was painted earlier in
the same area.

You can change this behaviour by using something that can be thought
of as ``(semi)transparent colors.'' Such colors do not completely
obscure the background, rather they blend the background with the new
color. At first sight, using such semitransparent colors might seem quite
straightforward, but the math going on in the background is quite
involved and the correct handling of transparency fills some 64 pages
in the PDF specification.

In the present section, we start with the different ways of specifying
``how transparent'' newly drawn objects should be. The simplest way is
to just specify a percentage like ``60\% transparent.'' A much more
general way is to use something that I call a \emph{fading,} also
known as a soft mask or a mask.

At the end of the section we address the problem of creating so-called
\emph{transparency groups}. This problem arises when you paint over a
position several times with a semitransparent color. Sometimes you
want the effect to accumulate, sometimes you do not.

\emph{Note:} Transparency is best supported by the pdf\TeX\
driver. The \textsc{svg} driver also has some support. For PostScript
output, opacity is rendered correctly only with the most recent
versions of Ghostscript. Printers and other programs will typically
ignore the opacity setting.



\subsection{Specifying a Uniform Opacity}

Specifying a stroke and/or fill opacity is quite easy using the
following options.


\begin{key}{/tikz/draw opacity=\meta{value}}
  This option sets ``how transparent'' lines should be. A value of |1|
  means ``fully opaque'' or ``not transparent at all,'' a value of |0|
  means ``fully transparent'' or ``invisible.'' A value of |0.5|
  yields lines that are semitransparent.

  Note that when you use PostScript as your output format,
  this option works only with recent versions of Ghostscript.

\begin{codeexample}[]
\begin{tikzpicture}[line width=1ex]
  \draw (0,0) -- (3,1);
  \filldraw [fill=yellow!80!black,draw opacity=0.5] (1,0) rectangle (2,1);
\end{tikzpicture}
\end{codeexample}
\end{key}

Note that the |draw opacity| options only sets the opacity of drawn
lines. The opacity of fillings is set using the option
|fill opacity| (documented in Section~\ref{section-fill-opacity}. The
option |opacity| sets both at the same time.

\begin{key}{/tikz/opacity=\meta{value}}
  Sets both the drawing and filling opacity to \meta{value}.

  The following predefined styles make it easier to use this option:
  \begin{stylekey}{/tikz/transparent}
    Makes everything totally transparent and, hence, invisible.

\begin{codeexample}[]
\tikz{\fill[red]             (0,0)   rectangle (1,0.5);
      \fill[transparent,red] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/ultra nearly transparent}
    Makes everything, well, ultra nearly transparent.

\begin{codeexample}[]
\tikz{\fill[red]                      (0,0)   rectangle (1,0.5);
      \fill[ultra nearly transparent] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/very nearly transparent}
\begin{codeexample}[]
\tikz{\fill[red]                     (0,0)   rectangle (1,0.5);
      \fill[very nearly transparent] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/nearly transparent}
\begin{codeexample}[]
\tikz{\fill[red]                (0,0)   rectangle (1,0.5);
      \fill[nearly transparent] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/semitransparent}
\begin{codeexample}[]
\tikz{\fill[red]             (0,0)   rectangle (1,0.5);
      \fill[semitransparent] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/nearly opaque}
\begin{codeexample}[]
\tikz{\fill[red]           (0,0)   rectangle (1,0.5);
      \fill[nearly opaque] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/very nearly opaque}
\begin{codeexample}[]
\tikz{\fill[red]                (0,0)   rectangle (1,0.5);
      \fill[very nearly opaque] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/ultra nearly opaque}
\begin{codeexample}[]
\tikz{\fill[red]                 (0,0)   rectangle (1,0.5);
      \fill[ultra nearly opaque] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}

  \begin{stylekey}{/tikz/opaque}
    This yields completely opaque drawings, which is the default.
\begin{codeexample}[]
\tikz{\fill[red]    (0,0)   rectangle (1,0.5);
      \fill[opaque] (0.5,0) rectangle (1.5,0.25); }
\end{codeexample}
  \end{stylekey}
\end{key}


\begin{key}{/tikz/fill opacity=\meta{value}}
  This option sets the opacity of fillings. In addition to filling
  operations, this opacity also applies to text and images.

  Note, again, that when you use PostScript as your output format,
  this option works only with recent versions of Ghostscript.

\begin{codeexample}[]
\begin{tikzpicture}[thick,fill opacity=0.5]
  \filldraw[fill=red]   (0:1cm)    circle (12mm);
  \filldraw[fill=green] (120:1cm)  circle (12mm);
  \filldraw[fill=blue]  (-120:1cm) circle (12mm);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \fill[red] (0,0) rectangle (3,2);

  \node                   at (0,0) {\huge A};
  \node[fill opacity=0.5] at (3,2) {\huge B};
\end{tikzpicture}
\end{codeexample}
\end{key}

\begin{key}{/tikz/text opacity=\meta{value}}
  Sets the opacity of text labels, overriding the |fill opacity| setting.
\begin{codeexample}[]
\begin{tikzpicture}[every node/.style={fill,draw}]
  \draw[line width=2mm,blue!50,line cap=round] (0,0) grid (3,2);

  \node[opacity=0.5] at (1.5,2) {Upper node};
  \node[draw opacity=0.8,fill opacity=0.2,text opacity=1]
    at (1.5,0) {Lower node};
\end{tikzpicture}
\end{codeexample}
\end{key}


Note the following effect: If you set up a certain opacity for stroking
or filling and you stroke or fill the same area twice, the effect
accumulates:

\begin{codeexample}[]
\begin{tikzpicture}[fill opacity=0.5]
  \fill[red] (0,0) circle (1);
  \fill[red] (1,0) circle (1);
\end{tikzpicture}
\end{codeexample}

Often, this is exactly what you intend, but not always. You can use
transparency groups, see the end of this section, to change this.



\subsection{Blend Modes}
\label{section-blend-modes}

A \emph{blend mode} specifies how colors mix when you paint on a
canvas. Normally, if you paint a red box on a green circle, the red
color will completely replace the green circle. However, in some
situations you might also wish the red color to somehow ``mix'' or
``blend'' with the green circle. We already saw that, using transparency,
we can draw something without completely obscuring the
background. \emph{Blending} is a similar operation, only here we mix
colors in more complicated ways.

\emph{Note:} Blending is a rather ``advanced'' feature of
\textsc{pdf}. Most renderers, let alone printers, will have trouble
rendering blending correctly.

\begin{key}{/tikz/blend mode=\meta{mode}}
  Sets the current blend mode to \meta{mode}. Here \meta{mode} must be
  one of the modes listed below. More details on these modes can also
  be found in  Section 7.2.4 of the \textsc{pdf} Specification, version 1.7.

  In the following example, the blend mode is only used and set inside
  a transparency group (see also
  Section~\ref{section-transparency-groups}). This is because most
  renderers (viewing 
  programs) have trouble rendering blending correctly otherwise. For
  instance, at the time of writing, the versions of Adobe's Reader and
  Apple's Preview render the following drawing very differently, if
  the transparency group is not used in the following example.

\begin{codeexample}[]
\tikz {
  \begin{scope}[transparency group]
    \begin{scope}[blend mode=screen] 
      \fill[red!90!black]   ( 90:.6) circle (1);
      \fill[green!80!black] (210:.6) circle (1);
      \fill[blue!90!black]  (330:.6) circle (1);
    \end{scope}
  \end{scope}
}
\end{codeexample}

  Because of the trouble with rendering blending correctly outside
  transparency groups, there is a special key that establishes a
  transparency group and sets a blend mode simultaneously:
  
  \begin{key}{/tikz/blend group=\meta{mode}}
    This key can only be used with a scope (like
    |transparency group|). It will cause the current scope to become a
    transparency group and, inside this group, the blend mode will be
    set to \meta{mode}.

\begin{codeexample}[]
\tikz [blend group=screen] {
  \fill[red!90!black]   ( 90:.6) circle (1);
  \fill[green!80!black] (210:.6) circle (1);
  \fill[blue!90!black]  (330:.6) circle (1);
}
\end{codeexample}
  \end{key}

  Here is an overview of the effects of the different available blend
  modes. In the examples, we always have three circles drawn on
  top of each other (as in the example code earlier): We start with a
  triple of pure red, green, and blue. Below it, we have a triple of
  light versions of these three colors (|red!50|, |green!50|, and
  |blue!50|). Next comes the triple  yellow, cyan, and magenta; again
  with a triple of light versions below it. The large example consists
  of three balls (produced using |ball color|) having the colors red,
  green, and blue, are drawn on top of each other just like the
  circles.  
  
  \definecolor{rg}{rgb}{1,1,0}
  \definecolor{gb}{rgb}{0,1,1}
  \definecolor{br}{rgb}{1,0,1}
  
  \def\makeline#1#2#3{\leavevmode
    \hbox to 4cm{#1\hss}\ \hbox to
    2cm{#2\hss}\ \begin{minipage}[t]{9cm}\raggedright#3\end{minipage}\par
    \textcolor{black!25}{\hrule height1pt}
  }

  \def\showmode#1#2{
    \makeline{
    \tikz [blend mode=#1,baseline=-.5ex] {
      \fill[red]      ( 90:.5em) circle (.75em);
      \fill[green]    (210:.5em) circle (.75em);
      \fill[blue]     (330:.5em) circle (.75em);
      \scoped[yshift=-2.5em]{
        \fill[red!50]   ( 90:.5em) circle (.75em);
        \fill[green!50] (210:.5em) circle (.75em);
        \fill[blue!50]  (330:.5em) circle (.75em);
      }
    }
    \tikz [blend mode=#1,baseline=-.5ex] {
      \fill[rg]   ( 90:.5em) circle (.75em);
      \fill[gb]  (210:.5em) circle (.75em);
      \fill[br]    (330:.5em) circle (.75em);
      \scoped[yshift=-2.5em]{
        \fill[rg!50]  ( 90:.5em) circle (.75em);
        \fill[gb!50]  (210:.5em) circle (.75em);
        \fill[br!50]  (330:.5em) circle (.75em);
      }
    }
    \tikz [blend mode=#1,baseline=-.5ex+1.25em] {
      \shade[ball color=red]      ( 90:1em) circle (1.5em);
      \shade[ball color=green]    (210:1em) circle (1.5em);
      \shade[ball color=blue]     (330:1em) circle (1.5em);
    }}{|#1|}{#2}}

  \medskip
  \makeline{\emph{Example}}{\emph{Mode}}{\emph{Explanations quoted from Table 7.2 of the
      \textsc{pdf} Specification, Version 1.7}}
  \showmode{normal}{When painting a pixel with a some color (called
    the ``source color''), the background color
      (called the ``backdrop'') is completely ignored.}
    \showmode{multiply}{Multiplies the backdrop and source color
      values. The result color is always at least as dark as
      either of the two constituent colors. Multiplying any color with
      black produces black; multiplying with white leaves the original
      color unchanged. Painting successive overlapping objects with a
      color other than black or white produces progressively darker
      colors.}
    \showmode{screen}{Multiplies the complements of the backdrop and
      source color       values, then complements the result. The
      result color is always 
      at least as light as either of the two constituent
      colors. Screening any color with white produces white; screening
      with black leaves the original color unchanged. The effect is
      similar to projecting multiple photographic slides
      simultaneously onto a single screen.}
    \showmode{overlay}{Multiplies or screens the colors, depending on
      the backdrop color value. Source colors overlay the backdrop
      while preserving its highlights and shadows. The backdrop color
      is not replaced but is mixed with the source color to reflect
      the lightness or darkness of the backdrop.}
    \showmode{darken}{Selects the darker of the backdrop and source
      colors. The backdrop is replaced with the source where the
      source is darker; otherwise, it is left unchanged.}
    \showmode{lighten}{Selects the lighter of the backdrop and source
      colors. The backdrop is replaced with the source where the
      source is lighter; otherwise, it is left unchanged.}
    \showmode{color dodge}{Brightens the backdrop color to reflect the
      source color. Painting with black produces no changes.}
    \showmode{color burn}{Darkens the backdrop color to reflect the
      source color. Painting with white produces no change.}
    \showmode{hard light}{Multiplies or screens the colors, depending
      on the source color value. The effect is similar to shining a
      harsh spotlight on the backdrop.}
    \showmode{soft light}{Darkens or lightens the colors, depending on
      the source color value. The effect is similar to shining a
      diffused spotlight on the backdrop.}
    \showmode{difference}{Subtracts the darker of the two constituent
      colors from the lighter color. Painting with white inverts the
      backdrop color; painting with black produces no change.}
    \showmode{exclusion}{Produces an effect similar to that of the
      Difference mode but lower in contrast. Painting with white
      inverts the backdrop color; painting with black produces no
      change.}
    \showmode{hue}{Creates a color with the hue of the source color
      and the saturation and luminosity of the backdrop color.} 
    \showmode{saturation}{Creates a color with the saturation of the
      source color and the hue and luminosity of the backdrop
      color. Painting with this mode in an area of the backdrop that
      is a pure gray (no saturation) produces no change.}
    \showmode{color}{Creates a color with the hue and saturation of
      the source color and the luminosity of the backdrop color. This
      preserves the gray levels of the backdrop and is useful for
      coloring monochrome images or tinting color images.}
    \showmode{luminosity}{Creates a color with the luminosity of the
      source color and the hue and saturation of the backdrop
      color. This produces an inverse effect to that of the Color
      mode.}
  
\end{key}



\subsection{Fadings}

For complicated graphics, uniform transparency settings are not always
sufficient. Suppose, for instance, that while you paint a picture, you
want the transparency to vary smoothly from completely opaque to
completely transparent. This is a ``shading-like'' transparency. For
such a form of transparency I will use the term \emph{fading} (as a
noun). They are also known as \emph{soft masks}, \emph{opacity masks},
\emph{masks}, or \emph{soft clips}.


\subsubsection{Creating Fadings}

How do we specify a fading? This is a bit of an art since the
underlying mechanism is quite powerful, but a bit difficult to use.

Let us start with a bit of terminology. A \emph{fading} specifies for
each point of an area the transparency of that point. This transparency
can by any number between 0 and 1. A \emph{fading picture} is a normal
graphic that, in a way to be described in a moment, determines the
transparency of points inside the fading. Each fading has an
underlying fading picture.

The fading picture is a normal graphic drawn using any of the normal
graphic drawing commands. A fading and its fading picture are related
as follows: Given any point of the fading, the transparency of this
point is determined by the luminosity of the fading picture at the
same position. The luminosity of a point determines ``how bright'' the
point is. The brighter the point in the fading picture, the more
opaque is the point in the fading. In particular, a white point of the
fading picture is completely opaque in the fading and a black point of
the fading picture is completely transparent in the fading. (The
background of the fading picture is always transparent in the fading
as if the background were black.)

It is rather counter-intuitive that a \emph{white} pixel of the fading
picture will be \emph{opaque} in the fading and a \emph{black} pixel
will be \emph{transparent}. For this reason, \tikzname\ defines a
color called |transparent| that is the same as |black|. The nice thing
about this definition is that the color
|transparent!|\meta{percentage} in the fading picture yields a
pixel that is \meta{percentage} percent transparent in the fading.

Turning a fading picture into a normal picture is achieved using the
following commands, which are \emph{only defined in the library},
namely the library |fadings|. So, to use them, you have to say
|\usetikzlibrary{fadings}| first.

\begin{environment}{{tikzfadingfrompicture}\oarg{options}}
  This command works like a |{tikzpicture}|, only the picture is not
  shown, but instead a fading is defined based on this picture. To set
  the name of the picture, use the |name| option (which is normally
  used to set the name of a node).
  \begin{key}{/tikz/name=\marg{name}}
    Use this option with the |{tikzfadingfrompicture}| environment to
    set the name of the fading. You \emph{must} provide this option.
  \end{key}

  The following shading is 2cm by 2cm and gets more and more
  transparent from left to right, but is 50\% transparent for a large
  circle in the middle.
{\tikzexternaldisable
\begin{codeexample}[]
\begin{tikzfadingfrompicture}[name=fade right]
  \shade[left color=transparent!0,
         right color=transparent!100] (0,0) rectangle (2,2);
  \fill[transparent!50] (1,1) circle (0.7);
\end{tikzfadingfrompicture}

% Now we use the fading in another picture:
\begin{tikzpicture}
  % Background
  \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
  \pattern [pattern=checkerboard,pattern color=black!30]
                   (-1.2,-1.2) rectangle (1.2,1.2);

  \fill [path fading=fade right,red] (-1,-1) rectangle (1,1);
\end{tikzpicture}
\end{codeexample}
  In the next example we create a fading picture that contains some
  text. When the fading is used, we only see the shading ``through
  it.''
\begin{codeexample}[]
\begin{tikzfadingfrompicture}[name=tikz]
  \node [text=transparent!20]
    {\fontfamily{ptm}\fontsize{45}{45}\bfseries\selectfont Ti\emph{k}Z};
\end{tikzfadingfrompicture}

% Now we use the fading in another picture:
\begin{tikzpicture}
  \fill [black!20] (-2,-1) rectangle (2,1);
  \pattern [pattern=checkerboard,pattern color=black!30]
                   (-2,-1) rectangle (2,1);

  \shade[path fading=tikz,fit fading=false,
         left color=blue,right color=black]
    (-2,-1) rectangle (2,1);
\end{tikzpicture}
\end{codeexample}
}%

  The same effect can also be achieved using knockout groups, see
  Section~\ref{section-transparency-groups}.
\end{environment}

\begin{plainenvironment}{{tikzfadingfrompicture}\oarg{options}}
  The plain\TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{tikzfadingfrompicture}\oarg{options}}
  The Con\TeX t version of the environment.
\end{contextenvironment}

\begin{command}{\tikzfading\oarg{options}}
  This command is used to define a fading similarly to the way a
  shading is defined. In the \meta{options} you should
  \begin{enumerate}
  \item use the |name=|\meta{name} option to set a name for the fading,
  \item use the |shading| option to set the name of the shading that
    you wish to use,
  \item extra options for setting the colors of the shading (typically
    you will set them to the color |transparent!|\meta{percentage}).
  \end{enumerate}
  Then, a new fading named \meta{name} will be created based on the
  shading.

\begin{codeexample}[]
\tikzfading[name=fade right,
            left color=transparent!0,
            right color=transparent!100]

% Now we use the fading in another picture:
\begin{tikzpicture}
  % Background
  \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
  \path [pattern=checkerboard,pattern color=black!30]
                   (-1.2,-1.2) rectangle (1.2,1.2);

  \fill [red,path fading=fade right] (-1,-1) rectangle (1,1);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\tikzfading[name=fade out,
            inner color=transparent!0,
            outer color=transparent!100]

% Now we use the fading in another picture:
\begin{tikzpicture}
  % Background
  \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
  \path [pattern=checkerboard,pattern color=black!30]
                   (-1.2,-1.2) rectangle (1.2,1.2);

  \fill [blue,path fading=fade out] (-1,-1) rectangle (1,1);
\end{tikzpicture}
\end{codeexample}
\end{command}



\subsubsection{Fading a Path}

A fading specifies for each pixel of a certain area how transparent
this pixel will be. The following options are used to install such a
fading for the current scope or path.

\pgfdeclarefading{fade down}{%
  \tikzset{top color=pgftransparent!0,bottom color=pgftransparent!100}
  \pgfuseshading{axis}
}
\pgfdeclarefading{fade inside}{%
  \tikzset{inner color=pgftransparent!90,outer color=pgftransparent!30}
  \pgfuseshading{radial}
}

\begin{key}{/tikz/path fading=\meta{name} (default \normalfont scope's setting)}
  This option tells \tikzname\ that the current path should be faded
  with the fading \meta{name}. If no \meta{name} is given, the
  \meta{name} set for the whole scope is used. Similarly to options
  like |draw| or |fill|, this option is reset for each path, so you
  have to add it to each path that should be faded. You can also
  specify |none| as \meta{name}, in which case fading for the path
  will be switched off in case it has been switched on by previous
  options or styles.
\begin{codeexample}[]
\begin{tikzpicture}[path fading=south]
  % Checker board
  \fill [black!20] (0,0) rectangle (4,3);
  \pattern [pattern=checkerboard,pattern color=black!30]
                   (0,0) rectangle (4,3);

  \fill [color=blue]                   (0.5,1.5) rectangle +(1,1);
  \fill [color=blue,path fading=north] (2.5,1.5) rectangle +(1,1);

  \fill [color=red,path fading]        (1,0.75) ellipse (.75 and .5);
  \fill [color=red]                    (3,0.75) ellipse (.75 and .5);
\end{tikzpicture}
\end{codeexample}

  \begin{key}{/tikz/fit fading=\meta{boolean} (default true, initially true)}
    When set to |true|, the fading is shifted and resized (in exactly
    the same way as a shading) so that it covers the current
    path. When set to |false|, the fading is only shifted so that it
    is centered on the path's center, but it is not resized. This can
    be useful for special-purpose fadings, for instance when you use a
    fading to ``punch out'' something.                                     
  \end{key}

  \begin{key}{/tikz/fading transform=\meta{transformation options}}
    The \meta{transformation options} are applied to the fading before
    it is used. For instance, if \meta{transformation options} is set
    to |rotate=90|, the fading is rotated by 90 degrees.
\begin{codeexample}[]
\begin{tikzpicture}[path fading=fade down]
  % Checker board
  \fill [black!20] (0,0) rectangle (4,1.5);
  \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,1.5);

  \fill [red,path fading,fading transform={rotate=90}]
    (1,0.75) ellipse (.75 and .5);
  \fill [red,path fading,fading transform={rotate=30}]
    (3,0.75) ellipse (.75 and .5);
\end{tikzpicture}
\end{codeexample}
  \end{key}

  \begin{key}{/tikz/fading angle=\meta{degree}}
    A shortcut for |fading transform={rotate=|\meta{degree}|}|.
  \end{key}

  Note that you can ``fade just about anything.'' In particular, you
  can fade a shading.

\begin{codeexample}[]
\begin{tikzpicture}
  % Checker board
  \fill [black!20] (0,0) rectangle (4,4);
  \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4);

  \shade [ball color=blue,path fading=south] (2,2) circle (1.8);
\end{tikzpicture}
\end{codeexample}

  The |fade inside| of the following example is more transparent in the middle than on the
  outside.

\begin{codeexample}[]
\tikzfading[name=fade inside,
            inner color=transparent!80,
            outer color=transparent!30]
\begin{tikzpicture}
  % Checker board
  \fill [black!20] (0,0) rectangle (4,4);
  \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4);

  \shade [ball color=red] (3,3) circle (0.8);
  \shade [ball color=white,path fading=fade inside] (2,2) circle (1.8);
\end{tikzpicture}
\end{codeexample}

  Note that adding the |path fading| option to a node fades the
  (background) path, not the text itself. To fade the text, you need
  to use a scope fading (see below).
\end{key}

Note that using fadings in conjunction with patterns can create
visually rather pleasing effects:
\begin{codeexample}[]
\tikzfading[name=middle,
            top color=transparent!50,
            bottom color=transparent!50,
            middle color=transparent!20]
\begin{tikzpicture}
  \node      [circle,circular drop shadow,
              pattern=horizontal lines dark blue,
              path fading=south,
              minimum size=3.6cm] {};
  \pattern   [path fading=north,
              pattern=horizontal lines dark gray]
    (0,0) circle (1.8cm);
  \pattern   [path fading=middle,
              pattern=crosshatch dots light steel blue]
    (0,0) circle (1.8cm);
\end{tikzpicture}
\end{codeexample}


\subsubsection{Fading a Scope}

In addition to fading individual paths, you may also wish to ``fade a
scope,'' that is, you may wish to install a fading that is used
globally to specify the transparency for all objects drawn inside a
scope. This effect can also be thought of as a ``soft clip'' and it
works in a similar way: You add the |scope fading| option to a path in
a scope -- typically the first one -- and then all subsequent drawings
in the scope are faded. You will use a |transparency group| in
conjunction, see the end of this section.

\begin{key}{/tikz/scope fading=\meta{fading}}
  In principle, this key works in exactly the same way as the
  |path fading| key. The only difference is, that the effect of the
  fading will persist after the current path till the end of the
  scope. Thus, the \meta{fading} is applied to all subsequent drawings
  in the current scope, not just to the current path. In this regard,
  the option works very much like the |clip| option. (Note, however,
  that, unlike the |clip| option, fadings to not accumulate unless a
  transparency group is used.)

  The keys |fit fading| and |fading transform| have the same effect as
  for |path fading|. Also that, just as for |path fading|, providing
  the |scope fading| option with a |{scope}| only sets the name of the
  fading to be used. You have to explicitly provide the |scope fading|
  with a path to actually install a fading.

\begin{codeexample}[]
\begin{tikzpicture}
  \fill [black!20] (-2,-2) rectangle (2,2);
  \pattern [pattern=checkerboard,pattern color=black!30]
                   (-2,-2) rectangle (2,2);

  % The bounding box of the shading:
  \draw [red] (-50bp,-50bp) rectangle (50bp,50bp);

  \path [scope fading=south,fit fading=false] (0,0);
  % fading is centered at its natural size

  \fill[red]   ( 90:1) circle (1);
  \fill[green] (210:1) circle (1);
  \fill[blue]  (330:1) circle (1);
\end{tikzpicture}
\end{codeexample}

  In the following example we resize the fading to the size of the
  whole picture:
\begin{codeexample}[]
\begin{tikzpicture}
  \fill [black!20] (-2,-2) rectangle (2,2);
  \pattern [pattern=checkerboard,pattern color=black!30]
                   (-2,-2) rectangle (2,2);

  \path [scope fading=south] (-2,-2) rectangle (2,2);

  \fill[red]   ( 90:1) circle (1);
  \fill[green] (210:1) circle (1);
  \fill[blue]  (330:1) circle (1);
\end{tikzpicture}
\end{codeexample}

  Scope fadings are also needed if you wish to fade a node.
\begin{codeexample}[]
\tikz \node [scope fading=south,fading angle=45,text width=3.5cm]
{
  This is some text that will fade out as we go right
  and down. It is pretty hard to achieve this effect in
  other ways.
};
\end{codeexample}

\end{key}


\subsection{Transparency Groups}
\label{section-transparency-groups}

Consider the following cross and sign. They ``look wrong'' because we
can see how they were constructed, while this is not really part of
the desired effect.

\begin{codeexample}[]
\begin{tikzpicture}[opacity=.5]
  \draw [line width=5mm] (0,0) -- (2,2);
  \draw [line width=5mm] (2,0) -- (0,2);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};

  \node [opacity=.5]
        at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
\end{tikzpicture}
\end{codeexample}

Transparency groups are used to render them correctly:

\begin{codeexample}[]
\begin{tikzpicture}[opacity=.5]
  \begin{scope}[transparency group]
    \draw [line width=5mm] (0,0) -- (2,2);
    \draw [line width=5mm] (2,0) -- (0,2);
  \end{scope}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};

  \begin{scope}[opacity=.5,transparency group]
    \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
      {Smoking};
  \end{scope}
\end{tikzpicture}
\end{codeexample}

\begin{key}{/tikz/transparency group=\oarg{options}}
  This option can be given to a |scope|. It will have the following
  effect: The scope's contents is stroked\,/\penalty0\,filled
  ``ignoring any outside transparency.'' This means, all previous
  transparency settings are ignored (you can still set transparency
  inside the group, but never mind). For instance, in the forbidden
  sign example, the whole sign is first painted (conceptually) like
  the image on the left hand side. Note that some pixels of the sign
  are painted multiple times (up to three times), but only the last
  color ``wins.''

  Then, when the scope is finished, it is painted as a whole. The
  \emph{fill} transparency settings are now applied to the resulting
  picture. For instance, the pixel that has been painted three times
  is just red at the end, so this red color will be blended with
  whatever is ``behind'' the group on the page.

\begin{codeexample}[]
\begin{tikzpicture}
  \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1);
  \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};

  \begin{scope}[transparency group,opacity=.5]
    \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
      {Smoking};
  \end{scope}
\end{tikzpicture}
\end{codeexample}

  Note that in the example, the |opacity=.5| is not active inside the
  transparency group: The group is only established at beginning of
  the scope and all options given to the |{scope}| environment are set
  before the group is established. To change the opacity \emph{inside}
  the group, you need to open another scope inside it or use the
  |opacity| key with a command inside the group:

\begin{codeexample}[]
\begin{tikzpicture}
  \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1);
  \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};

  \begin{scope}[transparency group,opacity=.5]
    \node (s) at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
    {Smoking};

    \draw [opacity=.5, line width=2ex, blue] (1.2,0) -- (2.8,0);
  \end{scope}
\end{tikzpicture}
\end{codeexample}

  The \meta{options} are a list of comma-separated options:
  \begin{itemize}
  \item \declare{|knockout|} When this option is given inside the
    \meta{options}, the group becomes a so-called \emph{knockout}
    group. This means, essentially, that inside the group everything
    is painted as if the ``opacity'' of a line or area were just
    another color channel. In particular, if you paint a pixel with
    opacity $0$ inside a knockout group, this pixel becomes perfectly
    transparent immediately. In contrast, painting a pixel with
    something of opacity 0 normally has no effect.

    Not all renderers, let alone printers, will support
    this. At the time of writing, Apple's Preview will not show the
    following correctly (you should see the text \tikzname\ in the
    middle): 
\begin{codeexample}[]
\begin{tikzpicture}
  \shade [left color=red,right color=blue] (-2,-1) rectangle (2,1);
  \begin{scope}[transparency group=knockout]
    \fill [white] (-1.9,-.9) rectangle (1.9,.9);
    \node [opacity=0,font=\fontfamily{ptm}\fontsize{45}{45}\bfseries]
          {Ti\emph{k}Z};
  \end{scope}
\end{tikzpicture}
\end{codeexample}
   In the example, we first draw a large shading and then, inside the
   transparency group ``overwrite'' most of this shading by a big
   white rectangle. The interesting part is the text of the node,
   which has opacity |0|. Normally, this would mean that nothing is
   shown. However, in a knockout group, we ``paint'' the text with an
   ``opacity zero'' color. The effect is that part of the totally
   opaque white rectangle gets overwritten by a perfectly transparent
   area (namely exactly the area taken up by the pixels of the
   text). When this whole knockout group is then placed on top of the
   shading, the shading will ``shine through'' at the knocked-out
   pixels.

  \item \declare{|isolated|}|=false| A group can be isolated or
    not. By default, they are isolated, since this is typically what you
    want. For details on what isolated groups are, exactly, see
    Section~7.3.4 of the \textsc{pdf} Specification, version 1.7.
  \end{itemize}

  Note that when a transparency group is created, \tikzname\ must
  correctly determine the size of the material inside the
  group. Usually, this is no problem, but when you use things like
  |overlay| or |transform canvas|, trouble may result. In this case,
  please consult Section~\ref{section-transparency} on how to sidestep
  this problem in such cases.
\end{key}




%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: