Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-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-transparency}
13
14 For an introduction to the notion of transparency, fadings, and transparency
15 groups, please consult Section~\ref{section-tikz-transparency}.
16
17
18 \subsection{Specifying a Uniform Opacity}
19
20 Specifying a stroke and/or fill opacity is quite easy.
21
22 \begin{command}{\pgfsetstrokeopacity\marg{value}}
23 Sets the opacity of stroking operations. The \meta{value} should be a
24 number between |0| and |1|, where |1| means ``fully opaque'' and |0| means
25 ``fully transparent''. A value like |0.5| will cause paths to be stroked in
26 a semitransparent way.
27 %
28 \begin{codeexample}[]
29 \begin{pgfpicture}
30 \pgfsetlinewidth{5mm}
31 \color{red}
32 \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke}
33 \color{black}
34 \pgfsetstrokeopacity{0.5}
35 \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke}
36 \end{pgfpicture}
37 \end{codeexample}
38 %
39 \end{command}
40
41 \begin{command}{\pgfsetfillopacity\marg{value}}
42 Sets the opacity of filling operations. As for stroking, the \meta{value}
43 should be a number between |0| and~|1|.
44
45 The ``filling transparency'' will also be used for text and images.
46 %
47 \begin{codeexample}[]
48 \begin{tikzpicture}
49 \pgfsetfillopacity{0.5}
50 \fill[red] (90:1cm) circle (11mm);
51 \fill[green] (210:1cm) circle (11mm);
52 \fill[blue] (-30:1cm) circle (11mm);
53 \end{tikzpicture}
54 \end{codeexample}
55 %
56 \end{command}
57
58 Note the following effect: If you set up a certain opacity for stroking or
59 filling and you stroke or fill the same area twice, the effect accumulates:
60 %
61 \begin{codeexample}[]
62 \begin{tikzpicture}
63 \pgfsetfillopacity{0.5}
64 \fill[red] (0,0) circle (1);
65 \fill[red] (1,0) circle (1);
66 \end{tikzpicture}
67 \end{codeexample}
68
69 Often, this is exactly what you intend, but not always. You can use
70 transparency groups, see the end of this section, to change this.
71
72
73 \subsection{Specifying a Blend Mode}
74
75 To set the blend mode, use the following command:
76
77 \begin{command}{\pgfsetblendmode\marg{mode}}
78 Sets the blend mode to one of the values described in
79 Section~\ref{section-blend-modes}. As described there, blend modes are an
80 advanced feature of \textsc{pdf} and not always rendered correctly.
81 %
82 \begin{codeexample}[]
83 \tikz [transparency group] {
84 \pgfsetblendmode{screen}
85
86 \fill[red!90!black] ( 90:.6) circle (1);
87 \fill[green!80!black] (210:.6) circle (1);
88 \fill[blue!90!black] (330:.6) circle (1);
89 }
90 \end{codeexample}
91 %
92 \end{command}
93
94
95 \subsection{Specifying a Fading}
96
97 The method used by \pgfname\ for specifying fadings is quite general: You
98 ``paint'' the fading using any of the standard graphics commands. In more
99 detail: You create a normal picture, which may even contain text, image, and
100 shadings. Then, you create a fading based on this picture. For this, the
101 \emph{luminosity} of each pixel of the picture is analyzed (the brighter the
102 pixel, the higher the luminosity -- a black pixel has luminosity $0$, a white
103 pixel has luminosity $1$, a gray pixel has some intermediate value as does a
104 red pixel). Then, when the fading is used, the luminosity of the pixel
105 determines the opacity of the fading at that position. Positions in the fading
106 where the picture was black will be completely transparent, positions where the
107 picture was white will be completely opaque. Positions that have not been
108 painted at all in the picture are always completely transparent.
109
110 \begin{command}{\pgfdeclarefading\marg{name}\marg{contents}}
111 This command declares a fading named \meta{name} for later use. The
112 ``picture'' on which the fading is based is given by the \meta{contents}.
113 The \meta{contents} are normally typeset in a \TeX\ box. The resulting box
114 is then used as the ``picture''. In particular, inside the \meta{contents}
115 you must explicitly open a |{pgfpicture}| environment if you wish to use
116 \pgfname\ commands.
117
118 Let's start with an easy example. Our first fading picture is just some
119 text:
120 %
121 \begin{codeexample}[]
122 \pgfdeclarefading{fading1}{\textcolor{white}{Ti\emph{k}Z}}
123 \begin{tikzpicture}
124 \fill [black!20] (0,0) rectangle (2,2);
125 \fill [black!30] (0,0) arc (180:0:1);
126 \pgfsetfading{fading1}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
127 \fill [red] (0,0) rectangle (2,2);
128 \end{tikzpicture}
129 \end{codeexample}
130 %
131 What's happening here? The ``fading picture'' is mostly transparent, except
132 for the pixels that are part of the word Ti\emph{k}Z. Now, these pixels are
133 \emph{white} and, thus, have a high luminosity. This in turn means that
134 these pixels of the fading will be highly opaque. For this reason, only
135 those pixels of the big red rectangle ``shine through'' that are at the
136 positions of these opaque pixels.
137
138 It is somewhat counter-intuitive that the white pixels in a fading picture
139 are opaque in a fading. For this reason, the color |pgftransparent| is
140 defined to be the same as |black|. This allows one to write
141 |pgftransparent| for completely transparent parts of a fading picture and
142 |pgftransparent!0| for the opaque parts and things like |pgftransparent!20|
143 for parts that are 20\% transparent.
144
145 Furthermore, the color |pgftransparent!0| (which is the same as white and
146 which corresponds to completely opaque) is installed at the beginning of a
147 fading picture. Thus, in the above example the |\color{white}| was not
148 really necessary.
149
150 Next, let us create a fading that gets more and more transparent as we go
151 from left to right. For this, we put a shading inside the fading picture
152 that has the color |pgftransparent!0| at the left-hand side and the color
153 |pgftransparent!100| at the right-hand side.
154 %
155 \begin{codeexample}[]
156 \pgfdeclarefading{fading2}
157 {\tikz \shade[left color=pgftransparent!0,
158 right color=pgftransparent!100] (0,0) rectangle (2,2);}
159 \begin{tikzpicture}
160 \fill [black!20] (0,0) rectangle (2,2);
161 \fill [black!30] (0,0) arc (180:0:1);
162 \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
163 \fill [red] (0,0) rectangle (2,2);
164 \end{tikzpicture}
165 \end{codeexample}
166
167 In our final example, we create a fading that is based on a radial shading.
168 %
169 \begin{codeexample}[]
170 \pgfdeclareradialshading{myshading}{\pgfpointorigin}
171 {
172 color(0mm)=(pgftransparent!0);
173 color(5mm)=(pgftransparent!0);
174 color(8mm)=(pgftransparent!100);
175 color(15mm)=(pgftransparent!100)
176 }
177 \pgfdeclarefading{fading3}{\pgfuseshading{myshading}}
178 \begin{tikzpicture}
179 \fill [black!20] (0,0) rectangle (2,2);
180 \fill [black!30] (0,0) arc (180:0:1);
181 \pgfsetfading{fading3}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
182 \fill [red] (0,0) rectangle (2,2);
183 \end{tikzpicture}
184 \end{codeexample}
185 %
186 \end{command}
187
188 After having declared a fading, we can use it. As for shadings, there are
189 different commands for using fadings:
190
191 \begin{command}{\pgfsetfading\marg{name}\marg{transformations}}
192 This command sets the graphic state parameter ``fading'' to a previously
193 defined fading \meta{name}. This graphic state works like other graphic
194 states, that is, is persists till the end of the current scope or until a
195 different transparency setting is chosen.
196
197 When the fading is installed, it will be centered on the origin with its
198 natural size. Anything outside the fading picture's original bounding box
199 will be transparent and, thus, the fading effectively clips against this
200 bounding box.
201
202 The \meta{transformations} are applied to the fading before it is used.
203 They contain normal \pgfname\ transformation commands like
204 |\pgftransformshift|. You can also scale the fading using this command.
205 Note, however, that the transformation needs to be inverted internally,
206 which may result in inaccuracies and the following graphics may be slightly
207 distorted if you use a strong \meta{transformation}.
208 %
209 \begin{codeexample}[]
210 \pgfdeclarefading{fading2}
211 {\tikz \shade[left color=pgftransparent!0,
212 right color=pgftransparent!100] (0,0) rectangle (2,2);}
213 \begin{tikzpicture}
214 \fill [black!20] (0,0) rectangle (2,2);
215 \fill [black!30] (0,0) arc (180:0:1);
216 \pgfsetfading{fading2}{}
217 \fill [red] (0,0) rectangle (2,2);
218 \end{tikzpicture}
219 \end{codeexample}
220 %
221 \begin{codeexample}[preamble={\pgfdeclarefading{fading2}
222 {\tikz \shade[left color=pgftransparent!0,
223 right color=pgftransparent!100] (0,0) rectangle (2,2);}}]
224 \begin{tikzpicture}
225 \fill [black!20] (0,0) rectangle (2,2);
226 \fill [black!30] (0,0) arc (180:0:1);
227 \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}
228 \pgftransformrotate{20}}
229 \fill [red] (0,0) rectangle (2,2);
230 \end{tikzpicture}
231 \end{codeexample}
232 %
233 \end{command}
234
235 \begin{command}{\pgfsetfadingforcurrentpath\marg{name}\marg{transformations}}
236 This command works like |\pgfsetfading|, but the fading is scaled and
237 transformed according to the following rules:
238 %
239 \begin{enumerate}
240 \item If the current path is empty, the command has the same effect as
241 |\pgfsetfading|.
242 \item Otherwise it is assumed that the fading has a size of 100bp times
243 100bp.
244 \item The fading is resized and shifted (using appropriate
245 transformations) such that the position
246 $(25\mathrm{bp},25\mathrm{bp})$ lies at the lower-left corner of
247 the current path and the position $(75\mathrm{bp},75\mathrm{bp})$
248 lies at the upper-right corner of the current path.
249 \end{enumerate}
250 %
251 Note that these rules are the same as the ones used in |\pgfshadepath| for
252 shadings. After these transformations, the \meta{transformations} are
253 executed (typically a rotation).
254 %
255 \begin{codeexample}[]
256 \pgfdeclarehorizontalshading{shading}{100bp}
257 { color(0pt)=(transparent!0); color(25bp)=(transparent!0);
258 color(75bp)=(transparent!100); color(100bp)=(transparent!100)}
259
260 \pgfdeclarefading{fading}{\pgfuseshading{shading}}
261
262 \begin{tikzpicture}
263 \fill [black!20] (0,0) rectangle (2,2);
264 \fill [black!30] (0,0) arc (180:0:1);
265
266 \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
267 \pgfsetfadingforcurrentpath{fading}{}
268 \pgfusepath{discard}
269
270 \fill [red] (0,0) rectangle (2,1);
271
272 \pgfpathrectangle{\pgfpoint{0cm}{1cm}}{\pgfpoint{2cm}{1cm}}
273 \pgfsetfadingforcurrentpath{fading}{\pgftransformrotate{90}}
274 \pgfusepath{discard}
275
276 \fill [red] (0,1) rectangle (2,2);
277 \end{tikzpicture}
278 \end{codeexample}
279 %
280 \end{command}
281
282 \begin{command}{\pgfsetfadingforcurrentpathstroked\marg{name}\marg{transformations}}
283 This command works like |\pgfsetfadingforcurrentpath|, only the current
284 path is enlarged by the line width in both $x$- and $y$-direction. This is
285 exactly the enlargement necessary to compensate for the fact that if the
286 current path will be stroked, this much needs to be added around the path's
287 bounding box to actually contain the path.
288 %
289 \begin{codeexample}[preamble={\pgfdeclarehorizontalshading{shading}{100bp}
290 { color(0pt)=(transparent!0); color(25bp)=(transparent!0);
291 color(75bp)=(transparent!100); color(100bp)=(transparent!100)}
292 %
293 \pgfdeclarefading{fading}{\pgfuseshading{shading}}}]
294 \begin{tikzpicture}
295 \pgfsetlinewidth{2mm}
296 \pgfpathmoveto{\pgfpointorigin}
297 \pgfpathlineto{\pgfpoint{2cm}{0cm}}
298 \pgfsetfadingforcurrentpathstroked{fading}{}
299 \pgfusepath{stroke}
300 \end{tikzpicture}
301 \end{codeexample}
302 %
303 \end{command}
304
305
306 \subsection{Transparency Groups}
307
308 Transparency groups are declared using the following commands.
309
310 \begin{environment}{{pgftransparencygroup}\opt{\oarg{options}}}
311 This environment should only be used inside a |{pgfpicture}|. It has the
312 following effect:
313 %
314 \begin{enumerate}
315 \item The \meta{environment contents} are stroked/filled ``ignoring any
316 outside transparency''. This means, all previous transparency
317 settings are ignored (you can still set transparency inside the
318 group, but never mind). This means that if in the \meta{environment
319 contents} you stroke a pixel three times in black, it is just
320 black. Stroking it white afterwards yields a white pixel, and so
321 on.
322 \item When the group is finished, it is painted as a whole. The
323 \emph{fill} transparency settings are now applied to the resulting
324 picture. For instance, the pixel that has been painted three times
325 in black and once in white is just white at the end, so this white
326 color will be blended with whatever is ``behind'' the group on the
327 page.
328 \end{enumerate}
329
330 The optional \meta{options} are keys that configure the transparency group
331 further. Two keys are currently defined:
332 %
333 \begin{itemize}
334 \item \declare{|knockout|\opt{|=|\meta{true or false}}} Configures
335 whether the group is a knockout group (if no argument is given,
336 |true| is assumed; initially the key is always false, even when the
337 command is used in a nested manner.) See
338 Section~\ref{section-transparency-groups} for details on knockout
339 groups.
340 \item \declare{|isolated|\opt{|=|\meta{true or false}}} Similar, but
341 configures whether the group is an isolated group. Also see
342 Section~\ref{section-transparency-groups} for details on isolated
343 groups.
344 \end{itemize}
345
346 Note that, depending on the driver, \pgfname\ may have to guess the size of
347 the contents of the transparency group (because such a group is put in an
348 XForm in \textsc{pdf} and a bounding box must be supplied). \pgfname\ will
349 use normally use the size of the picture's bounding box at the end of the
350 transparency group plus a safety margin of 1cm. Under normal circumstances,
351 this will work nicely since the picture's bounding box contains everything
352 anyway. However, if you have switched off the picture size tracking or if
353 you are using canvas transformations, you may have to make sure that the
354 bounding box is big enough. The trick is to locally create a picture that
355 is ``large enough'' and then insert this picture into the main picture
356 while ignoring the size. The following example shows how this is done:
357
358 % TODO: Nesting tikzpictures is NOT supported
359 {\ifpgfmanualexternalize\tikzexternaldisable\fi
360 \begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
361 \begin{tikzpicture}
362 \draw [help lines] (0,0) grid (2,2);
363
364 % Stuff outside the picture, but still in a transparency group.
365 \node [left,overlay] at (0,1) {
366 \begin{tikzpicture}
367 \pgfsetfillopacity{0.5}
368 \pgftransparencygroup
369 \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
370 {Smoking};
371 \endpgftransparencygroup
372 \end{tikzpicture}
373 };
374 \end{tikzpicture}
375 \end{codeexample}
376 }%
377
378 \begin{plainenvironment}{{pgftransparencygroup}}
379 Plain \TeX\ version of the |{pgftransparencygroup}| environment.
380 \end{plainenvironment}
381
382 \begin{contextenvironment}{{pgftransparencygroup}}
383 This is the Con\TeX t version of the environment.
384 \end{contextenvironment}
385 \end{environment}
386
387
388 %%% Local Variables:
389 %%% mode: latex
390 %%% TeX-master: "pgfmanual"
391 %%% End: