summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-01-05 22:40:38 +0000
committerKarl Berry <karl@freefriends.org>2019-01-05 22:40:38 +0000
commit22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch)
tree2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex
parentcf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff)
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
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.tex349
1 files changed, 173 insertions, 176 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
index 1243597df54..fda8f6a8872 100644
--- 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
@@ -9,12 +9,10 @@
\section{Transparency}
-
\label{section-transparency}
-
-For an introduction to the notion of transparency, fadings, and
-transparency groups, please consult Section~\ref{section-tikz-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}
@@ -22,11 +20,11 @@ transparency groups, please consult Section~\ref{section-tikz-transparency}.
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.
-
+ 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}
@@ -37,15 +35,15 @@ Specifying a stroke and/or fill opacity is quite easy.
\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.
+ 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}
@@ -54,12 +52,12 @@ Specifying a stroke and/or fill opacity is quite easy.
\fill[blue] (-30:1cm) circle (11mm);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
-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}
\pgfsetfillopacity{0.5}
@@ -77,52 +75,49 @@ transparency groups, see the end of this section, to change this.
To set the blend mode, use the following command:
\begin{command}{\pgfsetblendmode\marg{mode}}
- Sets the blend mode to one of the values described in
- Section~\ref{section-blend-modes}. As described there, blend modes
- are an advanced feature of \textsc{pdf} and not always rendered
- correctly.
-
-
+ Sets the blend mode to one of the values described in
+ Section~\ref{section-blend-modes}. As described there, blend modes are an
+ advanced feature of \textsc{pdf} and not always rendered correctly.
+ %
\begin{codeexample}[]
\tikz [transparency group] {
\pgfsetblendmode{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);
}
\end{codeexample}
+ %
\end{command}
\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 analyzed (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.
-
+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 analyzed (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 declares a fading named \meta{name} for later use. The
- ``picture'' on which the fading is based is given by the
- \meta{contents}. The \meta{contents} are 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:
+ This command declares a fading named \meta{name} for later use. The
+ ``picture'' on which the fading is based is given by the \meta{contents}.
+ The \meta{contents} are 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}
@@ -132,32 +127,31 @@ transparent.
\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 like |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.
+ %
+ 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 like |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,
@@ -170,8 +164,8 @@ transparent.
\end{tikzpicture}
\end{codeexample}
- In our final example, we create a fading that is based on a radial
- shading.
+ In our final example, we create a fading that is based on a radial shading.
+ %
\begin{codeexample}[]
\pgfdeclareradialshading{myshading}{\pgfpointorigin}
{
@@ -188,29 +182,30 @@ transparent.
\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 different commands for using fadings:
+After having declared a fading, we can use it. As for shadings, there are
+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 picture'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}.
+ 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 picture'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,
@@ -222,6 +217,7 @@ are different commands for using fadings:
\fill [red] (0,0) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\fill [black!20] (0,0) rectangle (2,2);
@@ -231,28 +227,29 @@ are different commands for using fadings:
\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
- and 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 shifted (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).
+ This command works like |\pgfsetfading|, but the fading is scaled and
+ 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 shifted (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);
@@ -277,16 +274,16 @@ are different commands for using fadings:
\fill [red] (0,1) rectangle (2,2);
\end{tikzpicture}
\end{codeexample}
-
+ %
\end{command}
\begin{command}{\pgfsetfadingforcurrentpathstroked\marg{name}\marg{transformations}}
- This command works line |\pgfsetfadingforcurrentpath|, only the
- current path is enlarged by the line width in both $x$- and
- $y$-direction. This is exactly the enlargement necessary to
- compensate for the fact that if the current path will be stroked,
- this much needs to be added around the path's bounding box to
- actually contain the path.
+ This command works line |\pgfsetfadingforcurrentpath|, only the current
+ path is enlarged by the line width in both $x$- and $y$-direction. This is
+ exactly the enlargement necessary to compensate for the fact that if the
+ current path will be stroked, this much needs to be added around the path's
+ bounding box to actually contain the path.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\pgfsetlinewidth{2mm}
@@ -296,58 +293,61 @@ are different commands for using fadings:
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
+
\subsection{Transparency Groups}
Transparency groups are declared using the following commands.
\begin{environment}{{pgftransparencygroup}\opt{\oarg{options}}}
- This environment should only be used inside a |{pgfpicture}|. It has
- the following effect:
- \begin{enumerate}
- \item The \meta{environment contents} are 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
- picture. 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}
-
- The optional \meta{options} are keys that configure the transparency
- group further. Two keys are currently defined:
- \begin{itemize}
- \item \declare{|knockout|\opt{|=|\meta{true or false}}} Configures
- whether the group is a knockout group (if no argument is given,
- |true| is assumed; initially the key is always false, even when
- the command is used in a nested manner.) See
- Section~\ref{section-transparency-groups} for details on knockout groups.
- \item \declare{|isolated|\opt{|=|\meta{true or false}}} Similar, but
- configures whether the group is an isolated group. Also see
- Section~\ref{section-transparency-groups} for details on isolated groups.
- \end{itemize}
-
- 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 locally
- 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:
-
+ This environment should only be used inside a |{pgfpicture}|. It has the
+ following effect:
+ %
+ \begin{enumerate}
+ \item The \meta{environment contents} are 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
+ picture. 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}
+
+ The optional \meta{options} are keys that configure the transparency group
+ further. Two keys are currently defined:
+ %
+ \begin{itemize}
+ \item \declare{|knockout|\opt{|=|\meta{true or false}}} Configures
+ whether the group is a knockout group (if no argument is given,
+ |true| is assumed; initially the key is always false, even when the
+ command is used in a nested manner.) See
+ Section~\ref{section-transparency-groups} for details on knockout
+ groups.
+ \item \declare{|isolated|\opt{|=|\meta{true or false}}} Similar, but
+ configures whether the group is an isolated group. Also see
+ Section~\ref{section-transparency-groups} for details on isolated
+ groups.
+ \end{itemize}
+
+ 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 locally 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:
{\tikzexternaldisable
\begin{codeexample}[]
@@ -368,19 +368,16 @@ Transparency groups are declared using the following commands.
\end{codeexample}
}%
+ \begin{plainenvironment}{{pgftransparencygroup}}
+ Plain \TeX\ version of the |{pgftransparencygroup}| environment.
+ \end{plainenvironment}
-\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}
-
+ \begin{contextenvironment}{{pgftransparencygroup}}
+ This is the Con\TeX t version of the environment.
+ \end{contextenvironment}
\end{environment}
-
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"