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

<!-- generated by ./scripts/extract_doc.rb  -->
<!-- DO NOT EDIT! -->

<doc>
<title>DRC Reference: Global Functions</title>
<keyword name="global"/>
<p>
Some functions are available on global level and can be used without any object.
Most of them are convenience functions that basically act on some default object
or provide function-like alternatives for the methods.
</p>
<h2-index/>
<h2>"box" - Creates a box object</h2>
<keyword name="box"/>
<a name="box"/><p>Usage:</p>
<ul>
<li><tt>box(...)</tt></li>
</ul>
<p>
This function creates a box object. The arguments are the same than for the 
<class_doc href="DBox">DBox</class_doc> constructors.
</p>
<h2>"cell" - Selects a cell for input on the default source</h2>
<keyword name="cell"/>
<a name="cell"/><p>Usage:</p>
<ul>
<li><tt>cell(args)</tt></li>
</ul>
<p>
See <a href="/about/drc_ref_source.xml#cell">Source#cell</a> for a description of that function.
In addition to the functionality described there, the global function will also send the output
to the specified cell.
</p><p>
The following code will select cell "MACRO" from the input layout:
</p><p>
<pre>
cell("MACRO")
# shapes now will be taken from cell "MACRO"
l1 = input(1, 0)
</pre>
</p>
<h2>"clip" - Specifies clipped input on the default source</h2>
<keyword name="clip"/>
<a name="clip"/><p>Usage:</p>
<ul>
<li><tt>clip(args)</tt></li>
</ul>
<p>
See <a href="/about/drc_ref_source.xml#clip">Source#clip</a> for a description of that function.
</p><p>
The following code will select shapes within a 500x600 micron rectangle (lower left corner at 0,0) 
from the input layout. The shapes will be clipped to that rectangle:
</p><p>
<pre>
clip(0.mm, 0.mm, 0.5.mm, 0.6.mm)
# shapes now will be taken from the given rectangle and clipped to it
l1 = input(1, 0)
</pre>
</p>
<h2>"dbu" - Gets or sets the database unit to use</h2>
<keyword name="dbu"/>
<a name="dbu"/><p>Usage:</p>
<ul>
<li><tt>dbu(dbu)</tt></li>
<li><tt>dbu</tt></li>
</ul>
<p>
Without any argument, this method gets the database unit
used inside the DRC engine. 
</p><p>
With an argument, sets the database unit used internally in the DRC engine.
Without using that method, the database unit is automatically
taken as the database unit of the last input. 
A specific database unit can be set in order to optimize
for two layouts (i.e. take the largest common denominator).
When the database unit is set, it must be set at the beginning
of the script and before any operation that uses it.
</p>
<h2>"edge" - Creates an edge object</h2>
<keyword name="edge"/>
<a name="edge"/><p>Usage:</p>
<ul>
<li><tt>edge(...)</tt></li>
</ul>
<p>
This function creates an edge object. The arguments are the same than for the 
<class_doc href="DEdge">DEdge</class_doc> constructors.
</p>
<h2>"edge_layer" - Creates an empty edge layer</h2>
<keyword name="edge_layer"/>
<a name="edge_layer"/><p>Usage:</p>
<ul>
<li><tt>edge_layer</tt></li>
</ul>
<p>
The intention of that method is to create an empty layer which can be 
filled with edge objects using <a href="/about/drc_ref_layer.xml#insert">Layer#insert</a>.
</p>
<h2>"error" - Prints an error</h2>
<keyword name="error"/>
<a name="error"/><p>Usage:</p>
<ul>
<li><tt>error(message)</tt></li>
</ul>
<p>
Similar to <a href="#log">log</a>, but the message is printed formatted as an error
</p>
<h2>"extent" - Creates a new layer with the bounding box of the default source</h2>
<keyword name="extent"/>
<a name="extent"/><p>Usage:</p>
<ul>
<li><tt>extent</tt></li>
</ul>
<p>
See <a href="/about/drc_ref_source.xml#extent">Source#extent</a> for a description of that function.
</p>
<h2>"flat" - Disables tiling mode</h2>
<keyword name="flat"/>
<a name="flat"/><p>Usage:</p>
<ul>
<li><tt>flat</tt></li>
</ul>
<p>
Disables tiling mode. Tiling mode can be enabled again with <a href="#tiles">tiles</a> later.
</p>
<h2>"info" - Outputs as message to the logger window</h2>
<keyword name="info"/>
<a name="info"/><p>Usage:</p>
<ul>
<li><tt>info(message)</tt></li>
</ul>
<p>
Prints the message to the log window in verbose mode.
In non-verbose more, nothing is printed.
<a href="#log">log</a> is a function that always prints a message.
</p>
<h2>"input" - Fetches the shapes from the specified input from the default source</h2>
<keyword name="input"/>
<a name="input"/><p>Usage:</p>
<ul>
<li><tt>input(args)</tt></li>
</ul>
<p>
See <a href="/about/drc_ref_source.xml#input">Source#input</a> for a description of that function.
</p>
<h2>"is_tiled?" - Returns true, if in tiled mode</h2>
<keyword name="is_tiled?"/>
<a name="is_tiled?"/><p>Usage:</p>
<ul>
<li><tt>is_tiled?</tt></li>
</ul>
<h2>"layout" - Specifies an additional layout for the input source.</h2>
<keyword name="layout"/>
<a name="layout"/><p>Usage:</p>
<ul>
<li><tt>layout</tt></li>
<li><tt>layout(what)</tt></li>
</ul>
<p>
This function can be used to specify a new layout for input.
It returns an Source object representing that layout. The "input" method
of that object can be used to get input layers for that layout.
</p><p>
"what" specifies what input to use. "what" be either
</p><p>
<ul>
<li>A string "@n" specifying input from a cellview in the current view</li>
<li>A layout filename plus an optional cell name</li>
<li>A <class_doc href="Layout">Layout</class_doc> object</li>
<li>A <class_doc href="Cell">Cell</class_doc> object</li>
</ul>
</p><p>
Without any arguments the default layout is returned.
</p><p>
If a file name is given, a cell name can be specified as the second argument.
If not, the top cell is taken which must be unique in that case.
</p><p>
Having specified a layout for input enables to use the input method
for getting input:
</p><p>
<pre>
# XOR between layers 1 or the default input and "second_layout.gds":
l2 = layout("second_layout.gds")
(input(1, 0) ^ l2.input(1, 0)).output(100, 0)
</pre>
</p><p>
For further methods on the source object see <a href="#Source">Source</a>.
</p>
<h2>"log" - Outputs as message to the logger window</h2>
<keyword name="log"/>
<a name="log"/><p>Usage:</p>
<ul>
<li><tt>log(message)</tt></li>
</ul>
<p>
Prints the message to the log window.
<a href="#info">info</a> is a function that prints a message only if 
verbose mode is enabled.
</p>
<h2>"log_file" - Specify the log file where to send to log to</h2>
<keyword name="log_file"/>
<a name="log_file"/><p>Usage:</p>
<ul>
<li><tt>log_file(filename)</tt></li>
</ul>
<p>
After using that method, the log output is sent to the 
given file instead of the logger window or the terminal.
</p>
<h2>"no_borders" - Reset the tile borders</h2>
<keyword name="no_borders"/>
<a name="no_borders"/><p>Usage:</p>
<ul>
<li><tt>no_borders</tt></li>
</ul>
<p>
Resets the tile borders - see <a href="#tile_borders">tile_borders</a> for a description of tile borders.
</p>
<h2>"output" - Outputs a layer to the report database or output layout</h2>
<keyword name="output"/>
<a name="output"/><p>Usage:</p>
<ul>
<li><tt>output(layer, args)</tt></li>
</ul>
<p>
This function is equivalent to "layer.output(args)". See <a href="/about/drc_ref_layer.xml#output">Layer#output</a> for details about this function.
</p>
<h2>"output_cell" - Specifies a target cell, but does not change the target layout</h2>
<keyword name="output_cell"/>
<a name="output_cell"/><p>Usage:</p>
<ul>
<li><tt>output_cell(cellname)</tt></li>
</ul>
<p>
This method switches output to the specified cell, but does not
change the target layout nor does it switch the output channel to
layout if is report database. 
</p>
<h2>"p" - Creates a point object</h2>
<keyword name="p"/>
<a name="p"/><p>Usage:</p>
<ul>
<li><tt>p(x, y)</tt></li>
</ul>
<p>
A point is not a valid object by itself, but it is useful for creating 
paths for polygons:
</p><p>
<pre>
x = polygon_layer
x.insert(polygon([ p(0, 0), p(16.0, 0), p(8.0, 8.0) ]))
</pre>
</p>
<h2>"path" - Creates a path object</h2>
<keyword name="path"/>
<a name="path"/><p>Usage:</p>
<ul>
<li><tt>path(...)</tt></li>
</ul>
<p>
This function creates a path object. The arguments are the same than for the 
<class_doc href="DPath">DPath</class_doc> constructors.
</p>
<h2>"polygon" - Creates a polygon object</h2>
<keyword name="polygon"/>
<a name="polygon"/><p>Usage:</p>
<ul>
<li><tt>polygon(...)</tt></li>
</ul>
<p>
This function creates a polygon object. The arguments are the same than for the 
<class_doc href="DPolygon">DPolygon</class_doc> constructors.
</p>
<h2>"polygon_layer" - Creates an empty polygon layer</h2>
<keyword name="polygon_layer"/>
<a name="polygon_layer"/><p>Usage:</p>
<ul>
<li><tt>polygon_layer</tt></li>
</ul>
<p>
The intention of that method is to create an empty layer which can be 
filled with polygon-like objects using <a href="/about/drc_ref_layer.xml#insert">Layer#insert</a>.
</p>
<h2>"report" - Specifies a report database for output</h2>
<keyword name="report"/>
<a name="report"/><p>Usage:</p>
<ul>
<li><tt>report(description [, filename])</tt></li>
</ul>
<p>
After specifying a report database for output, <a href="#output">output</a> method calls are redirected to
the report database. The format of the <a href="#output">output</a> calls changes and a category name plus
description can be specified rather than a layer/datatype number of layer name.
See the description of the output method for details.
</p><p>
If a filename is given, the report database will be written to the specified file name.
Otherwise it will be shown but not written.
</p><p>
If external input is specified with <a href="#source">source</a>, 
"report" must be called after "source".
</p>
<h2>"select" - Specifies cell filters on the default source</h2>
<keyword name="select"/>
<a name="select"/><p>Usage:</p>
<ul>
<li><tt>select(args)</tt></li>
</ul>
<p>
See <a href="/about/drc_ref_source.xml#select">Source#select</a> for a description of that function.
</p>
<h2>"silent" - Resets verbose mode</h2>
<keyword name="silent"/>
<a name="silent"/><p>Usage:</p>
<ul>
<li><tt>silent</tt></li>
</ul>
<p>
This function is equivalent to "verbose(false)" (see <a href="#verbose">verbose</a>)
</p>
<h2>"source" - Specifies a source layout</h2>
<keyword name="source"/>
<a name="source"/><p>Usage:</p>
<ul>
<li><tt>source</tt></li>
<li><tt>source(what)</tt></li>
</ul>
<p>
This function replaces the default source layout by the specified
file. If this function is not used, the currently active layout 
is used as input. 
</p><p>
<a href="#layout">layout</a> is a similar method which specifies<i>a additional</i>input layout.
</p><p>
"what" specifies what input to use. "what" be either
</p><p>
<ul>
<li>A string "@n" specifying input from a layout in the current panel</li>
<li>A layout filename plus an optional cell name</li>
<li>A <class_doc href="Layout">Layout</class_doc> object</li>
<li>A <class_doc href="Cell">Cell</class_doc> object</li>
</ul>
</p><p>
Without any arguments the default layout is returned. If a filename is given, a cell name
can be specified as the second argument. If none is specified, the top cell is taken which
must be unique in that case.
</p><p>
<pre>
# XOR between layers 1 of "first_layout.gds" and "second_layout.gds" and sends the results to "xor_layout.gds":
target("xor_layout.gds")
source("first_layout.gds")
l2 = layout("second_layout.gds")
(input(1, 0) ^ l2.input(1, 0)).output(100, 0)
</pre>
</p><p>
For further methods on the source object see <a href="#Source">Source</a>.
</p>
<h2>"target" - Specify the target layout</h2>
<keyword name="target"/>
<a name="target"/><p>Usage:</p>
<ul>
<li><tt>target(what [, cellname])</tt></li>
</ul>
<p>
This function can be used to specify a target layout for output.
Subsequent calls of "output" will send their results to that target
layout. Using "target" will disable output to a report database.
If any target was specified before, that target will be closed and 
a new target will be set up.
</p><p>
"what" specifies what input to use. "what" be either
</p><p>
<ul>
<li>A string "@n" specifying output to a layout in the current panel</li>
<li>A layout filename</li>
<li>A <class_doc href="Layout">Layout</class_doc> object</li>
<li>A <class_doc href="Cell">Cell</class_doc> object</li>
</ul>
</p><p>
Except if the argument is a <class_doc href="Cell">Cell</class_doc> object, a cellname can be specified 
stating the cell name under which the results are saved. If no cellname is 
specified, either the current cell or "TOP" is used.
</p>
<h2>"threads" - Specifies the number of CPU cores to use in tiling mode</h2>
<keyword name="threads"/>
<a name="threads"/><p>Usage:</p>
<ul>
<li><tt>threads(n)</tt></li>
</ul>
<p>
If using threads, tiles are distributed on multiple CPU cores for
parallelization. Still, all tiles must be processed before the 
operation proceeds with the next statement.
</p>
<h2>"tile_borders" - Specifies a minimum tile border</h2>
<keyword name="tile_borders"/>
<a name="tile_borders"/><p>Usage:</p>
<ul>
<li><tt>tile_border(b)</tt></li>
<li><tt>tile_border(bx, by)</tt></li>
</ul>
<p>
The tile border specifies the distance to which shapes are collected into the 
tile. In order words, when processing a tile, shapes within the border distance
participate in the operations.
</p><p>
For some operations such as booleans (<a href="#and">and</a>, <a href="#or">or</a>, ...), <a href="#size">size</a> and the DRC functions (<a href="#width">width</a>, <a href="#space">space</a>, ...)
a tile border is automatically established. For other operations such as <a href="#with_area">with_area</a>
or <a href="#edges">edges</a>, the exact distance is unknown, because such operations may have a long range.
In that cases, no border is used. The tile_borders function may be used to specify a minimum border
which is used in that case. That allows taking into account at least shapes within the 
given range, although not necessarily all.
</p><p>
To reset the tile borders, use <a href="#no_borders">no_borders</a> or "tile_borders(nil)".
</p>
<h2>"tiles" - Specifies tiling</h2>
<keyword name="tiles"/>
<a name="tiles"/><p>Usage:</p>
<ul>
<li><tt>tiles(t)</tt></li>
<li><tt>tiles(w, h)</tt></li>
</ul>
<p>
Specifies tiling mode. In tiling mode, the DRC operations are evaluated in tiles
with width w and height h. With one argument, square tiles with width and height
t are used.
</p><p>
Special care must be taken when using tiling mode, since some operations may not
behave as expected at the borders of the tile. Tiles can be made overlapping by
specifying a tile border dimension with <a href="#tile_borders">tile_borders</a>. Some operations like sizing,
the DRC functions specify a tile border implicitly. Other operations without a
defined range won't do so and the consequences of tiling mode can be difficult to
predict.
</p><p>
In tiling mode, the memory requirements are usually smaller (depending on the 
choice of the tile size) and multi-CPU support is enabled (see <a href="#threads">threads</a>).
To disable tiling mode use <a href="#flat">flat</a>. 
</p>
<h2>"verbose" - Sets or resets verbose mode</h2>
<keyword name="verbose"/>
<a name="verbose"/><p>Usage:</p>
<ul>
<li><tt>verbose</tt></li>
<li><tt>verbose(m)</tt></li>
</ul>
<p>
In verbose mode, more output is generated in the log file
</p>
<h2>"verbose?" - Returns true, if verbose mode is enabled</h2>
<keyword name="verbose?"/>
<a name="verbose?"/><p>Usage:</p>
<ul>
<li><tt>verbose?</tt></li>
</ul>
<p>
In verbose mode, more output is generated in the log file
</p>
</doc>
