summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-base-images.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-images.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-base-images.tex274
1 files changed, 274 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-images.tex b/graphics/pgf/base/doc/pgfmanual-en-base-images.tex
new file mode 100644
index 0000000000..d5ea0b5d2e
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-base-images.tex
@@ -0,0 +1,274 @@
+% 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: