diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
commit | 22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch) | |
tree | 2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex | |
parent | cf794f0e2db6857972a9d48d4466a4f03a7057a0 (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.tex | 349 |
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" |