| 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: |