API reference - Class Layout

Notation used in Ruby API documentation

Description: The layout object

• Public constructors
• Public methods
• Detailed description

The layout object basically wraps the cell graphs and adds functionality for managing cell names and layer names. The cell graph is a container for the cells and their hierarchical arrangement. The cell graph is constructed by creating cells and adding child instances to it.

Public constructors

Public methods

Detailed description

unsigned int add_cell(string name)

Description: Add a cell with the given name

unsigned int add_lib_cell(Library ptr library,unsigned int lib_cell_index)

Description: Imports a cell from the library

This method imports the given cell from the library and creates a new proxy cell. The proxy cell acts as a pointer to the actual cell which still resides in the library (precisely: in library.layout). The name of the new cell will be the name of library cell.

This method has been introduced in version 0.22.

unsigned int add_pcell_variant(unsigned int pcell_id,variant[] parameters)

Description: Creates a PCell variant for the given PCell ID with the given parameters

This method will create a PCell variant proxy for a local PCell definition. It will create the PCell variant for the given parameters. Note that this method does not allow to create PCell instances for PCell's located in a library. Use add_lib_pcell_variant for that purpose.

The new of the new cell will be the name of the PCell. If a cell with that name already exists, a new unique name is generated.

This method has been introduced in version 0.22.

unsigned int add_pcell_variant(Library ptr library,unsigned int pcell_id,variant[] parameters)

Description: Creates a PCell variant for a PCell located in an external library

This method will import a PCell from a library and create a variant for the given parameter set. Technically, this method creates a proxy to the library and creates the variant inside that library.

The new of the new cell will be the name of the PCell. If a cell with that name already exists, a new unique name is generated.

This method has been introduced in version 0.22.

[const] void assign(const Layout other)

Description: Assign the contents of another object to self

This method assigns the contents of another object to self. This is a deep copy that does not only copy the reference but the actual content.

[const] RecursiveShapeIterator begin_shapes(unsigned int cell_index,unsigned int layer)

Description: Delivers a recursive shape iterator for the shapes below the given cell on the given layer

For details see the description of the RecursiveShapeIterator class.

This method has been added in version 0.18.

[const] RecursiveShapeIterator begin_shapes_overlapping(unsigned int cell_index,unsigned int layer,Box region)

Description: Delivers a recursive shape iterator for the shapes below the given cell on the given layer using a region search

For details see the description of the RecursiveShapeIterator class. This version gives an iterator delivering shapes whose bounding box overlaps the given region.

This method has been added in version 0.18.

[const] RecursiveShapeIterator begin_shapes_touching(unsigned int cell_index,unsigned int layer,Box region)

Description: Delivers a recursive shape iterator for the shapes below the given cell on the given layer using a region search

For details see the description of the RecursiveShapeIterator class. This version gives an iterator delivering shapes whose bounding box touches the given region.

This method has been added in version 0.18.

Cell cell(unsigned int i)

Description: Gets a cell object from the cell index

unsigned int cell_by_name(string name)

Description: Get the cell index for a given name

Returns the cell index for the cell with the given name. If no cell with this name exists, an exception is thrown.

[const] string cell_name(unsigned int index)

Description: Get the name for a cell with the given index

[const] unsigned int cells

Description: Returns the number of cells

void clear

Description: Clears the layout

Clears the layout completely.

void clear_layer(unsigned int layer_index)

Description: Clear a layer

Clears the layer: removes all shapes.

This method was introduced in version 0.19.

unsigned int clip(unsigned int cell,const Box box)

Description: Clips the given cell by the given rectangle and produce a new cell with the clip

This method will cut a rectangular region given by the box from the given cell. The clip will be stored in a new cell whose index is returned. The clip will be performed hierarchically. The resulting cell will hold a hierarchy of child cells, which are potentially clipped versions of child cells of the original cell. This method has been added in version 0.21.

[const] unsigned int clip_into(unsigned int cell,Layout ptr box,const Box target)

Description: Clips the given cell by the given rectangle and produce a new cell with the clip

This method will cut a rectangular region given by the box from the given cell. The clip will be stored in a new cell in the target layout. The clip will be performed hierarchically. The resulting cell will hold a hierarchy of child cells, which are potentially clipped versions of child cells of the original cell.

Please note that it is important that the database unit of the target layout is identical to the database unit of the source layout to achieve the desired results.This method also assumes that the target layout holds the same layers than the source layout. It will copy shapes to the same layers than they have been on the original layout. This method has been added in version 0.21.

void copy_layer(unsigned int src,unsigned int dest)

Description: Copy a layer

This method was introduced in version 0.19.

Copy a layer from the source to the target. The target is not cleared before, so that this method merges shapes from the source with the target layer.

void create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

[const] double dbu

Description: Database unit read accessor

void dbu=(double dbu)

Description: Database unit write accessor

void delete_cell(unsigned int cell_index)

Description: Delete a cell

This deletes a cell but not the sub cells of the cell. These subcells will likely become new top cells unless they are used otherwise. All instances of this cell are deleted as well. Hint: to delete multiple cells, use "delete_cells" which is far more efficient in this case.

This method has been introduced in version 0.20.

void delete_cell_rec(unsigned int cell_index)

Description: Delete a cell plus all subcells

This deletes a cell and also all sub cells of the cell. In contrast to prune_cell, all cells are deleted together with their instances even if they are used otherwise.

This method has been introduced in version 0.20.

void delete_cells(unsigned int[] cell_index_list)

Description: Delete multiple cells

This deletes the cells but not the sub cells of these cells. These subcells will likely become new top cells unless they are used otherwise. All instances of these cells are deleted as well.

This method has been introduced in version 0.20.

void delete_layer(unsigned int layer_index)

Description: Delete a layer

This does free the shapes of the cells and remembers the layer's index for recycling.

void destroy

Description: Explicitly destroy the object

Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, this method will do nothing.

[const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

[const] Layout dup

Description: Creates a copy of self

[iter] Cell each_cell

Description: Iterates the unsorted cell list

[iter] unsigned int each_cell_bottom_up

Description: Iterates the bottom-up sorted cell list

In bottom-up traversal a cell is not delivered before the last child cell of this cell has been delivered. The bottom-up iterator does not deliver cells but cell indices actually.

[iter] unsigned int each_cell_top_down

Description: begin iterator of the top-down sorted cell list

The top-down cell list has the property of delivering all cells before they are instantiated. In addition the first cells are all top cells. There is at least one top cell. The top-down iterator does not deliver cells but cell indices actually.

[iter] unsigned int each_top_cell

Description: Iterates the top cells

A layout may have an arbitrary number of top cells. The usual case however is that there is one top cell.

void end_changes

Description: Cancel the "in changes" state (see "start_changes")

void flatten(unsigned int cell_index,int levels,bool prune)

Description: Flatten the given cell

This method propagates all shapes from the specified number of hierarchy levels below into the given cell. It also removes the instances of the cells from which the shapes came from, but does not remove the cells themselves if prune is set to false. If prune is set to true, these cells are removed if not used otherwise.

This method has been introduced in version 0.20.

[const] LayerInfo get_info(unsigned int index)

Description: Get the info structure for a specified layer

[const] unsigned int guiding_shape_layer

Description: Returns the index of the guiding shape layer

The guiding shape layer is used to store guiding shapes for PCell's.

This method has been added in version 0.22.

bool has_cell?(string name)

Description: Tell, if the cell with a given name exists

Returns true, if the layout has a cell with the given name

unsigned int insert_layer(const LayerInfo props)

Description: Insert a new layer with the given properties

void insert_layer_at(unsigned int index,const LayerInfo props)

Description: Insert a new layer with the given properties at the given index

unsigned int insert_special_layer(const LayerInfo props)

Description: Insert a new special layer with the given properties

Special layers can be used to represent objects that should not participate in normal viewing or other related operations. Special layers are not reported as valid layers.

void insert_special_layer_at(unsigned int index,const LayerInfo props)

Description: Insert a new special layer with the given properties at the given index

See insert_special_layer for a description of special layers.

[const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

[const] bool is_editable?

Description: Returns a value indicating whether the layout is editable.

If a layout is editable, in general manipulation methods are enabled and some optimisations are disabled (i.e. shape arrays are expanded).

This method has been introduced in version 0.22.

[const] bool is_special_layer?(unsigned int layer_index)

Description: Tell, if a layer index is a special layer index

[const] bool is_valid_cell_index?(unsigned int cell_index)

Description: Tell, if a cell index is a valid index

This method has been added in version 0.20.

[const] bool is_valid_layer?(unsigned int layer_index)

Description: Tell, if a layer index is a valid index

[const] unsigned int[] layer_indices

Description: Return a list of valid layer indices

This method returns an array with layer indices representing valid layers.

This method was introduced in version 0.19.

[const] unsigned int layers

Description: Return the number of layers

The number of layers reports the maximum (plus 1) layer index used so far. Not all of the layers with an index in the range of 0 to layers-1 needs to be a valid layer. These layers can be either valid, special or unused. Use is_valid_layer? and is_special_layer? to test for the first two states.

void move_layer(unsigned int src,unsigned int dest)

Description: Move a layer

This method was introduced in version 0.19.

Move a layer from the source to the target. The target is not cleared before, so that this method merges shapes from the source with the target layer. The source layer is empty after that operation.

unsigned int[] multi_clip(unsigned int cell,Box[] boxes)

Description: Clips the given cell by the given rectangles and produce new cells with the clips, one for each rectangle.

This method will cut rectangular regions given by the boxes from the given cell. The clips will be stored in a new cells whose indexed are returned. The clips will be performed hierarchically. The resulting cells will hold a hierarchy of child cells, which are potentially clipped versions of child cells of the original cell. This version is somewhat more efficient than doing individual clips because the clip cells may share clipped versions of child cells. This method has been added in version 0.21.

unsigned int[] multi_clip_into(unsigned int cell,Layout ptr boxes,Box[] target)

Description: Clips the given cell by the given rectangles and produce new cells with the clips, one for each rectangle.

This method will cut rectangular regions given by the boxes from the given cell. The clips will be stored in a new cells in the given target layout. The clips will be performed hierarchically. The resulting cells will hold a hierarchy of child cells, which are potentially clipped versions of child cells of the original cell. This version is somewhat more efficient than doing individual clips because the clip cells may share clipped versions of child cells.

Please note that it is important that the database unit of the target layout is identical to the database unit of the source layout to achieve the desired results. This method also assumes that the target layout holds the same layers than the source layout. It will copy shapes to the same layers than they have been on the original layout. This method has been added in version 0.21.

[static] new Layout new(Manager manager)

Description: Create a layout object attached to a manager

This constructor allows to specify a manager object which is used to store undo information for example. A layout created with this constructor inherits the editable mode from the application.

This method was introduced in version 0.19.

[static] new Layout new

Description: Create a layout object

A layout created with this constructor inherits the editable mode from the application.

[static] new Layout new(bool editable,Manager manager)

Description: Create a layout object attached to a manager

This constructor allows to specify a manager object which is used to store undo information for example. It also allows to specify whether the layout is editable. In editable mode, some optimisations are disabled and the layout can be manipulated through a variety of methods.

This method was introduced in version 0.22.

[static] new Layout new(bool editable)

Description: Create a layout object

This constructor allows to specify whether the layout is editable. In editable mode, some optimisations are disabled and the layout can be manipulated through a variety of methods.

This method was introduced in version 0.22.

[const] const PCellDeclaration ptr pcell_declaration(string name)

Description: Gets a reference to the PCell declaration for the PCell with the given name

Returns a reference to the local PCell declaration with the given name. If the name is not a valid PCell name, this method returns nil.

Usually this method is used on library layouts that define PCells. Note that this method cannot be used on the layouts using the PCell from a library.

This method has been introduced in version 0.22.

[const] const PCellDeclaration ptr pcell_declaration(unsigned int pcell_id)

Description: Gets a reference to the PCell declaration for the PCell with the given PCell ID.

Returns a reference to the local PCell declaration with the given PCell id. If the parameter is not a valid PCell ID, this method returns nil. The PCell ID is the number returned by register_pcell for example.

Usually this method is used on library layouts that define PCells. Note that this method cannot be used on the layouts using the PCell from a library.

This method has been introduced in version 0.22.

[const] unsigned int pcell_id(string name)

Description: Gets ID of the PCell with the given name

This method is equivalent to 'pcell_declaration(name).id'.

This method has been introduced in version 0.22.

[const] variant[] properties(unsigned int properties_id)

Description: Get the properties set for a given properties ID

Basically performs the backward conversion of the 'properties_id' method. Given a properties ID, returns the properties set as an array of pairs of variants. In this array, each key and the value are stored as pairs (arrays with two elements). If the properties ID is not valid, an empty array is returned.

unsigned int properties_id(variant[] properties)

Description: Get the properties ID for a given properties set

Before a set of properties can be attached to a shape, it must be converted into an ID that is unique for that set. The properties set must be given as a list of pairs of variants, each pair describing a name and a value. The name acts as the key for the property and does not need to be a string (it can be an integer or double value as well). The backward conversion can be performed with the 'properties' method.

void prune_cell(unsigned int cell_index,int levels)

Description: Delete a cell plus subcells not used otherwise

This deletes a cell and also all sub cells of the cell which are not used otherwise. The number of hierarchy levels to consider can be specified as well. One level of hierarchy means that only the direct children of the cell are deleted with the cell itself. All instances of this cell are deleted as well.

This method has been introduced in version 0.20.

void prune_subcells(unsigned int cell_index,int levels)

Description: Delete all sub cells of the cell which are not used otherwise down to the specified level of hierarchy

This deletes all sub cells of the cell which are not used otherwise. All instances of the deleted cells are deleted as well. It is possible to specify how many levels of hierarchy below the given root cell are considered.

This method has been introduced in version 0.20.

LayerMap read(string filename)

Description: Load the layout from the given file

The format of the file is determined automatically and automatic unzipping is provided. No particular options can be specified.

This method has been added in version 0.18.

LayerMap read(string filename,const LoadLayoutOptions options)

Description: Load the layout from the given file with options

The format of the file is determined automatically and automatic unzipping is provided. In this version, some reader options can be specified.

This method has been added in version 0.18.

unsigned int register_pcell(string name,PCellDeclaration ptr declaration)

Description: Registers a PCell declaration under the given name

Registers a local PCell in the current layout. If a declaration with that name alreay exists, it is replaced with the new declaration.

This method has been introduced in version 0.22.

void rename_cell(unsigned int index,string name)

Description: name

void set_info(unsigned int index,const LayerInfo props)

Description: Set the info structure for a specified layer

void start_changes

Description: Signal the start of an operation bringing the layout into invalid state

This method should be called whenever the layout is about to be brought into an invalid state. After calling this method, under_construction returns false which tells foreign code (such as update which might be called asynchronously for example because of a repaint event) not to use this layout object.

This state is cancelled by the end_changes method. The start_changes method can be called multiple times and must be cancelled the same number of times.

This method can be used to speed up certain operations. For example iterating over the layout with a RecursiveShapeIterator while modifying other layers of the layout can be very inefficent, because inside the loop the layout's state is invalidate and updated frequently. Putting a update and start_changes sequence before the loop (use both methods in that order!) and a end_changes call after the loop can improve the performance dramatically.

In addition, it can be necessary to prevent redraw operations in certain cases by using start_changes .. end_changes, in particular when it is possible to put a layout object into an invalid state temporarily.

void swap_layers(unsigned int a,unsigned int b)

Description: Swap layers

Swaps the shapes of both layers.

This method was introduced in version 0.19.

[const] bool under_construction

Description: Tell if the layout object is under construction

A layout object is either under construction if a transaction is ongoing or the layout is brought into invalid state by "start_changes".

void update

Description: Update the internals of the layout

This method updates the internal state of the layout. Usually this is done automatically This method is provided to ensure this state explicitly.

[const] void write(string filename,bool gzip,const SaveLayoutOptions options)

Description: Write the layout to a stream file

[const] void write(string filename)

Description: Write the layout to a stream file