summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex145
1 files changed, 98 insertions, 47 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
index c3af156d25a..d38f6bf3759 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex
@@ -50,10 +50,10 @@ should be red, which has red-green-blue (rgb) components (1,0,0). At
Instead of |rgb|, you can currently also specify |gray| as
color model, in which case only one value is needed, or |color|,
in which case you must provide the name of a color in parentheses. In
-a color specification the individual specifications must
+a color specification the individual specifications must
be separated using a semicolon, which may be followed by a whitespace
(like a space or a newline). Individual specifications must be given
-in increasing order.
+in increasing order.
\subsection{Declaring Shadings}
@@ -80,12 +80,12 @@ in increasing order.
change. By specifying a \meta{color list} you can specify
that the shading should be recalculated whenever one of the colors
listed in the list changes (this includes effects like color
- mixins). Thus, when you specify a \meta{color list},
+ mixins). Thus, when you specify a \meta{color list}, % TODOsp: mixins --> mixings? (ff) (or is here really the object meant?)
whenever the shading is used, \pgfname\ first converts the colors in the
list to \textsc{rgb} triples using the current values of the
colors and taking any mixins and blends into account. If the
resulting \textsc{rgb} triples have not yet been used, a new
- shading is internally created and used. Note that if the
+ shading is internally created and used. Note that if the
option \meta{color list} is used, then no shading is created until
the first use of |\pgfuseshading|. In particular, the colors
mentioned in the shading need not be defined when the declaration is
@@ -96,7 +96,7 @@ in increasing order.
is recalculated. Thus even colors not mentioned in the list will be
used with their current values, not with the values they had upon
declaration.
-
+
\begin{codeexample}[]
\pgfdeclarehorizontalshading[mycolor]{myshadingB}
{1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)}
@@ -133,13 +133,13 @@ in increasing order.
will be the color specified for 0cm and the color of the border of
the circle will be the color for the maximum dimension given in
the \meta{color specified}. This maximum will also be the radius of
- the circle. If the \meta{center point} is not at the
+ the circle. If the \meta{center point} is not at the
origin, the whole shading inside the circle (whose size remains
exactly the same) will be distorted such that the given center now
has the color specified for 0cm. The effect of \meta{color list} is
- the same as for horizontal shadings.
+ the same as for horizontal shadings.
-\begin{codeexample}[]
+\begin{codeexample}[]
\pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}%
{rgb(0cm)=(0.9,0,0);
rgb(0.7cm)=(0.7,0,0);
@@ -162,10 +162,10 @@ in increasing order.
This command creates a \emph{functional shading}. For such a
shading, the color of each point is calculated by calling a function
that gets the coordinates of the point as input and yields the
- color as an output. Note that the function is evaluated by the
+ color as an output. Note that the function is evaluated by the
\emph{renderer}, not by \pgfname\ or \TeX or someone else at
compile-time. This means that the evaluation of this function has to
- be done \emph{extremely quickly} and the funciton should be
+ be done \emph{extremely quickly} and the function should be
\emph{very simple}. For this reason, only a very restricted set of
operations are possible in the function and functions should be
kept small. Any errors in the function will only be noticed by the
@@ -175,8 +175,8 @@ in increasing order.
simplified form of a subset of the PostScript language. This subset
will be understood by the PDF-renderer (yes, PDF-renderers do
have a basic understanding of PostScript) and also by PostScript
- renders. This subset is detailed in Seciton 3.9.4 of the
- PDF-specification (version 1.7). In essence, the specificaiton
+ renders. This subset is detailed in Section~3.9.4 of the
+ PDF-specification (version 1.7). In essence, the specification
states that these functions may contain ``expressions involving
integers, real numbers, and boolean values only. There are no
composite data structures such as strings or arrays, no procedures,
@@ -196,7 +196,7 @@ in increasing order.
coordinates of the point for which the color should be computed. The
coordinates are dimensionless and given in big points, so for the
coordinate $(50bp, 72.27pt)$ the top two stack elements would be
- \texttt{50.0} and \texttt{72.0}. Ohterwise, the (virtual) stack is
+ \texttt{50.0} and \texttt{72.0}. Otherwise, the (virtual) stack is
empty (or should be treated as if it were empty). The function
should then replace these two values by three values, representing
the red, green, and blue color of the point. The numbers should be
@@ -208,11 +208,11 @@ in increasing order.
which should be a \pgfname-point expression like
|\pgfpoint{100bp}{100bp}|. A renderer may choose to evaluate the
function at less points, but, in principle, the function will be
- evaluated for each pixel independently.
+ evaluated for each pixel independently.
Because of the rather difficult PostScript syntax, use this macro
only \emph{if you know what you are doing} (or if you are
- advanterous, of course).
+ advantageous, of course).
As for other shadings, the optional \meta{color list} is used to
determine whether a shading needs to be recalculated when a color
@@ -220,16 +220,7 @@ in increasing order.
The \meta{init code} is executed each time a shading is
(re)calculated. Typically, it will contain code to extract
- coordinates from colors (see below).
-
- Inside the PostScript function \meta{type 4 function} you cannot use
- colors directly. Rather, you must push the color components on the
- stack. For this, it is useful to call |\pgfshadecolorrgb| in the
- \meta{init code}. The macro takes a color name as input and stores
- the color's red/green/blue components real numbers between 0.0 and
- 1.0 separated by spaces (which is exactly what you need if you want
- to push it on a stack) in a macro. You can then use this macro in
- the argument \meta{type 4 function}.
+ coordinates from colors.
\begin{codeexample}[]
\pgfdeclarefunctionalshading{twospots}
@@ -239,9 +230,9 @@ in increasing order.
% Compute distance from (40bp,45bp), with x doubled
45 sub dup mul exch
40 sub dup mul 0.5 mul add sqrt
- % expontial decay
+ % exponential decay
dup mul neg 1.0005 exch exp 1.0 exch sub
- % Compute distance form (70bp,70bp) from stored coordiante, scaled
+ % Compute distance form (70bp,70bp) from stored coordinate, scaled
3 1 roll
70 sub dup mul .5 mul exch
70 sub dup mul add sqrt
@@ -253,18 +244,33 @@ in increasing order.
\pgfuseshading{twospots}
\end{codeexample}
+ Inside the PostScript function \meta{type 4 function} you cannot use
+ colors directly. Rather, you must push the color components on the
+ stack. For this, it is useful to call |\pgfshadecolorrgb| in the
+ \meta{init code}:
+
+\begin{command}{\pgfshadecolortorgb\marg{color name}\marg{macro}}
+ This command takes \meta{color name} as input and stores
+ the color's red/green/blue components real numbers between 0.0 and
+ 1.0 separated by spaces (which is exactly what you need if you want
+ to push it on a stack) in \meta{macro}. This macro can then be used
+ inside the
+ \meta{type 4 function} argument for |\pgfdeclarefunctionalshading|.
+
+
\begin{codeexample}[]
\pgfdeclarefunctionalshading[mycol]{sweep}{\pgfpoint{-1cm}{-1cm}}
{\pgfpoint{1cm}{1cm}}{\pgfshadecolortorgb{mycol}{\myrgb}}{
2 copy % whirl
- atan
+ % Calculate "safe" atan of position
+ 2 copy abs exch abs add 0.0001 ge { atan } { pop } ifelse
3 1 roll
dup mul exch
dup mul add sqrt
30 mul
add
sin
- 1 add 2 div
+ 1 add 2 div
dup
\myrgb % push mycol
5 4 roll % multiply all components by calculated value
@@ -282,6 +288,51 @@ in increasing order.
\colorlet{mycol}{red}%
\pgfuseshading{sweep}
\end{codeexample}
+
+
+In addition, three macros suffixed with |red|, |green| and |blue|
+are defined, which store the individual components of
+\meta{color name}. These can also
+be used in the \meta{type 4 function} argument.
+
+\begin{codeexample}[]
+\pgfshadecolortorgb{orange}{\mycol}
+|\mycol|=\mycol |\mycolred|=\mycolred |\mycolgreen|=\mycolgreen |\mycolblue|=\mycolblue
+\end{codeexample}
+\end{command}
+
+\begin{codeexample}[]
+\pgfdeclarefunctionalshading[col1,col2,col3,col4]{bilinear interpolation}
+{\pgfpointorigin}{\pgfpoint{100bp}{100bp}}
+{
+\pgfshadecolortorgb{col1}{\first}\pgfshadecolortorgb{col2}{\second}
+\pgfshadecolortorgb{col3}{\third}\pgfshadecolortorgb{col4}{\fourth}
+}{
+ 100 div exch 100 div 2 copy % Calculate y/100 x/100.
+ neg 1 add exch neg 1 add % Calculate 1-y/100 1-x/100.
+ 3 1 roll 2 copy exch 5 2 roll 6 copy 6 copy % Set up stack.
+ \firstred mul exch \secondred mul add mul % Process red component.
+ 4 1 roll
+ \thirdred mul exch \fourthred mul add mul
+ add
+ 13 1 roll
+ \firstgreen mul exch \secondgreen mul add mul % Process green component.
+ 4 1 roll
+ \thirdgreen mul exch \fourthgreen mul add mul
+ add
+ 7 1 roll
+ \firstblue mul exch \secondblue mul add mul % Process blue component.
+ 4 1 roll
+ \thirdblue mul exch \fourthblue mul add mul
+ add
+}
+
+\colorlet{col1}{blue}
+\colorlet{col2}{yellow}
+\colorlet{col3}{red}
+\colorlet{col4}{green}
+\pgfuseshading{bilinear interpolation}
+\end{codeexample}
\end{command}
@@ -292,7 +343,7 @@ in increasing order.
Inserts a previously declared shading into the text. If you wish to
use it in a |pgfpicture| environment, you should put a |\pgfbox|
around it.
-
+
\begin{codeexample}[]
\begin{pgfpicture}
\pgfdeclareverticalshading{myshadingD}
@@ -318,16 +369,16 @@ in increasing order.
the bounding box of the current path. This bounding box is computed
automatically when a path is computed; however, it can sometimes be
(quite a bit) too large, especially when complicated curves are
- involved.
+ involved.
Inside the scope, the low-level transformation matrix is modified.
The center of the shading is translated (moved) such that it lies on
the center of the bounding box of the path. The low-level coordinate
- system is also scaled such that the shading ``covers'' the shading (the
+ system is also scaled such that the shading ``covers'' the shading (the
details are a bit more complex, see below). Then, the coordinate
- system is rotated by \meta{angle}. Finally, if the macro
+ system is rotated by \meta{angle}. Finally, if the macro
|\pgfsetadditionalshadetransform| has been used, an additional
- transformation is applied.
+ transformation is applied.
After everything has been set up, the shading is inserted. Due to
the transformations and clippings, the effect will be that the
@@ -341,9 +392,9 @@ in increasing order.
rectangle itself.
For these reasons, things work slightly differently ``in reality.''
- The shading is scaled and translated such that the
+ The shading is scaled and translated such that
the point $(50\mathrm{bp},50\mathrm{bp})$, which is the middle of
- the shading, is at the middle of the path and such that the the
+ the shading, is at the middle of the path and such that the
point $(25\mathrm{bp},25\mathrm{bp})$ is at the lower left corner of
the path and that $(75\mathrm{bp},75\mathrm{bp})$ is at upper
right corner.
@@ -354,9 +405,9 @@ in increasing order.
shading. Here is an example that demonstrates this effect:
\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingE}{100bp}
+\pgfdeclareverticalshading{myshadingE}{100bp}
{color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)}
-\pgfuseshading{myshadingE}
+\pgfuseshading{myshadingE}
\hskip 1cm
\begin{pgfpicture}
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
@@ -380,10 +431,10 @@ in increasing order.
place, then the rotation is done.
The following graphics show which part of the shading are actually
- shown:
+ shown:
\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingF}{100bp}
+\pgfdeclareverticalshading{myshadingF}{100bp}
{color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)}
\begin{tikzpicture}
\draw (50bp,50bp) node {\pgfuseshading{myshadingF}};
@@ -403,7 +454,7 @@ in increasing order.
\end{scope}
\end{tikzpicture}
\end{codeexample}
-
+
An advantage of this approach is that when you rotate a radial
shading, no distortion is introduced:
@@ -430,9 +481,9 @@ in increasing order.
and if the path is not a square, but an elongated rectangle, the
``desired'' effect results: The shading will exactly vary between
the colors at the 25bp and 75bp boundaries. Here is an example:
-
+
\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingG}{100bp}
+\pgfdeclareverticalshading{myshadingG}{100bp}
{color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)}
\begin{pgfpicture}
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
@@ -462,17 +513,17 @@ in increasing order.
\end{codeexample}
Note that rainbow shadings are \emph{way} to colorful in almost all
- applications.
+ applications.
\end{command}
\begin{command}{\pgfsetadditionalshadetransform\marg{transformation}}
This command allows you to specify an additional transformation
that should be applied to shadings when the |\pgfshadepath|
command is used. The \meta{transformation} should be
- transformation code like |\pgftransformrotate{20}|.
+ transformation code like |\pgftransformrotate{20}|.
\end{command}
-%%% Local Variables:
+%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
-%%% End:
+%%% End: