summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-base-transparency.tex
blob: de9c874ed0c51d2ab110cae9f6cfd3020d5382b6 (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
% Copyright 2019 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}{\textcolor{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}[preamble={\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}}
                         \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 like |\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}[preamble={\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}
  \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:

% TODO: Nesting tikzpictures is NOT supported
{\ifpgfmanualexternalize\tikzexternaldisable\fi
\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
\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: