summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex
diff options
context:
space:
mode:
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.tex278
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: