This package provides a commands and environments for composing a picture from multiple layers. The package is loaded automatically by pgf, but you can load it manually if you have only included pgfcore.
PGF provides a layering mechanism for composing graphics from multiple layers. (This mechanism is not be confused with the conceptual “software layers” the PGF system is composed of.) Layers are often used in graphic programs. The idea is that you can draw on the different layers in any order. So you might start drawing something on the “background” layer, then something on the “foreground” layer, then something on the “middle” layer, and then something on the background layer once more, and so on. At the end, no matter in which ordering you drew on the different layers, the layers are “stacked on top of each other” in a fixed ordering to produce the final picture. Thus, anything drawn on the middle layer would come on top of everything of the background layer.
Normally, you do not need to use different layers since you will have little trouble “ordering” your graphic commands in such a way that layers are superfluous. However, in certain situations you only “know” what you should draw behind something else after the “something else” has been drawn.
For example, suppose you wish to draw a yellow background behind your picture. The background should be as large as the bounding box of the picture, plus a little border. If you know the size of the bounding box of the picture at its beginning, this is easy to accomplish. However, in general this is not the case and you need to create a “background” layer in addition to the standard “main” layer. Then, at the end of the picture, when the bounding box has been established, you can add a rectangle of the appropriate size to the picture.
In PGF layers are referenced using names. The standard layer, which is a bit special in certain ways, is called main. If nothing else is specified, all graphic commands are added to the main layer. You can declare a new layer using the following command:
This command declares a layer named <name> for later use. Mainly, this will setup some internal bookkeeping.
The next step toward using a layer is to tell PGF which layers will be part of the actual picture and which will be their ordering. Thus, it is possible to have more layers declared than are actually used.
This command, which should be used outside a {pgfpicture} environment, tells PGF which layers will be used in pictures. They are stacked on top of each other in the order given. The layer main should always be part of the list. Here is an example:
|
Once the layers of your picture have been declared, you can start to “fill” them. As said before, all graphics commands are normally added to the main layer. Using the {pgfonlayer} environment, you can tell PGF that certain commands should, instead, be added to the given layer.
The whole <environment contents> is added to the layer with the name <layer name>. This environment can be used anywhere inside a picture. Thus, even if it is used inside a {pgfscope} or a TEX group, the contents will still be added to the “whole” picture. Using this environment multiple times inside the same picture will cause the <environment contents> to accumulate.
Note: You can not add anything to the main layer using this environment. The only way to add anything to the main layer is to give graphic commands outside all {pgfonlayer} environments.
|
This is the plain TEX version of the environment.