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 | 851 |
1 files changed, 417 insertions, 434 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 index 3891d152987..8d817df5aeb 100644 --- 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 @@ -9,153 +9,147 @@ \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. +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. -At the end of the section we address 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. +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. -\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. +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 address 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. +\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. + 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=yellow!80!black,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. +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. + 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. + \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} + \end{stylekey} - \begin{stylekey}{/tikz/very nearly transparent} + \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} + \end{stylekey} - \begin{stylekey}{/tikz/nearly transparent} + \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} + \end{stylekey} - \begin{stylekey}{/tikz/semitransparent} + \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} + \end{stylekey} - \begin{stylekey}{/tikz/nearly opaque} + \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} + \end{stylekey} - \begin{stylekey}{/tikz/very nearly opaque} + \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} + \end{stylekey} - \begin{stylekey}{/tikz/ultra nearly opaque} + \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} + \end{stylekey} - \begin{stylekey}{/tikz/opaque} - This yields completely opaque drawings, which is the default. + \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{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. + 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); @@ -172,10 +166,12 @@ option |opacity| sets both at the same time. \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. + 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); @@ -185,13 +181,12 @@ option |opacity| sets both at the same time. at (1.5,0) {Lower node}; \end{tikzpicture} \end{codeexample} + % \end{key} - -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: - +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}[fill opacity=0.5] \fill[red] (0,0) circle (1); @@ -203,41 +198,37 @@ 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{Blend Modes} \label{section-blend-modes} -A \emph{blend mode} specifies how colors mix when you paint on a -canvas. Normally, if you paint a red box on a green circle, the red -color will completely replace the green circle. However, in some -situations you might also wish the red color to somehow ``mix'' or -``blend'' with the green circle. We already saw that, using transparency, -we can draw something without completely obscuring the -background. \emph{Blending} is a similar operation, only here we mix -colors in more complicated ways. +A \emph{blend mode} specifies how colors mix when you paint on a canvas. +Normally, if you paint a red box on a green circle, the red color will +completely replace the green circle. However, in some situations you might also +wish the red color to somehow ``mix'' or ``blend'' with the green circle. We +already saw that, using transparency, we can draw something without completely +obscuring the background. \emph{Blending} is a similar operation, only here we +mix colors in more complicated ways. -\emph{Note:} Blending is a rather ``advanced'' feature of -\textsc{pdf}. Most renderers, let alone printers, will have trouble -rendering blending correctly. +\emph{Note:} Blending is a rather ``advanced'' feature of \textsc{pdf}. Most +renderers, let alone printers, will have trouble rendering blending correctly. \begin{key}{/tikz/blend mode=\meta{mode}} - Sets the current blend mode to \meta{mode}. Here \meta{mode} must be - one of the modes listed below. More details on these modes can also - be found in Section 7.2.4 of the \textsc{pdf} Specification, version 1.7. - - In the following example, the blend mode is only used and set inside - a transparency group (see also - Section~\ref{section-transparency-groups}). This is because most - renderers (viewing - programs) have trouble rendering blending correctly otherwise. For - instance, at the time of writing, the versions of Adobe's Reader and - Apple's Preview render the following drawing very differently, if - the transparency group is not used in the following example. - + Sets the current blend mode to \meta{mode}. Here \meta{mode} must be one of + the modes listed below. More details on these modes can also be found in + Section~7.2.4 of the \textsc{pdf} Specification, version~1.7. + + In the following example, the blend mode is only used and set inside a + transparency group (see also Section~\ref{section-transparency-groups}). + This is because most renderers (viewing programs) have trouble rendering + blending correctly otherwise. For instance, at the time of writing, the + versions of Adobe's Reader and Apple's Preview render the following drawing + very differently, if the transparency group is not used in the following + example. + % \begin{codeexample}[] \tikz { \begin{scope}[transparency group] - \begin{scope}[blend mode=screen] + \begin{scope}[blend mode=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); @@ -246,16 +237,15 @@ rendering blending correctly. } \end{codeexample} - Because of the trouble with rendering blending correctly outside - transparency groups, there is a special key that establishes a - transparency group and sets a blend mode simultaneously: - - \begin{key}{/tikz/blend group=\meta{mode}} - This key can only be used with a scope (like - |transparency group|). It will cause the current scope to become a - transparency group and, inside this group, the blend mode will be - set to \meta{mode}. + Because of the trouble with rendering blending correctly outside + transparency groups, there is a special key that establishes a transparency + group and sets a blend mode simultaneously: + \begin{key}{/tikz/blend group=\meta{mode}} + This key can only be used with a scope (like |transparency group|). It + will cause the current scope to become a transparency group and, inside + this group, the blend mode will be set to \meta{mode}. + % \begin{codeexample}[] \tikz [blend group=screen] { \fill[red!90!black] ( 90:.6) circle (1); @@ -263,186 +253,177 @@ rendering blending correctly. \fill[blue!90!black] (330:.6) circle (1); } \end{codeexample} - \end{key} - - Here is an overview of the effects of the different available blend - modes. In the examples, we always have three circles drawn on - top of each other (as in the example code earlier): We start with a - triple of pure red, green, and blue. Below it, we have a triple of - light versions of these three colors (|red!50|, |green!50|, and - |blue!50|). Next comes the triple yellow, cyan, and magenta; again - with a triple of light versions below it. The large example consists - of three balls (produced using |ball color|) having the colors red, - green, and blue, are drawn on top of each other just like the - circles. - - \definecolor{rg}{rgb}{1,1,0} - \definecolor{gb}{rgb}{0,1,1} - \definecolor{br}{rgb}{1,0,1} - - \def\makeline#1#2#3{\leavevmode - \hbox to 4cm{#1\hss}\ \hbox to - 2cm{#2\hss}\ \begin{minipage}[t]{9cm}\raggedright#3\end{minipage}\par - \textcolor{black!25}{\hrule height1pt} - } - - \def\showmode#1#2{ - \makeline{ - \tikz [blend mode=#1,baseline=-.5ex] { - \fill[red] ( 90:.5em) circle (.75em); - \fill[green] (210:.5em) circle (.75em); - \fill[blue] (330:.5em) circle (.75em); - \scoped[yshift=-2.5em]{ - \fill[red!50] ( 90:.5em) circle (.75em); - \fill[green!50] (210:.5em) circle (.75em); - \fill[blue!50] (330:.5em) circle (.75em); - } + \end{key} + + Here is an overview of the effects of the different available blend modes. + In the examples, we always have three circles drawn on top of each other + (as in the example code earlier): We start with a triple of pure red, + green, and blue. Below it, we have a triple of light versions of these + three colors (|red!50|, |green!50|, and |blue!50|). Next comes the triple + yellow, cyan, and magenta; again with a triple of light versions below it. + The large example consists of three balls (produced using |ball color|) + having the colors red, green, and blue, are drawn on top of each other just + like the circles. + + \definecolor{rg}{rgb}{1,1,0} + \definecolor{gb}{rgb}{0,1,1} + \definecolor{br}{rgb}{1,0,1} + + \def\makeline#1#2#3{\leavevmode + \hbox to 40mm{#1\hss}\ \hbox to + 20.5mm{#2\hss}\ \begin{minipage}[t]{88.5mm}\raggedright#3\end{minipage}\par + \textcolor{black!25}{\hrule height1pt} } - \tikz [blend mode=#1,baseline=-.5ex] { - \fill[rg] ( 90:.5em) circle (.75em); - \fill[gb] (210:.5em) circle (.75em); - \fill[br] (330:.5em) circle (.75em); - \scoped[yshift=-2.5em]{ - \fill[rg!50] ( 90:.5em) circle (.75em); - \fill[gb!50] (210:.5em) circle (.75em); - \fill[br!50] (330:.5em) circle (.75em); - } + + \def\showmode#1#2{ + \makeline{ + \tikz [blend mode=#1,baseline=-.5ex] { + \fill[red] ( 90:.5em) circle (.75em); + \fill[green] (210:.5em) circle (.75em); + \fill[blue] (330:.5em) circle (.75em); + \scoped[yshift=-2.5em]{ + \fill[red!50] ( 90:.5em) circle (.75em); + \fill[green!50] (210:.5em) circle (.75em); + \fill[blue!50] (330:.5em) circle (.75em); + } + } + \tikz [blend mode=#1,baseline=-.5ex] { + \fill[rg] ( 90:.5em) circle (.75em); + \fill[gb] (210:.5em) circle (.75em); + \fill[br] (330:.5em) circle (.75em); + \scoped[yshift=-2.5em]{ + \fill[rg!50] ( 90:.5em) circle (.75em); + \fill[gb!50] (210:.5em) circle (.75em); + \fill[br!50] (330:.5em) circle (.75em); + } + } + \tikz [blend mode=#1,baseline=-.5ex+1.25em] { + \shade[ball color=red] ( 90:1em) circle (1.5em); + \shade[ball color=green] (210:1em) circle (1.5em); + \shade[ball color=blue] (330:1em) circle (1.5em); + }}{\verb|#1|}{#2}% + % this argument was changed from {|#1|} + % --> see <https://sourceforge.net/p/pgf/bugs/486/> } - \tikz [blend mode=#1,baseline=-.5ex+1.25em] { - \shade[ball color=red] ( 90:1em) circle (1.5em); - \shade[ball color=green] (210:1em) circle (1.5em); - \shade[ball color=blue] (330:1em) circle (1.5em); - }}{|#1|}{#2}} - - \medskip - \makeline{\emph{Example}}{\emph{Mode}}{\emph{Explanations quoted from Table 7.2 of the - \textsc{pdf} Specification, Version 1.7}} - \showmode{normal}{When painting a pixel with a some color (called - the ``source color''), the background color - (called the ``backdrop'') is completely ignored.} - \showmode{multiply}{Multiplies the backdrop and source color - values. The result color is always at least as dark as - either of the two constituent colors. Multiplying any color with - black produces black; multiplying with white leaves the original - color unchanged. Painting successive overlapping objects with a - color other than black or white produces progressively darker - colors.} - \showmode{screen}{Multiplies the complements of the backdrop and - source color values, then complements the result. The - result color is always - at least as light as either of the two constituent - colors. Screening any color with white produces white; screening - with black leaves the original color unchanged. The effect is - similar to projecting multiple photographic slides - simultaneously onto a single screen.} - \showmode{overlay}{Multiplies or screens the colors, depending on - the backdrop color value. Source colors overlay the backdrop - while preserving its highlights and shadows. The backdrop color - is not replaced but is mixed with the source color to reflect - the lightness or darkness of the backdrop.} - \showmode{darken}{Selects the darker of the backdrop and source - colors. The backdrop is replaced with the source where the - source is darker; otherwise, it is left unchanged.} - \showmode{lighten}{Selects the lighter of the backdrop and source - colors. The backdrop is replaced with the source where the - source is lighter; otherwise, it is left unchanged.} - \showmode{color dodge}{Brightens the backdrop color to reflect the - source color. Painting with black produces no changes.} - \showmode{color burn}{Darkens the backdrop color to reflect the - source color. Painting with white produces no change.} - \showmode{hard light}{Multiplies or screens the colors, depending - on the source color value. The effect is similar to shining a - harsh spotlight on the backdrop.} - \showmode{soft light}{Darkens or lightens the colors, depending on - the source color value. The effect is similar to shining a - diffused spotlight on the backdrop.} - \showmode{difference}{Subtracts the darker of the two constituent - colors from the lighter color. Painting with white inverts the - backdrop color; painting with black produces no change.} - \showmode{exclusion}{Produces an effect similar to that of the - Difference mode but lower in contrast. Painting with white - inverts the backdrop color; painting with black produces no - change.} - \showmode{hue}{Creates a color with the hue of the source color - and the saturation and luminosity of the backdrop color.} - \showmode{saturation}{Creates a color with the saturation of the - source color and the hue and luminosity of the backdrop - color. Painting with this mode in an area of the backdrop that - is a pure gray (no saturation) produces no change.} - \showmode{color}{Creates a color with the hue and saturation of - the source color and the luminosity of the backdrop color. This - preserves the gray levels of the backdrop and is useful for - coloring monochrome images or tinting color images.} - \showmode{luminosity}{Creates a color with the luminosity of the - source color and the hue and saturation of the backdrop - color. This produces an inverse effect to that of the Color - mode.} - -\end{key} + \medskip + \makeline{\emph{Example}}{\emph{Mode}}{\emph{Explanations quoted from + Table~7.2 of the \textsc{pdf} Specification, Version~1.7}} + \showmode{normal}{When painting a pixel with a some color (called the + ``source color''), the background color (called the ``backdrop'') is + completely ignored.} + \showmode{multiply}{Multiplies the backdrop and source color values. The + result color is always at least as dark as either of the two + constituent colors. Multiplying any color with black produces black; + multiplying with white leaves the original color unchanged. Painting + successive overlapping objects with a color other than black or white + produces progressively darker colors.} + \showmode{screen}{Multiplies the complements of the backdrop and source + color values, then complements the result. The result color is always + at least as light as either of the two constituent colors. Screening + any color with white produces white; screening with black leaves the + original color unchanged. The effect is similar to projecting multiple + photographic slides simultaneously onto a single screen.} + \showmode{overlay}{Multiplies or screens the colors, depending on the + backdrop color value. Source colors overlay the backdrop while + preserving its highlights and shadows. The backdrop color is not + replaced but is mixed with the source color to reflect the lightness or + darkness of the backdrop.} + \showmode{darken}{Selects the darker of the backdrop and source colors. The + backdrop is replaced with the source where the source is darker; + otherwise, it is left unchanged.} + \showmode{lighten}{Selects the lighter of the backdrop and source colors. + The backdrop is replaced with the source where the source is lighter; + otherwise, it is left unchanged.} + \showmode{color dodge}{Brightens the backdrop color to reflect the source + color. Painting with black produces no changes.} + \showmode{color burn}{Darkens the backdrop color to reflect the source + color. Painting with white produces no change.} + \showmode{hard light}{Multiplies or screens the colors, depending on the + source color value. The effect is similar to shining a harsh spotlight + on the backdrop.} + \showmode{soft light}{Darkens or lightens the colors, depending on the + source color value. The effect is similar to shining a diffused + spotlight on the backdrop.} + \showmode{difference}{Subtracts the darker of the two constituent colors + from the lighter color. Painting with white inverts the backdrop color; + painting with black produces no change.} + \showmode{exclusion}{Produces an effect similar to that of the Difference + mode but lower in contrast. Painting with white inverts the backdrop + color; painting with black produces no change.} + \showmode{hue}{Creates a color with the hue of the source color and the + saturation and luminosity of the backdrop color.} + \showmode{saturation}{Creates a color with the saturation of the source + color and the hue and luminosity of the backdrop color. Painting with + this mode in an area of the backdrop that is a pure gray (no + saturation) produces no change.} + \showmode{color}{Creates a color with the hue and saturation of the source + color and the luminosity of the backdrop color. This preserves the gray + levels of the backdrop and is useful for coloring monochrome images or + tinting color images.} + \showmode{luminosity}{Creates a color with the luminosity of the source + color and the hue and saturation of the backdrop color. This produces + an inverse effect to that of the Color mode.} +\end{key} \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}. +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 the transparency of that 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 luminosity 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 were 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{percentage} percent 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. +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 the transparency of that 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 +luminosity 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 were 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{percentage} percent 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 gets more and more - transparent from left to right, but is 50\% transparent for a large - circle in the middle. + 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 gets more and more transparent from + left to right, but is 50\% transparent for a large circle in the middle. + % {\tikzexternaldisable \begin{codeexample}[] \begin{tikzfadingfrompicture}[name=fade right] @@ -461,9 +442,10 @@ namely the library |fadings|. So, to use them, you have to say \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.'' + % + 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] @@ -483,31 +465,32 @@ namely the library |fadings|. So, to use them, you have to say \end{codeexample} }% - The same effect can also be achieved using knockout groups, see - Section~\ref{section-transparency-groups}. + The same effect can also be achieved using knockout groups, see + Section~\ref{section-transparency-groups}. \end{environment} \begin{plainenvironment}{{tikzfadingfrompicture}\oarg{options}} - The plain\TeX\ version of the environment. + The plain\TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{tikzfadingfrompicture}\oarg{options}} - The Con\TeX t version of the environment. + 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 the 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. - + This command is used to define a fading similarly to the 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, @@ -539,15 +522,15 @@ namely the library |fadings|. So, to use them, you have to say \fill [blue,path fading=fade out] (-1,-1) rectangle (1,1); \end{tikzpicture} \end{codeexample} + % \end{command} - \subsubsection{Fading a Path} -A 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. +A 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} @@ -559,14 +542,14 @@ fading for the current scope or path. } \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. + 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 @@ -582,19 +565,20 @@ fading for the current scope or path. \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 it 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 ``punch out'' something. - \end{key} + \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 it 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 ``punch + 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{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 @@ -607,15 +591,15 @@ fading for the current scope or path. (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} + \end{key} - Note that you can ``fade just about anything.'' In particular, you - can fade a shading. + \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 @@ -626,9 +610,9 @@ fading for the current scope or path. \end{tikzpicture} \end{codeexample} - The |fade inside| of the following example is more transparent in the middle than on the - outside. - + The |fade inside| of the following example is more transparent in the + middle than on the outside. + % \begin{codeexample}[] \tikzfading[name=fade inside, inner color=transparent!80, @@ -643,13 +627,14 @@ fading for the current scope or path. \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). + 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: +Note that using fadings in conjunction with patterns can create visually rather +pleasing effects: +% \begin{codeexample}[] \tikzfading[name=middle, top color=transparent!50, @@ -672,31 +657,29 @@ visually rather pleasing effects: \subsubsection{Fading a Scope} -In addition 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. +In addition 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 exactly 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. - + In principle, this key works in exactly 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); @@ -715,8 +698,9 @@ conjunction, see the end of this section. \end{tikzpicture} \end{codeexample} - In the following example we resize the fading to the size of the - whole picture: + 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); @@ -731,7 +715,8 @@ conjunction, see the end of this section. \end{tikzpicture} \end{codeexample} - Scope fadings are also needed if you wish to fade a node. + 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] { @@ -740,17 +725,16 @@ conjunction, see the end of this section. other ways. }; \end{codeexample} - + % \end{key} \subsection{Transparency Groups} \label{section-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. - +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); @@ -768,7 +752,7 @@ the desired effect. \end{codeexample} Transparency groups are used to render them correctly: - +% \begin{codeexample}[] \begin{tikzpicture}[opacity=.5] \begin{scope}[transparency group] @@ -790,22 +774,21 @@ Transparency groups are used to render them correctly: \end{codeexample} \begin{key}{/tikz/transparency group=\oarg{options}} - This option can be given to a |scope|. It will have the following - effect: The scope's contents is stroked\,/\penalty0\,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 - picture. 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. - + This option can be given to a |scope|. It will have the following effect: + The scope's contents is stroked\,/\penalty0\,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 picture. 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. + % \begin{codeexample}[] \begin{tikzpicture} \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1); @@ -818,13 +801,13 @@ Transparency groups are used to render them correctly: \end{tikzpicture} \end{codeexample} - Note that in the example, the |opacity=.5| is not active inside the - transparency group: The group is only established at beginning of - the scope and all options given to the |{scope}| environment are set - before the group is established. To change the opacity \emph{inside} - the group, you need to open another scope inside it or use the - |opacity| key with a command inside the group: - + Note that in the example, the |opacity=.5| is not active inside the + transparency group: The group is only established at beginning of the scope + and all options given to the |{scope}| environment are set before the group + is established. To change the opacity \emph{inside} the group, you need to + open another scope inside it or use the |opacity| key with a command inside + the group: + % \begin{codeexample}[] \begin{tikzpicture} \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1); @@ -839,21 +822,22 @@ Transparency groups are used to render them correctly: \end{tikzpicture} \end{codeexample} - The \meta{options} are a list of comma-separated options: - \begin{itemize} - \item \declare{|knockout|} When this option is given inside the - \meta{options}, the group becomes a so-called \emph{knockout} - group. This means, essentially, that inside the group everything - is painted as if the ``opacity'' of a line or area were just - another color channel. In particular, if you paint a pixel with - opacity $0$ inside a knockout group, this pixel becomes perfectly - transparent immediately. In contrast, painting a pixel with - something of opacity 0 normally has no effect. + The \meta{options} are a list of comma-separated options: + % + \begin{itemize} + \item \declare{|knockout|} When this option is given inside the + \meta{options}, the group becomes a so-called \emph{knockout} + group. This means, essentially, that inside the group everything is + painted as if the ``opacity'' of a line or area were just another + color channel. In particular, if you paint a pixel with opacity $0$ + inside a knockout group, this pixel becomes perfectly transparent + immediately. In contrast, painting a pixel with something of + opacity $0$ normally has no effect. - Not all renderers, let alone printers, will support - this. At the time of writing, Apple's Preview will not show the - following correctly (you should see the text \tikzname\ in the - middle): + Not all renderers, let alone printers, will support this. At the + time of writing, Apple's Preview will not show the following + correctly (you should see the text \tikzname\ in the middle): + % \begin{codeexample}[] \begin{tikzpicture} \shade [left color=red,right color=blue] (-2,-1) rectangle (2,1); @@ -864,35 +848,34 @@ Transparency groups are used to render them correctly: \end{scope} \end{tikzpicture} \end{codeexample} - In the example, we first draw a large shading and then, inside the - transparency group ``overwrite'' most of this shading by a big - white rectangle. The interesting part is the text of the node, - which has opacity |0|. Normally, this would mean that nothing is - shown. However, in a knockout group, we ``paint'' the text with an - ``opacity zero'' color. The effect is that part of the totally - opaque white rectangle gets overwritten by a perfectly transparent - area (namely exactly the area taken up by the pixels of the - text). When this whole knockout group is then placed on top of the - shading, the shading will ``shine through'' at the knocked-out - pixels. - - \item \declare{|isolated|}|=false| A group can be isolated or - not. By default, they are isolated, since this is typically what you - want. For details on what isolated groups are, exactly, see - Section~7.3.4 of the \textsc{pdf} Specification, version 1.7. - \end{itemize} - - Note that when a transparency group is created, \tikzname\ must - correctly determine the size of the material inside the - group. Usually, this is no problem, but when you use things like - |overlay| or |transform canvas|, trouble may result. In this case, - please consult Section~\ref{section-transparency} on how to sidestep - this problem in such cases. + % + In the example, we first draw a large shading and then, inside the + transparency group ``overwrite'' most of this shading by a big + white rectangle. The interesting part is the text of the node, + which has opacity |0|. Normally, this would mean that nothing is + shown. However, in a knockout group, we ``paint'' the text with an + ``opacity zero'' color. The effect is that part of the totally + opaque white rectangle gets overwritten by a perfectly transparent + area (namely exactly the area taken up by the pixels of the text). + When this whole knockout group is then placed on top of the + shading, the shading will ``shine through'' at the knocked-out + pixels. + + \item \declare{|isolated|}|=false| A group can be isolated or not. By + default, they are isolated, since this is typically what you want. + For details on what isolated groups are, exactly, see Section~7.3.4 + of the \textsc{pdf} Specification, version~1.7. + \end{itemize} + + Note that when a transparency group is created, \tikzname\ must correctly + determine the size of the material inside the group. Usually, this is no + problem, but when you use things like |overlay| or |transform canvas|, + trouble may result. In this case, please consult + Section~\ref{section-transparency} on how to sidestep this problem in such + cases. \end{key} - - %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" |