<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">

<doc>

  <title>About Layer Sources</title>

  <p>
  KLayout implements a concept of "layer views". The layer list is made up of such layer views.
  A "view" is basically a specification of what is shown how.
  The "how" part is given by the colors, stipples, styles etc. 
  The "what" part is given by the source specification.
  </p>

  <p>
  The most important part of the source specification is the layer number or name. 
  But the source specification is much more powerful.
  Basically the source specification offers the following capabilities:
  </p>

  <ul>
    <li>Specify the layer where the shapes are taken from, either by layer and datatype or name</li>
    <li>Transform the layout before it is drawn</li>
    <li>Property filter: draw only shapes whose user properties match a given expression</li>
    <li>Override the hierarchy levels on which the shapes are drawn</li>
  </ul>

  <h2>Specifying the source layer</h2>

  <p>
  The source layer specifies from which actual data
  layer to take the drawn shapes from. The most simple form of a source 
  specification is "layer/datatype" (i.e. "5/0") or the layer name, if an OASIS
  layer name (or a named layer in general) is present. 
  This specification can be enhanced by a layout index.
  The first layout loaded in the panel is referred to which "@1" or by omitting 
  this specification. The source specification "10/5@2" therefore refers to layer
  10, datatype 5 of the second layout loaded in the panel.
  </p>

  <p>
  Source specifications can be wildcarded. That means, either layer, datatype
  or layout index can be specified by "*". In this case, such a layer view must
  be contained in a group and the group parent must provide the missing specifications.
  For example, if a layer is specified "10/*" and the parent is specified "*/5", the
  effective layer looked for will be "10/5". Unlike the behaviour for the display
  styles, the children override (or specialize) the parent's definition in the 
  case of the source specification.
  </p>

  <p>
  For more information refer to <link href="/manual/layer_source.xml"/>.
  </p>

  <h2>Transforming the layout</h2>

  <p>
  A geometrical transformation is specified by appending a transformation in 
  round brackets to the layer/datatype source specification.
  </p>

  <p>
  For example, "(r90)" specifies a rotation by 90 degree counter-clockwise.
  "(0,100.0 m45 *0.5)" will shrink the layout to half the size, flip at the 
  45 degree-axis (swap x and y axes) and finally shift the layout by 100 micron
  upwards.
  </p>

  <p>
  Transformations accumulate over the layer hierarchy. This means, that if a layer is transformed
  and the layer is inside a group whose representative specifies a transformation as well, the
  resulting transformation is the combination of the layer's transformation (first applied) and
  the group representative's transformation.
  </p>

  <p>
  Multiple transformations can be present. In this case, the layout is shown in multiple
  instances.
  </p>

  <p>
  For more information refer to <link href="/manual/layer_source_expert.xml"/>.
  </p>

  <h2>Property filters</h2>

  <p>
  It is possible to specify a property filter. A property filter specifies an expression and only shapes
  for which that expression applies are shown. The expression operates on user properties and the syntax
  allows comparison of properties with a given key against a given value. Boolean operators are available. That
  way, complex expressions can be created.
  </p>

  <p>
  The property filter is specified in square brackets. For example:</p>

  <p>
  <tt>10/5 [#43==X]</tt>
  </p>

  <p>
  With this source specification, the layer will show all shapes from layer 10, datatype 5 
  which have a user property with number 43 and value string "X".
  </p>

  <p>
  For more information refer to <link href="/manual/layer_source_expert.xml"/>.
  </p>

  <h2>Overriding the hierarchy levels</h2>

  <p>
  By default, only the hierarchy levels that are selected in the hierarchy level
  selection boxes are shown, i.e. if levels 0 to 1 are selected, just the top level 
  shapes and instances are shown. This selection can be modified for certain layers or layer groups.
  To specify a different hierarchy selection for a certain layer, use an optional source specification 
  element, the hierarchy level selector.
  </p>

  <p> 
  For example:
  </p>

  <table>
    <tr><td><tt>#*&nbsp;&nbsp;</tt></td><td>Display all hierarchy levels</td></tr>
    <tr><td><tt>#0..1&nbsp;&nbsp;</tt></td><td>Display top level only</td></tr>
    <tr><td><tt>#..5&nbsp;&nbsp;</tt></td><td>Override upper level with 5</td></tr>
    <tr><td><tt>#2..&nbsp;&nbsp;</tt></td><td>Override lower level with 2</td></tr>
    <tr><td><tt>#..*&nbsp;&nbsp;</tt></td><td>Override upper level setting by "all levels"</td></tr>
  </table>

  <p>
  For more information refer to <link href="/manual/explicit_hier_levels.xml"/>.
  </p>

</doc>

