summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex331
1 files changed, 331 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex
new file mode 100644
index 00000000000..ad6c465cef6
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex
@@ -0,0 +1,331 @@
+% 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-transparency}
+
+
+For an introduction to the notion of transparency, fadings, and
+transparency groups, please consult Section~\ref{section-tikz-transparency}.
+
+
+\subsection{Specifying a Uniform Opacity}
+
+Specifying a stroke and/or fill opacity is quite easy.
+
+\begin{command}{\pgfsetstrokeopacity\marg{value}}
+ Sets the opacity of stroking operations. The \meta{value} should be
+ a number between |0| and |1|, where |1| means ``fully opaque'' and
+ |0| means ``fully transparent.'' A value like |0.5| will cause paths
+ to be stroked in a semitransparent way.
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \pgfsetlinewidth{5mm}
+ \color{red}
+ \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke}
+ \color{black}
+ \pgfsetstrokeopacity{0.5}
+ \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke}
+\end{pgfpicture}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfsetfillopacity\marg{value}}
+ Sets the opacity of filling operations. As for stroking, the
+ \meta{value} should be a number between |0| and~|1|.
+
+ The ``filling transparency'' will also be used for text and images.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \pgfsetfillopacity{0.5}
+ \fill[red] (90:1cm) circle (11mm);
+ \fill[green] (210:1cm) circle (11mm);
+ \fill[blue] (-30:1cm) circle (11mm);
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+Note the following effect: If you setup a certain opacity for stroking
+or filling and you stroke or fill the same area twice, the effect
+accumulates:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \pgfsetfillopacity{0.5}
+ \fill[red] (0,0) circle (1);
+ \fill[red] (1,0) circle (1);
+\end{tikzpicture}
+\end{codeexample}
+
+Often, this is exactly what you intend, but not always. You can use
+transparency groups, see the end of this section, to change this.
+
+
+\subsection{Specifying a Fading}
+
+The method used by \pgfname\ for specifying fadings is quite
+general: You ``paint'' the fading using any of the standard graphics
+commands. In more detail: You create a normal picture, which may even
+contain text, image, and shadings. Then, you create a fading based on
+this picture. For this, the \emph{luminosity} of each pixel of the
+picture is analysed (the brighter the pixel, the higher the luminosity
+-- a black pixel has luminosity $0$, a white pixel has luminosity $1$,
+a gray pixel has some intermediate value as does a red pixel). Then,
+when the fading is used, the luminosity of the pixel determines the
+opacity of the fading at that position. Positions in the fading where
+the picture was black will be completely transparent, positions where
+the picture was white will be completely opaque. Positions that have
+not been painted at all in the picture are always completely
+transparent.
+
+
+\begin{command}{\pgfdeclarefading\marg{name}\marg{contents}}
+ This command declare a fading named \meta{name} for later use. The
+ ``picture'' on which the fading is based is given by the
+ \meta{contents}. This \meta{contents} is normally typeset in a \TeX\
+ box. The resulting box is then used as the ``picture.'' In
+ particular, inside the \meta{contents} you must explicitly open a
+ |{pgfpicture}| environment if you wish to use \pgfname\ commands.
+
+ Let's start with an easy example. Our first fading picture is just
+ some text:
+\begin{codeexample}[]
+\pgfdeclarefading{fading1}{\color{white}Ti\emph{k}Z}
+\begin{tikzpicture}
+ \fill [black!20] (0,0) rectangle (2,2);
+ \fill [black!30] (0,0) arc (180:0:1);
+ \pgfsetfading{fading1}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
+ \fill [red] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+ What's happening here? The ``fading picture'' is mostly transparent,
+ except for the pixels that are part of the word Ti\emph{k}Z. Now,
+ these pixels are \emph{white} and, thus, have a high
+ luminosity. This in turn means that these pixels of the fading will
+ be highly opaque. For this reason, only those pixels of the big red
+ rectangle ``shine through'' that are at the positions of these
+ opaque pixels.
+
+ It is somewhat counter-intuitive that the white pixels in a fading
+ picture are opaque in a fading. For this reason, the color
+ |pgftransparent| is defined to be the same as |black|. This allows
+ one to write |pgftransparent| for completely transparent parts of a
+ fading picture and |pgftransparent!0| for the opaque parts and
+ things liek |pgftransparent!20| for parts that are 20\%
+ transparent.
+
+ Furthermore, the color |pgftransparent!0| (which is the same as
+ white and which corresponds to completely opaque) is installed at
+ the beginning of a fading picture. Thus, in the above example the
+ |\color{white}| was not really necessary.
+
+ Next, let us create a fading that gets more and more transparent as
+ we go from left to right. For this, we put a shading inside the
+ fading picture that has the color |pgftransparent!0| at the
+ left-hand side and the color |pgftransparent!100| at the right-hand
+ side.
+\begin{codeexample}[]
+\pgfdeclarefading{fading2}
+{\tikz \shade[left color=pgftransparent!0,
+ right color=pgftransparent!100] (0,0) rectangle (2,2);}
+\begin{tikzpicture}
+ \fill [black!20] (0,0) rectangle (2,2);
+ \fill [black!30] (0,0) arc (180:0:1);
+ \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
+ \fill [red] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ In our final example, we create a fading that is based on a radial
+ shading.
+\begin{codeexample}[]
+\pgfdeclareradialshading{myshading}{\pgfpointorigin}
+{
+ color(0mm)=(pgftransparent!0);
+ color(5mm)=(pgftransparent!0);
+ color(8mm)=(pgftransparent!100);
+ color(15mm)=(pgftransparent!100)
+}
+\pgfdeclarefading{fading3}{\pgfuseshading{myshading}}
+\begin{tikzpicture}
+ \fill [black!20] (0,0) rectangle (2,2);
+ \fill [black!30] (0,0) arc (180:0:1);
+ \pgfsetfading{fading3}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
+ \fill [red] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+After having declared a fading, we can use it. As for shadings, there
+are two different commands for using fadings:
+
+\begin{command}{\pgfsetfading\marg{name}\marg{transformations}}
+ This command sets the graphic state parameter ``fading'' to a
+ previously defined fading \meta{name}. This graphic state works like
+ other graphic states, that is, is persists till the end of the
+ current scope or until a different transparency setting is chosen.
+
+ When the fading is installed, it will be centered on the origin with
+ its natural size. Anything outside the fading pictures's original
+ bounding box will be transparent and, thus, the fading effectively
+ clips against this bounding box.
+
+ The \meta{transformations} are applied to the fading before it is
+ used. They contain normal \pgfname\ transformation commands like
+ |\pgftransformshift|. You can also scale the fading using this
+ command. Note, however, that the transformation needs to be inverted
+ internally, which may result in inaccuracies and the following
+ graphics may be slightly distorted if you use a strong
+ \meta{transformation}.
+\begin{codeexample}[]
+\pgfdeclarefading{fading2}
+{\tikz \shade[left color=pgftransparent!0,
+ right color=pgftransparent!100] (0,0) rectangle (2,2);}
+\begin{tikzpicture}
+ \fill [black!20] (0,0) rectangle (2,2);
+ \fill [black!30] (0,0) arc (180:0:1);
+ \pgfsetfading{fading2}{}
+ \fill [red] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \fill [black!20] (0,0) rectangle (2,2);
+ \fill [black!30] (0,0) arc (180:0:1);
+ \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}
+ \pgftransformrotate{20}}
+ \fill [red] (0,0) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfsetfadingforcurrentpath\marg{name}\marg{transformations}}
+ This command works like |\pgfsetfading|, but the fading is scaled
+ are transformed according to the following rules:
+ \begin{enumerate}
+ \item
+ If the current path is empty, the command has the same effect as
+ |\pgfsetfading|.
+ \item
+ Otherwise it is assumed that the fading has a size of 100bp times
+ 100bp.
+ \item
+ The fading is resized and shiften (using appropriate
+ transformations) such that the position
+ $(25\mathrm{bp},25\mathrm{bp})$ lies at the lower-left corner of
+ the current path and the position $(75\mathrm{bp},75\mathrm{bp})$
+ lies at the upper-right corner of the current path.
+ \end{enumerate}
+ Note that these rules are the same as the ones used in
+ |\pgfshadepath| for shadings. After these transformations, the
+ \meta{transformations} are executed (typically a rotation).
+\begin{codeexample}[]
+\pgfdeclarehorizontalshading{shading}{100bp}
+{ color(0pt)=(transparent!0); color(25bp)=(transparent!0);
+ color(75bp)=(transparent!100); color(100bp)=(transparent!100)}
+
+\pgfdeclarefading{fading}{\pgfuseshading{shading}}
+
+\begin{tikzpicture}
+ \fill [black!20] (0,0) rectangle (2,2);
+ \fill [black!30] (0,0) arc (180:0:1);
+
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
+ \pgfsetfadingforcurrentpath{fading}{}
+ \pgfusepath{discard}
+
+ \fill [red] (0,0) rectangle (2,1);
+
+ \pgfpathrectangle{\pgfpoint{0cm}{1cm}}{\pgfpoint{2cm}{1cm}}
+ \pgfsetfadingforcurrentpath{fading}{\pgftransformrotate{90}}
+ \pgfusepath{discard}
+
+ \fill [red] (0,1) rectangle (2,2);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{command}
+
+\subsection{Transparency Groups}
+
+Transparency groups are declared using the following commands.
+
+\begin{environment}{{pgftransparencygroup}}
+ This environment should only be used inside a |{pgfpicture}|. It has
+ the following effect:
+ \begin{enumerate}
+ \item The \meta{environment 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). This means that if in the
+ \meta{environment contents} you stroke a pixel three times in
+ black, it is just black. Stroking it white afterwards yields a
+ white pixel, and so on.
+ \item When the group is finished, it is painted as a whole. The
+ \emph{fill} transparency settings are now applied to the resulting
+ picutre. For instance, the pixel that has been painted three times
+ in black and once in white is just white at the end, so this white
+ color will be blended with whatever is ``behind'' the group on the
+ page.
+ \end{enumerate}
+
+ Note that, depending on the driver, \pgfname\ may have to guess the
+ size of the contents of the transparency group (because such a group
+ is put in an XForm in \textsc{pdf} and a bounding box must be
+ supplied). \pgfname\ will use normally use the size of the picture's
+ bounding box at the end of the transparency group plus a safety
+ margin of 1cm. Under normal circumstances, this will work nicely
+ since the picture's bounding box contains everything
+ anyway. However, if you have switched off the picture size tracking
+ or if you are using canvas transformations, you may have to make
+ sure that the bounding box is big enough. The trick is to locallly
+ create a picture that is ``large enough'' and then insert this
+ picture into the main picture while ignoring the size. The following
+ example shows how this is done:
+
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw [help lines] (0,0) grid (2,2);
+
+ % Stuff outside the picture, but still in a transparency group.
+ \node [left,overlay] at (0,1) {
+ \begin{tikzpicture}
+ \pgfsetfillopacity{0.5}
+ \pgftransparencygroup
+ \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
+ {Smoking};
+ \endpgftransparencygroup
+ \end{tikzpicture}
+ };
+\end{tikzpicture}
+\end{codeexample}
+
+
+\begin{plainenvironment}{{pgftransparencygroup}}
+ Plain \TeX\ version of the |{pgftransparencygroup}| environment.
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgftransparencygroup}}
+ This is the Con\TeX t version of the environment.
+\end{contextenvironment}
+
+\end{environment}
+
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End: