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.tex291
1 files changed, 143 insertions, 148 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
index 79ff832a88d..e8531820ca2 100644
--- 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
@@ -11,7 +11,6 @@
\section{Declaring and Using Images}
\label{section-images}
-
This section describes the commands for creating images.
@@ -19,134 +18,127 @@ This section describes the commands for creating images.
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.
+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:
+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.
+ \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:
+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.
+ 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}
+\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|.
+ 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}|
+ \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. % TODOsp: `color mixin': meant `color mixing' or the `colormixin' environment?
-
+ 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}
@@ -164,9 +156,9 @@ option:
\end{pgfpicture}
\end{codeexample}
- The following example demonstrates the effect of using
- |\pgfuseimage| inside a colormixin environment.
-
+ The following example demonstrates the effect of using |\pgfuseimage|
+ inside a colormixin environment.
+ %
\begin{codeexample}[]
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
{image1.!25!white}{brave-gnu-world-logo.25}
@@ -187,21 +179,21 @@ option:
\end{pgfpicture}
\end{colormixin}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfalternateextension}
- You should redefine this command to install a different alternate
- extension.
+ You should redefine this command to install a different alternate
+ extension.
- \example |\def\pgfalternateextension{!25!white}|
+ \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|.
-
+ 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}
@@ -219,44 +211,45 @@ option:
\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
+ 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);
@@ -269,8 +262,10 @@ color(14cm)=(green)}
\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"