diff options
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 | 278 |
1 files changed, 278 insertions, 0 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 new file mode 100644 index 00000000000..ebadb54e5ff --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex @@ -0,0 +1,278 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\section{Declaring and Using Images} +\label{section-images} + + +This section describes the |pgfbaseimage| package. + +\begin{package}{pgfbaseimage} + This package offers an abstraction of the image inclusion + process. It is loaded automatically by |pgf|, but you can load it + manually if you have only included |pgfcore|. +\end{package} + +\subsection{Overview} + +To be quite frank, \LaTeX's |\includegraphics| is designed better than +|pgfbaseimage|. 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 ``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}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,height=1cm]{image3}{pgf-tu-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 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 + names \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}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,width=1cm]{image2}{pgf-tu-logo} +\pgfdeclareimage[interpolate=true,height=1cm]{image3}{pgf-tu-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 color mixin environment. + +\begin{codeexample}[] +\pgfdeclareimage[interpolate=true,width=1cm,height=1cm] + {image1.!25!white}{pgf-tu-logo.25} +\pgfdeclareimage[interpolate=true,width=1cm] + {image2.25!white}{pgf-tu-logo.25} +\pgfdeclareimage[interpolate=true,height=1cm] + {image3.white}{pgf-tu-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}[] +\begin{colormixin}{25!white} +\begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base] + {\pgfimage[interpolate=true,width=1cm,height=1cm]{pgf-tu-logo}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base] + {\pgfimage[interpolate=true,width=1cm]{pgf-tu-logo}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base] + {\pgfimage[interpolate=true,height=1cm]{pgf-tu-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 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); +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]{pgf-apple}\hskip1cm +\pgfimage[height=4cm]{pgf-apple.mask}\hskip1cm +\pgfdeclaremask{mymask}{pgf-apple.mask} +\pgfimage[mask=mymask,height=4cm,interpolate=true]{pgf-apple}} +\end{codeexample} +\end{command} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |