summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex
diff options
context:
space:
mode:
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.tex274
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: