summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex
blob: 1243597df542686a5b1f424cf03a7a828f9822a2 (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
% 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-transparency}


For an introduction to the notion of transparency, fadings, and
transparency groups, please consult Section~\ref{section-tikz-transparency}.


\subsection{Specifying a Uniform Opacity}

Specifying a stroke and/or fill opacity is quite easy.

\begin{command}{\pgfsetstrokeopacity\marg{value}}
  Sets the opacity of stroking operations. The \meta{value} should be
  a number between |0| and |1|, where |1| means ``fully opaque'' and
  |0| means ``fully transparent.'' A value like |0.5| will cause paths
  to be stroked in a semitransparent way.

\begin{codeexample}[]
\begin{pgfpicture}
  \pgfsetlinewidth{5mm}
  \color{red}
  \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke}
  \color{black}
  \pgfsetstrokeopacity{0.5}
  \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
\end{command}


\begin{command}{\pgfsetfillopacity\marg{value}}
  Sets the opacity of filling operations. As for stroking, the
  \meta{value} should be a number between |0| and~|1|.

  The ``filling transparency'' will also be used for text and images.

\begin{codeexample}[]
\begin{tikzpicture}
  \pgfsetfillopacity{0.5}
  \fill[red]   (90:1cm)  circle (11mm);
  \fill[green] (210:1cm) circle (11mm);
  \fill[blue]  (-30:1cm) circle (11mm);
\end{tikzpicture}
\end{codeexample}
\end{command}

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}
  \pgfsetfillopacity{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{Specifying a Blend Mode}

To set the blend mode, use the following command:

\begin{command}{\pgfsetblendmode\marg{mode}}
  Sets the blend mode to one of the values described in
  Section~\ref{section-blend-modes}. As described there, blend modes
  are an advanced feature of \textsc{pdf} and not always rendered
  correctly.

  
\begin{codeexample}[]
\tikz [transparency group] {
  \pgfsetblendmode{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{command}


\subsection{Specifying a Fading}

The method used by \pgfname\ for specifying fadings is quite
general: You ``paint'' the fading using any of the standard graphics
commands. In more detail: You create a normal picture, which may even
contain text, image, and shadings. Then, you create a fading based on
this picture. For this, the \emph{luminosity} of each pixel of the
picture is analyzed (the brighter the pixel, the higher the luminosity
-- a black pixel has luminosity $0$, a white pixel has luminosity $1$,
a gray pixel has some intermediate value as does a red pixel). Then,
when the fading is used, the luminosity of the pixel determines the
opacity of the fading at that position. Positions in the fading where
the picture was black will be completely transparent, positions where
the picture was white will be completely opaque. Positions that have
not been painted at all in the picture are always completely
transparent.


\begin{command}{\pgfdeclarefading\marg{name}\marg{contents}}
  This command declares a fading named \meta{name} for later use. The
  ``picture'' on which the fading is based is given by the
  \meta{contents}. The \meta{contents} are normally typeset in a \TeX\
  box. The resulting box is then used as the ``picture.'' In
  particular, inside the \meta{contents} you must explicitly open a
  |{pgfpicture}| environment if you wish to use \pgfname\ commands.

  Let's start with an easy example. Our first fading picture is just
  some text:
\begin{codeexample}[]
\pgfdeclarefading{fading1}{\color{white}Ti\emph{k}Z}
\begin{tikzpicture}
  \fill [black!20] (0,0) rectangle (2,2);
  \fill [black!30] (0,0) arc (180:0:1);
  \pgfsetfading{fading1}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
  \fill [red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}
  What's happening here? The ``fading picture'' is mostly transparent,
  except for the pixels that are part of the word Ti\emph{k}Z. Now,
  these pixels are \emph{white} and, thus, have a high
  luminosity. This in turn means that these pixels of the fading will
  be highly opaque. For this reason, only those pixels of the big red
  rectangle ``shine through'' that are at the positions of these
  opaque pixels.

  It is somewhat counter-intuitive that the white pixels in a fading
  picture are opaque in a fading. For this reason, the color
  |pgftransparent| is defined to be the same as |black|. This allows
  one to write |pgftransparent| for completely transparent parts of a
  fading picture and |pgftransparent!0| for the opaque parts and
  things like |pgftransparent!20| for parts that are 20\%
  transparent.

  Furthermore, the color |pgftransparent!0| (which is the same as
  white and which corresponds to completely opaque) is installed at
  the beginning of a fading picture. Thus, in the above example the
  |\color{white}| was not really necessary.

  Next, let us create a fading that gets more and more transparent as
  we go from left to right. For this, we put a shading inside the
  fading picture that has the color |pgftransparent!0| at the
  left-hand side and the color |pgftransparent!100| at the right-hand
  side.
\begin{codeexample}[]
\pgfdeclarefading{fading2}
{\tikz \shade[left color=pgftransparent!0,
              right color=pgftransparent!100] (0,0) rectangle (2,2);}
\begin{tikzpicture}
  \fill [black!20] (0,0) rectangle (2,2);
  \fill [black!30] (0,0) arc (180:0:1);
  \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
  \fill [red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}

  In our final example, we create a fading that is based on a radial
  shading.
\begin{codeexample}[]
\pgfdeclareradialshading{myshading}{\pgfpointorigin}
{
  color(0mm)=(pgftransparent!0);
  color(5mm)=(pgftransparent!0);
  color(8mm)=(pgftransparent!100);
  color(15mm)=(pgftransparent!100)
}
\pgfdeclarefading{fading3}{\pgfuseshading{myshading}}
\begin{tikzpicture}
  \fill [black!20] (0,0) rectangle (2,2);
  \fill [black!30] (0,0) arc (180:0:1);
  \pgfsetfading{fading3}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
  \fill [red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}
\end{command}

After having declared a fading, we can use it. As for shadings, there
are different commands for using fadings:

\begin{command}{\pgfsetfading\marg{name}\marg{transformations}}
  This command sets the graphic state parameter ``fading'' to a
  previously defined fading \meta{name}. This graphic state works like
  other graphic states, that is, is persists till the end of the
  current scope or until a different transparency setting is chosen.

  When the fading is installed, it will be centered on the origin with
  its natural size. Anything outside the fading picture's original
  bounding box will be transparent and, thus, the fading effectively
  clips against this bounding box.

  The \meta{transformations} are applied to the fading before it is
  used. They contain normal \pgfname\ transformation commands like
  |\pgftransformshift|. You can also scale the fading using this
  command. Note, however, that the transformation needs to be inverted
  internally, which may result in inaccuracies and the following
  graphics may be slightly distorted if you use a strong
  \meta{transformation}.
\begin{codeexample}[]
\pgfdeclarefading{fading2}
{\tikz \shade[left color=pgftransparent!0,
              right color=pgftransparent!100] (0,0) rectangle (2,2);}
\begin{tikzpicture}
  \fill [black!20] (0,0) rectangle (2,2);
  \fill [black!30] (0,0) arc (180:0:1);
  \pgfsetfading{fading2}{}
  \fill [red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}
  \fill [black!20] (0,0) rectangle (2,2);
  \fill [black!30] (0,0) arc (180:0:1);
  \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}
                         \pgftransformrotate{20}}
  \fill [red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}
\end{command}

\begin{command}{\pgfsetfadingforcurrentpath\marg{name}\marg{transformations}}
  This command works like |\pgfsetfading|, but the fading is scaled
  and transformed according to the following rules:
  \begin{enumerate}
  \item
    If the current path is empty, the command has the same effect as
    |\pgfsetfading|.
  \item
    Otherwise it is assumed that the fading has a size of 100bp times
    100bp.
  \item
    The fading is resized and shifted (using appropriate
    transformations) such that the position
    $(25\mathrm{bp},25\mathrm{bp})$ lies at the lower-left corner of
    the current path and the position $(75\mathrm{bp},75\mathrm{bp})$
    lies at the upper-right corner of the current path.
  \end{enumerate}
  Note that these rules are the same as the ones used in
  |\pgfshadepath| for shadings. After these transformations, the
  \meta{transformations} are executed (typically a rotation).
\begin{codeexample}[]
\pgfdeclarehorizontalshading{shading}{100bp}
{ color(0pt)=(transparent!0);    color(25bp)=(transparent!0);
  color(75bp)=(transparent!100); color(100bp)=(transparent!100)}

\pgfdeclarefading{fading}{\pgfuseshading{shading}}

\begin{tikzpicture}
  \fill [black!20] (0,0) rectangle (2,2);
  \fill [black!30] (0,0) arc (180:0:1);

  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
  \pgfsetfadingforcurrentpath{fading}{}
  \pgfusepath{discard}

  \fill [red] (0,0) rectangle (2,1);

  \pgfpathrectangle{\pgfpoint{0cm}{1cm}}{\pgfpoint{2cm}{1cm}}
  \pgfsetfadingforcurrentpath{fading}{\pgftransformrotate{90}}
  \pgfusepath{discard}

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

\end{command}

\begin{command}{\pgfsetfadingforcurrentpathstroked\marg{name}\marg{transformations}}
  This command works line |\pgfsetfadingforcurrentpath|, only the
  current path is enlarged by the line width in both $x$- and
  $y$-direction. This is exactly the enlargement necessary to
  compensate for the fact that if the current path will be stroked,
  this much needs to be added around the path's bounding box to
  actually contain the path.
\begin{codeexample}[]
\begin{tikzpicture}
  \pgfsetlinewidth{2mm}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathlineto{\pgfpoint{2cm}{0cm}}
  \pgfsetfadingforcurrentpathstroked{fading}{}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\subsection{Transparency Groups}

Transparency groups are declared using the following commands.

\begin{environment}{{pgftransparencygroup}\opt{\oarg{options}}}
  This environment should only be used inside a |{pgfpicture}|. It has
  the following effect:
  \begin{enumerate}
  \item The \meta{environment contents} are stroked/filled
    ``ignoring any outside transparency.'' This means, all previous
    transparency settings are ignored (you can still set transparency
    inside the group, but never mind). This means that if in the
    \meta{environment contents} you stroke a pixel three times in
    black, it is just black. Stroking it white afterwards yields a
    white pixel, and so on.
  \item When the group 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
    in black and once in white is just white at the end, so this white
    color will be blended with whatever is ``behind'' the group on the
    page.
  \end{enumerate}
  
  The optional \meta{options} are keys that configure the transparency
  group further. Two keys are currently defined:
  \begin{itemize}
  \item \declare{|knockout|\opt{|=|\meta{true or false}}} Configures
    whether the group is a knockout group (if no argument is given,
    |true| is assumed; initially the key is always false, even when
    the command is used in a nested manner.) See
    Section~\ref{section-transparency-groups} for details on knockout groups.
  \item \declare{|isolated|\opt{|=|\meta{true or false}}} Similar, but
    configures whether the group is an isolated group. Also see
    Section~\ref{section-transparency-groups} for details on isolated groups.
  \end{itemize}
    
  Note that, depending on the driver, \pgfname\ may have to guess the
  size of the contents of the transparency group (because such a group
  is put in an XForm in \textsc{pdf} and a bounding box must be
  supplied). \pgfname\ will use normally use the size of the picture's
  bounding box at the end of the transparency group plus a safety
  margin of 1cm. Under normal circumstances, this will work nicely
  since the picture's bounding box contains everything
  anyway. However, if you have switched off the picture size tracking
  or if you are using canvas transformations, you may have to make
  sure that the bounding box is big enough. The trick is to locally
  create a picture that is ``large enough'' and then insert this
  picture into the main picture while ignoring the size. The following
  example shows how this is done:


{\tikzexternaldisable
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (2,2);

  % Stuff outside the picture, but still in a transparency group.
  \node [left,overlay] at (0,1) {
    \begin{tikzpicture}
      \pgfsetfillopacity{0.5}
      \pgftransparencygroup
      \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
        {Smoking};
      \endpgftransparencygroup
    \end{tikzpicture}
  };
\end{tikzpicture}
\end{codeexample}
}%


\begin{plainenvironment}{{pgftransparencygroup}}
  Plain \TeX\ version of the |{pgftransparencygroup}| environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgftransparencygroup}}
  This is the Con\TeX t version of the environment.
\end{contextenvironment}

\end{environment}



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