diff options
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex')
-rw-r--r-- | graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex | 274 |
1 files changed, 0 insertions, 274 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex deleted file mode 100644 index d5ea0b5d2e..0000000000 --- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex +++ /dev/null @@ -1,274 +0,0 @@ -% Copyright 2019 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{Declaring and Using Images} -\label{section-images} - -This section describes the commands for creating images. - - -\subsection{Overview} - -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. - -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. -\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: -% -\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. -\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} - % -\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|. - - \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. - % -\begin{codeexample}[] -\pgfdeclareimage[interpolate=true,width=1cm,height=1cm] - {image1}{brave-gnu-world-logo} -\pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo} -\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} -\begin{pgfpicture} - \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} - \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} - \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} - - \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} - \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} - \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} - \pgfusepath{stroke} -\end{pgfpicture} -\end{codeexample} - - The following example demonstrates the effect of using |\pgfuseimage| - inside a colormixin environment. - % -\begin{codeexample}[preamble={\usepackage{xxcolor}}] -\pgfdeclareimage[interpolate=true,width=1cm,height=1cm] - {image1.!25!white}{brave-gnu-world-logo.25} -\pgfdeclareimage[interpolate=true,width=1cm] - {image2.25!white}{brave-gnu-world-logo.25} -\pgfdeclareimage[interpolate=true,height=1cm] - {image3.white}{brave-gnu-world-logo.25} -\begin{colormixin}{25!white} -\begin{pgfpicture} - \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} - \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} - \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} - - \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} - \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} - \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} - \pgfusepath{stroke} -\end{pgfpicture} -\end{colormixin} -\end{codeexample} - % -\end{command} - -\begin{command}{\pgfalternateextension} - You should redefine this command to install a different alternate - extension. - - \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|. - % -\begin{codeexample}[preamble={\usepackage{xxcolor}}] -\begin{colormixin}{25!white} -\begin{pgfpicture} - \pgftext[at=\pgfpoint{1cm}{5cm},left,base] - {\pgfimage[interpolate=true,width=1cm,height=1cm]{brave-gnu-world-logo}} - \pgftext[at=\pgfpoint{1cm}{3cm},left,base] - {\pgfimage[interpolate=true,width=1cm]{brave-gnu-world-logo}} - \pgftext[at=\pgfpoint{1cm}{1cm},left,base] - {\pgfimage[interpolate=true,height=1cm]{brave-gnu-world-logo}} - - \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} - \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} - \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} - \pgfusepath{stroke} -\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 that are in a ``pixel format''. For drivers with - \textsc{pdf} output, these are |.jpg| and |.png| image files; you cannot - mask |.pdf| images in this way. Pixel images for the |dvips|+|ps2pdf| - workflow must be provided as |.eps| or |.ps| files. 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); -color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red); -color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red); -color(14cm)=(green)} -\hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm -\pgfimage[height=4cm]{brave-gnu-world-logo}\hskip1cm -\pgfimage[height=4cm]{brave-gnu-world-logo-mask}\hskip1cm -\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" -%%% End: |