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:
|
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.
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.
|
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.
|
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.
|
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.
|
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.
|
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:
|
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:
|
An advantage of this approach is that when you rotate a radial shading, no distortion is introduced:
|
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:
|
As a final example, let us define a “rainbow spectrum” shading for use with TikZ.
|
Note that rainbow shadings are way to colorful in almost all applications.