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-images.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-images.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex | 291 |
1 files changed, 143 insertions, 148 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex index 79ff832a88d..e8531820ca2 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex @@ -11,7 +11,6 @@ \section{Declaring and Using Images} \label{section-images} - This section describes the commands for creating images. @@ -19,134 +18,127 @@ This section describes the commands for creating images. To be quite frank, \LaTeX's |\includegraphics| is designed better than \pgfname's image mechanism. For this reason, \emph{I recommend that you use the - standard image inclusion mechanism of your format}. Thus, \LaTeX\ -users are encouraged to use |\includegraphics| to include images. +standard image inclusion mechanism of your format}. Thus, \LaTeX\ users are +encouraged to use |\includegraphics| to include images. -However, there are reasons why you might need to use the image -inclusion facilities of \pgfname: +However, there are reasons why you might need to use the image inclusion +facilities of \pgfname: +% \begin{itemize} -\item - There is no standard image inclusion mechanism in your format. For - example, plain \TeX\ does not have one, so \pgfname's inclusion - mechanism is ``better than nothing.'' - - However, this applies only to the |pdftex| backend. For all other - backends, \pgfname\ currently maps its commands back to the |graphicx| - package. Thus, in plain \TeX, this does not really help. It might be - a good idea to fix this in the future such that \pgfname\ becomes - independent of \LaTeX, thereby providing a uniform image abstraction - for all formats. -\item - You wish to use masking. This is a feature that is only supported by - \pgfname, though I hope that someone will implement this also for - the graphics package in \LaTeX\ in the future. + \item There is no standard image inclusion mechanism in your format. For + example, plain \TeX\ does not have one, so \pgfname's inclusion + mechanism is ``better than nothing''. + + However, this applies only to the |pdftex| backend. For all other + backends, \pgfname\ currently maps its commands back to the |graphicx| + package. Thus, in plain \TeX, this does not really help. It might be a + good idea to fix this in the future such that \pgfname\ becomes + independent of \LaTeX, thereby providing a uniform image abstraction + for all formats. + \item You wish to use masking. This is a feature that is only supported by + \pgfname, though I hope that someone will implement this also for the + graphics package in \LaTeX\ in the future. \end{itemize} -Whatever your choice, you can still use the usual image inclusion -facilities of the |graphics| package. - -The general approach taken by \pgfname\ to including an image is the -following: First, |\pgfdeclareimage| declares the -image. This must be done prior to the first use of the image. Once you -have declared an image, you can insert it into the text using -|\pgfuseimage|. The advantage of this two-phase approach is that, at -least for \textsc{pdf}, the image data will only be included once in the -file. This can drastically reduce the file size if you use an image -repeatedly, for example in an overlay. However, there is also a -command called |\pgfimage| that declares and then immediately uses the -image. - -To speedup the compilation, you may wish to use the following class -option: +Whatever your choice, you can still use the usual image inclusion facilities of +the |graphics| package. + +The general approach taken by \pgfname\ to including an image is the following: +First, |\pgfdeclareimage| declares the image. This must be done prior to the +first use of the image. Once you have declared an image, you can insert it into +the text using |\pgfuseimage|. The advantage of this two-phase approach is +that, at least for \textsc{pdf}, the image data will only be included once in +the file. This can drastically reduce the file size if you use an image +repeatedly, for example in an overlay. However, there is also a command called +|\pgfimage| that declares and then immediately uses the image. + +To speedup the compilation, you may wish to use the following class option: +% \begin{packageoption}{draft} - In draft mode boxes showing the image name replace the - images. It is checked whether the image files exist, but they are - not read. If either height or width is not given, 1cm is used - instead. + In draft mode boxes showing the image name replace the images. It is + checked whether the image files exist, but they are not read. If either + height or width is not given, 1cm is used instead. \end{packageoption} -\subsection{Declaring an Image} -\begin{command}{\pgfdeclareimage\oarg{options}\marg{image - name}\marg{filename}} - Declares an image, but does not paint anything. To draw the image, - use |\pgfuseimage{|\meta{image name}|}|. The \meta{filename} may not - have an extension. For \textsc{pdf}, the extensions |.pdf|, |.jpg|, - and |.png| will automatically tried. For PostScript, the extensions - |.eps|, |.epsi|, and |.ps| will be tried. - - The following options are possible: - \begin{itemize} - \item - \declare{|height=|\meta{dimension}} sets the height of the - image. If the width is not specified simultaneously, the aspect - ratio of the image is kept. - \item - \declare{|width=|\meta{dimension}} sets the width of the - image. If the height is not specified simultaneously, the aspect - ratio of the image is kept. - \item - \declare{|page=|\meta{page number}} selects a given page number - from a multipage document. Specifying this option will have the - following effect: first, \pgfname\ tries to find a file named - \begin{quote} - \meta{filename}|.page|\meta{page number}|.|\meta{extension} - \end{quote} - If such a file is found, it will be used instead of the originally - specified filename. If not, \pgfname\ inserts the image stored in - \meta{filename}|.|\meta{extension} and if a recent version of - |pdflatex| is used, only the selected page is inserted. For older - versions of |pdflatex| and for |dvips| the complete document is - inserted and a warning is printed. - \item - \declare{|interpolate=|\meta{true or false}} selects whether the - image should be ``smoothed'' when zoomed. False by default. - \item - \declare{|mask=|\meta{mask name}} selects a transparency mask. The - mask must previously be declared using |\pgfdeclaremask| (see - below). This option only has an effect for |pdf|. Not all viewers - support masking. - \end{itemize} +\subsection{Declaring an Image} +\begin{command}{\pgfdeclareimage\oarg{options}\marg{image name}\marg{filename}} + Declares an image, but does not paint anything. To draw the image, use + |\pgfuseimage{|\meta{image name}|}|. The \meta{filename} may not have an + extension. For \textsc{pdf}, the extensions |.pdf|, |.jpg|, and |.png| + will automatically tried. For PostScript, the extensions |.eps|, |.epsi|, + and |.ps| will be tried. + + The following options are possible: + % + \begin{itemize} + \item \declare{|height=|\meta{dimension}} sets the height of the image. + If the width is not specified simultaneously, the aspect ratio of + the image is kept. + \item \declare{|width=|\meta{dimension}} sets the width of the image. + If the height is not specified simultaneously, the aspect ratio of + the image is kept. + \item \declare{|page=|\meta{page number}} selects a given page number + from a multipage document. Specifying this option will have the + following effect: first, \pgfname\ tries to find a file named + % + \begin{quote} + \meta{filename}|.page|\meta{page number}|.|\meta{extension} + \end{quote} + % + If such a file is found, it will be used instead of the originally + specified filename. If not, \pgfname\ inserts the image stored in + \meta{filename}|.|\meta{extension} and if a recent version of + |pdflatex| is used, only the selected page is inserted. For older + versions of |pdflatex| and for |dvips| the complete document is + inserted and a warning is printed. + \item \declare{|interpolate=|\meta{true or false}} selects whether the + image should be ``smoothed'' when zoomed. False by default. + \item \declare{|mask=|\meta{mask name}} selects a transparency mask. + The mask must previously be declared using |\pgfdeclaremask| (see + below). This option only has an effect for |pdf|. Not all viewers + support masking. + \end{itemize} + % \begin{codeexample}[code only] \pgfdeclareimage[interpolate=true,height=1cm]{image1}{brave-gnu-world-logo} \pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{brave-gnu-world-logo} \pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} \end{codeexample} + % \end{command} - \begin{command}{\pgfaliasimage\marg{new image name}\marg{existing image name}} - The \marg{existing image name} is ``cloned'' and the \marg{new image - name} can now be used whenever the original image is used. This - command is useful for creating aliases for alternate extensions - and for accessing the last image inserted using |\pgfimage|. + The \marg{existing image name} is ``cloned'' and the \marg{new image name} + can now be used whenever the original image is used. This command is useful + for creating aliases for alternate extensions and for accessing the last + image inserted using |\pgfimage|. - \example |\pgfaliasimage{image.!30!white}{image.!25!white}| + \example |\pgfaliasimage{image.!30!white}{image.!25!white}| \end{command} \subsection{Using an Image} \begin{command}{\pgfuseimage\marg{image name}} - Inserts a previously declared image into the \emph{normal text}. If - you wish to use it in a |{pgfpicture}| environment, you must put a - |\pgftext| around it. - - If the macro |\pgfalternateextension| expands to some nonempty - \meta{alternate extension}, \pgfname\ will first try to use the image - named \meta{image name}|.|\meta{alternate extension}. If this - image is not defined, \pgfname\ will next check whether \meta{alternate - extension} contains a |!| character. If so, everything up to this - exclamation mark and including it is deleted from \meta{alternate - extension} and the \pgfname\ again tries to use the image \meta{image - name}|.|\meta{alternate extension}. This is repeated until - \meta{alternate extension} no longer contains a~|!|. Then the - original image is used. - - The |xxcolor| package sets the alternate extension to the current - color mixin. % TODOsp: `color mixin': meant `color mixing' or the `colormixin' environment? - + Inserts a previously declared image into the \emph{normal text}. If you + wish to use it in a |{pgfpicture}| environment, you must put a |\pgftext| + around it. + + If the macro |\pgfalternateextension| expands to some nonempty + \meta{alternate extension}, \pgfname\ will first try to use the image named + \meta{image name}|.|\meta{alternate extension}. If this image is not + defined, \pgfname\ will next check whether \meta{alternate extension} + contains a |!| character. If so, everything up to this exclamation mark and + including it is deleted from \meta{alternate extension} and the \pgfname\ + again tries to use the image \meta{image name}|.|\meta{alternate + extension}. This is repeated until \meta{alternate extension} no longer + contains a~|!|. Then the original image is used. + + The |xxcolor| package sets the alternate extension to the current color + mixin. + % \begin{codeexample}[] \pgfdeclareimage[interpolate=true,width=1cm,height=1cm] {image1}{brave-gnu-world-logo} @@ -164,9 +156,9 @@ option: \end{pgfpicture} \end{codeexample} - The following example demonstrates the effect of using - |\pgfuseimage| inside a colormixin environment. - + The following example demonstrates the effect of using |\pgfuseimage| + inside a colormixin environment. + % \begin{codeexample}[] \pgfdeclareimage[interpolate=true,width=1cm,height=1cm] {image1.!25!white}{brave-gnu-world-logo.25} @@ -187,21 +179,21 @@ option: \end{pgfpicture} \end{colormixin} \end{codeexample} + % \end{command} \begin{command}{\pgfalternateextension} - You should redefine this command to install a different alternate - extension. + You should redefine this command to install a different alternate + extension. - \example |\def\pgfalternateextension{!25!white}| + \example |\def\pgfalternateextension{!25!white}| \end{command} - \begin{command}{\pgfimage\oarg{options}\marg{filename}} - Declares the image under the name |pgflastimage| and - immediately uses it. You can ``save'' the image for later usage by - invoking |\pgfaliasimage| on |pgflastimage|. - + Declares the image under the name |pgflastimage| and immediately uses it. + You can ``save'' the image for later usage by invoking |\pgfaliasimage| on + |pgflastimage|. + % \begin{codeexample}[] \begin{colormixin}{25!white} \begin{pgfpicture} @@ -219,44 +211,45 @@ option: \end{pgfpicture} \end{colormixin} \end{codeexample} + % \end{command} - \subsection{Masking an Image} - \begin{command}{\pgfdeclaremask\oarg{options}\marg{mask name}\marg{filename}} - Declares a transparency mask named \meta{mask name} (called a - \emph{soft mask} in the \textsc{pdf} specification). This mask is - read from the file \meta{filename}. This file should contain a - grayscale image that is as large as the actual image. A white - pixel in the mask will correspond to ``transparent,'' a black pixel - to ``solid,'' and gray values correspond to intermediate values. The - mask must have a single ``color channel.'' This means that the - mask must be a ``real'' grayscale image, not an \textsc{rgb}-image - in which all \textsc{rgb}-triples happen to have the same - components. - - You can only mask images the are in a ``pixel format.'' These are - |.jpg| and |.png|. You cannot mask |.pdf| images in this way. Also, - again, the mask file and the image file must have the same size. - - The following options may be given: - \begin{itemize} - \item |matte=|\marg{color components} sets the so-called - \emph{matte} of the actual image (strangely, this has to be - specified together with the mask, not with the image itself). The - matte is the color that has been used to preblend the image. For - example, if the image has been preblended with a red background, - then \meta{color components} should be set to |{1 0 0}|. The - default is |{1 1 1}|, which is white in the rgb model. - - The matte is specified in terms of the parent's image color - space. Thus, if the parent is a grayscale image, the matte has to - be set to |{1}|. - \end{itemize} - \example + Declares a transparency mask named \meta{mask name} (called a \emph{soft + mask} in the \textsc{pdf} specification). This mask is read from the file + \meta{filename}. This file should contain a grayscale image that is as + large as the actual image. A white pixel in the mask will correspond to + ``transparent'', a black pixel to ``solid'', and gray values correspond to + intermediate values. The mask must have a single ``color channel''. This + means that the mask must be a ``real'' grayscale image, not an + \textsc{rgb}-image in which all \textsc{rgb}-triples happen to have the + same components. + + You can only mask images the are in a ``pixel format''. These are |.jpg| + and |.png|. You cannot mask |.pdf| images in this way. Also, again, the + mask file and the image file must have the same size. + + The following options may be given: + % + \begin{itemize} + \item |matte=|\marg{color components} sets the so-called \emph{matte} + of the actual image (strangely, this has to be specified together + with the mask, not with the image itself). The matte is the color + that has been used to preblend the image. For example, if the image + has been preblended with a red background, then \meta{color + components} should be set to |{1 0 0}|. The default is |{1 1 1}|, + which is white in the rgb model. + + The matte is specified in terms of the parent's image color space. + Thus, if the parent is a grayscale image, the matte has to be set + to |{1}|. + \end{itemize} + % + \example + % \begin{codeexample}[] %% Draw a large colorful background \pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red); @@ -269,8 +262,10 @@ color(14cm)=(green)} \pgfdeclaremask{mymask}{brave-gnu-world-logo-mask} \pgfimage[mask=mymask,height=4cm,interpolate=true]{brave-gnu-world-logo}} \end{codeexample} + % \end{command} + %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" |