diff options
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.tex | 145 |
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: |