From 237df1eb06d422ff243a05b9a25501ba287681c1 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 15 Oct 2006 22:37:32 +0000 Subject: pgf/tikz 1.09 big update (13oct06) git-svn-id: svn://tug.org/texlive/trunk@2332 c570f23f-e606-0410-a88d-b1316a301751 --- .../pgf/version-for-tex4ht/en/pgfmanualse28.html | 773 --------------------- 1 file changed, 773 deletions(-) delete mode 100644 Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse28.html (limited to 'Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse28.html') diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse28.html b/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse28.html deleted file mode 100644 index 861dcd26d8b..00000000000 --- a/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse28.html +++ /dev/null @@ -1,773 +0,0 @@ - - -28 Declaring and Using Shadings - - - - - - - - - -

28 Declaring and Using Shadings

-

-

28.1 Overview

-

A shading is an area in which the color changes smoothly between different colors. Similarly to an image, a -shading must first be declared before it can be used. Also similarly to an image, a shading is put into a -TEX-box. Hence, in order to include a shading in a {pgfpicture}, you have to use \pgftext around -it. -

There are three kinds of shadings: horizontal, vertical, and radial shadings. However, you can rotate and clip -shadings like any other graphics object, which allows you to create more complicated shadings. Horizontal shadings -could be created by rotating a vertical shading by 90 degrees, but explicit commands for creating both horizontal -and vertical shadings are included for convenience. -

Once you have declared a shading, you can insert it into text using the command \pgfuseshading. This -command cannot be used directly in a {pgfpicture}, you have to put a \pgftext around it. The second command -for using shadings, \pgfshadepath, on the other hand, can only be used inside {pgfpicture} environments. It will -“fill” the current path with the shading. -

A horizontal shading is a horizontal bar of a certain height whose color changes smoothly. You must at least -specify the colors at the left and at the right end of the bar, but you can also add color specifications for points in -between. For example, suppose you which to create a bar that is red at the left end, green in the -middle, and blue at the end. Suppose you would like the bar to be 4cm long. This could be specified as -follows: -

-

rgb(0cm)=(1,0,0); rgb(2cm)=(0,1,0); rgb(4cm)=(0,0,1) -
-
-

This line means that at 0cm (the left end) of the bar, the color should be red, which has red-green-blue (rgb) -components (1,0,0). At 2cm, the bar should be green, and at 4cm it should be blue. 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 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. -

-

28.2 Declaring Shadings

-

-

-\pgfdeclarehorizontalshading[<color list>]{<shading name>}{<shading height>}{<color specification>}
- -

Declares a horizontal shading named <shading name> of the specified <height> with the specified colors. - The length of the bar is deduced automatically from the maximum dimension in the specification. -

-
 

SVG-Viewer needed.

 
-
\pgfdeclarehorizontalshading{myshadingA} -
  {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(green); color(4cm)=(blue)} -
\pgfuseshading{myshadingA}
-

The effect of the <color list>, which is a comma-separated list of colors, is the following: Normally, when this - list is empty, once a shading has been declared, it becomes “frozen.” This means that even if you change a - color that was used in the declaration of the shading later on, the shading will not change. By specifying a - - - <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 <color list>, - whenever the shading is used, PGF first converts the colors in the list to RGB triples using the - current values of the colors and taking any mixins and blends into account. If the resulting RGB - triples have not yet been used, a new shading is internally created and used. Note that if the - option <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 - given. -

When a shading is recalculated because of a change in the colors mentioned in <color list>, the complete - shading 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. -

SVG-Viewer needed.

SVG-Viewer needed.

-
-
\pgfdeclarehorizontalshading[mycolor]{myshadingB} -
  {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)} -
\colorlet{mycolor}{green} -
\pgfuseshading{myshadingB} -
\colorlet{mycolor}{blue} -
\pgfuseshading{myshadingB}
-
-

-

-\pgfdeclareverticalshading[<color list>]{<shading name>}{<shading width>}{<color specification>}
- -

Declares a vertical shading named <shading name> of the specified <width>. The height of the bar is - deduced automatically. The effect of <color list> is the same as for horizontal shadings. -

- -
 

SVG-Viewer needed.

 
-
\pgfdeclareverticalshading{myshadingC} -
  {4cm}{rgb(0cm)=(1,0,0); rgb(1.5cm)=(0,1,0); rgb(2cm)=(0,0,1)} -
\pgfuseshading{myshadingC}
-
-

-

-\pgfdeclareradialshading[<color list>]{<shading name>}{<center point>}{<color specification>}
- -

Declares an radial shading. A radial shading is a circle whose inner color changes as specified by the - color specification. Assuming that the center of the shading is at the origin, the color of the center - 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 <color specified>. This maximum will also be the radius of the circle. - If the <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 <color list> is the same as for horizontal shadings. -

-
 

SVG-Viewer needed.

 

\pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}% -
  {rgb(0cm)=(0.9,0,0); -
   rgb(0.7cm)=(0.7,0,0); -
   rgb(1cm)=(0.5,0,0); -
   rgb(1.05cm)=(1,1,1)} -
\pgfuseshading{sphere}
- - -
-

-

28.3 Using Shadings

-

-

-\pgfuseshading{<shading name>}
- -

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. -

-
 

SVG-Viewer needed.

 
-
\begin{pgfpicture} -
  \pgfdeclareverticalshading{myshadingD} -
    {20pt}{color(0pt)=(red); color(20pt)=(blue)} -
  \pgftext[at=\pgfpoint{1cm}{0cm}]  {\pgfuseshading{myshadingD}} -
  \pgftext[at=\pgfpoint{2cm}{0.5cm}]{\pgfuseshading{myshadingD}} -
\end{pgfpicture}
-
-

-

-\pgfshadepath{<shading name>}{<angle>}
- -

This command must be used inside a {pgfpicture} environment. The effect is a bit complex, so let - us go over it step by step. -

First, PGF will setup a local scope. -

Second, it uses the current path to clip everything inside this scope. However, the current path is once - more available after the scope, so it can be used, for example, to stroke it. -

Now, the <shading name> should be a shading whose width and height are 100 bp, that is, 100 big - points. PGF has a look at 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. -

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 details are a bit more complex, - see below). Finally, the coordinate system is rotated by <angle>. -

After everything has been set up, the shading is inserted. Due to the transformations and clippings, - the effect will be that the shading seems to “fill” the path. -

If both the path and the shadings were always rectangles and if rotation were never involved, it would - be easy to scale shadings such they always cover the path. However, when a vertical shading is rotated, - it must obviously be “magnified” so that it still covers the path. Things get worse when the path is - not a rectangle itself. -

For these reasons, things work slightly differently “in reality.” The shading is scaled and translated - such that the the point (50bp,50bp), which is the middle of the shading, is at the middle of the path - and such that the the point (25bp,25bp) is at the lower left corner of the path and that (75bp,75bp) - is at upper right corner. -

In other words, only the center quarter of the shading will actually “survive the clipping” if the path - is a rectangle. If the path is not a rectangle, but, say, a circle, even less is seen of the shading. Here is - an example that demonstrates this effect: - - -

SVG-Viewer needed.

SVG-Viewer needed.

-
-
\pgfdeclareverticalshading{myshadingE}{100bp} -
 {color(0bp)=(red); color(25bp)=(green);  color(75bp)=(blue);  color(100bp)=(black)} -
\pgfuseshading{myshadingE} -
\hskip 1cm -
\begin{pgfpicture} -
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} -
  \pgfshadepath{myshadingE}{0} -
  \pgfusepath{stroke} -
  \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{1cm}{2cm}} -
  \pgfshadepath{myshadingE}{0} -
  \pgfusepath{stroke} -
  \pgfpathrectangle{\pgfpoint{5cm}{0cm}}{\pgfpoint{2cm}{2cm}} -
  \pgfshadepath{myshadingE}{45} -
  \pgfusepath{stroke} -
  \pgfpathcircle{\pgfpoint{9cm}{1cm}}{1cm} -
  \pgfshadepath{myshadingE}{45} -
  \pgfusepath{stroke} -
\end{pgfpicture}
-
-

As can be seen above in the last case, the “hidden” part of the shading actually can become visible if the - shading is rotated. The reason is that it is scaled as if no rotation took place, then the rotation is - done. -

The following graphics show which part of the shading are actually shown: -

SVG-Viewer needed.

-
-
\pgfdeclareverticalshading{myshadingF}{100bp} -
 {color(0bp)=(red); color(25bp)=(green);  color(75bp)=(blue);  color(100bp)=(black)} -
\begin{tikzpicture} -
  \draw (50bp,50bp) node {\pgfuseshading{myshadingF}}; -
  \draw[white,thick] (25bp,25bp) rectangle (75bp,75bp); -
  \draw (50bp,0bp) node[below] {first two applications}; -
-
  \begin{scope}[xshift=5cm] -
    \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; -
    \draw[rotate around={45:(50bp,50bp)},white,thick] (25bp,25bp) rectangle (75bp,75bp); -
    \draw (50bp,0bp) node[below] {third application}; -
  \end{scope} -
-
  \begin{scope}[xshift=10cm] -
    \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; -
    \draw[white,thick] (50bp,50bp) circle (25bp); -
    \draw (50bp,0bp) node[below] {fourth application}; -
  \end{scope} -
\end{tikzpicture}
-
-

An advantage of this approach is that when you rotate a radial shading, no distortion is introduced: - - -

SVG-Viewer needed.

SVG-Viewer needed.

-
-
\pgfdeclareradialshading{ballshading}{\pgfpoint{-10bp}{10bp}} -
 {color(0bp)=(red!15!white); color(9bp)=(red!75!white); -
 color(18bp)=(red!70!black); color(25bp)=(red!50!black); color(50bp)=(black)} -
\pgfuseshading{ballshading} -
\hskip 1cm -
\begin{pgfpicture} -
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{1cm}{1cm}} -
  \pgfshadepath{ballshading}{0} -
  \pgfusepath{} -
  \pgfpathcircle{\pgfpoint{3cm}{0cm}}{1cm} -
  \pgfshadepath{ballshading}{0} -
  \pgfusepath{} -
  \pgfpathcircle{\pgfpoint{6cm}{0cm}}{1cm} -
  \pgfshadepath{ballshading}{45} -
  \pgfusepath{} -
\end{pgfpicture}
-
-

If you specify a rotation of 90o 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: -

SVG-Viewer needed.

-
-
\pgfdeclareverticalshading{myshadingG}{100bp} -
 {color(0bp)=(red); color(25bp)=(green);  color(75bp)=(blue);  color(100bp)=(black)} -
\begin{pgfpicture} -
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} -
  \pgfshadepath{myshadingG}{0} -
  \pgfusepath{stroke} -
  \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{2cm}{1cm}} -
  \pgfshadepath{myshadingG}{90} -
  \pgfusepath{stroke} -
  \pgfpathrectangle{\pgfpoint{6cm}{0cm}}{\pgfpoint{2cm}{1cm}} -
  \pgfshadepath{myshadingG}{45} -
  \pgfusepath{stroke} -
\end{pgfpicture}
-
-

As a final example, let us define a “rainbow spectrum” shading for use with TikZ. -

-
 

SVG-Viewer needed.

 
-
\pgfdeclareverticalshading{rainbow}{100bp} -
 {color(0bp)=(red); color(25bp)=(red); color(35bp)=(yellow); -
  color(45bp)=(green); color(55bp)=(cyan); color(65bp)=(blue); -
  color(75bp)=(violet); color(100bp)=(violet)} -
\begin{tikzpicture}[shading=rainbow] -
  \shade (0,0) rectangle node[white] {\textsc{pride}} (2,1); -
  \shade[shading angle=90] (3,0) rectangle +(1,2); -
\end{tikzpicture}
-

Note that rainbow shadings are way to colorful in almost all applications.

- - - - - - - -

- -- cgit v1.2.3