layer

Select Layer. Selects a layer and starts a new layer definition segment in the command sequence.

layer= *n*|comp[, *name*]

layer= *name*

n	Number of layer to be selected (0 or greater int).
comp	Select the composite image.
name	Layer name.

All commands within the layer segment are applied to the specified layer. A layer segment is terminated by the next layer= or effect= command or the end of the request.

Specify layer=comp to select the composite image (or view, for some commands).

The layer number effectively specifies the z-order for the layer. Higher-numbered layers are placed on top of lower-numbered layers.

Layer numbers do not need to be consecutive. Layer 0 is required.

A name may be assigned to a layer with the layer= *n*, *name* command variant. Once a named layer is defined, it can be referenced with layer= *name*, without needing to know the layer number. Multiple names may be assigned to the same layer, using multiple layer= *n*, *name* commands.

NOTE

Layer 0 determines the overall size of the compositing canvas. All parts of layers falling outside the bounds of layer 0 are cropped off when the composite is built.

Properties

Layer command. Substitution variable references are not supported in layer=.

comp is not permitted as a name string. An error is returned if the same name is assigned to more than one layer, or if a layer is referenced by name which has not been defined previously.

Default

layer=comp. Many commands and attributes apply to layer 0 if layer=comp.

Special Cases

If the same name is mapped to multiple layers (for example: layer=1,image&layer=2,image), an error occurs.
If the same name is mapped to a single layer multiple times (for example: layer=1,image&layer=1,image), scope is set as usual, without errors.
Multiple names for the same layer are supported.

Either name can be used to reference the layer (for example: layer=1,image&layer=1,picture).
If a referenced name is never mapped to a layer number (for example: layer=1,image&layer=picture), an error occurs.
Substitution variables are not supported in layer modifiers (for example: layer=$image$).

This applies to all permutations, not only to layer names but to layer modifiers in general.
All merging and overriding rules should work exactly as when same layer is referenced in multiple sources (request, pre or post modifier catalog records, macros, etc.).