diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex | 636 |
1 files changed, 636 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex new file mode 100644 index 00000000000..ba56a91a53e --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex @@ -0,0 +1,636 @@ +% 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 adress 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=examplefill,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 setup 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{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 to transparency of the 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 lumonisity 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 where 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{percantage} per cent 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 changes gets more and more + transparent from left to right, but is 50\% transparent for a large + circle in the middle. +\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} +\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 that 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} + +Aa 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 is 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 ``punsh 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 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 addtion 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 excatly 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} + +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} + This option can be given to a |scope|. It will have the following + effect: The scope's contents is 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). 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 + picutre. 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. + + Note that, depending on the driver, it is possible to directly put + objects in a transparency group that lie outside the picture. This + has to do with internal bounding box computations. + Section~\ref{section-transparency} explains how to sidestep this + problem. +\end{key} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |