23 Figure Set Functions

This chapter includes the following topics:

FigSet Functions

A FigSet is a high performance, ordered grouping of database geometric objects or other FigSets. A member of a FigSet is unique within that FigSet, but an object can be added to multiple FigSets. The name of a FigSet is unique within the cellview it is associated with.

FigSets offer high performance because they are not database objects and are not saved to the disk. Consequently, operations performed on a FigSet cannot be undone. If you delete an object that is a member of a FigSet, the object is removed from the FigSet, and when you undo delete, the object is restored, but it is not added back to the FigSet. To store the contents of a FigSet on the disk, you need to create a corresponding FigSetGroup. For information about FigSetGroups, see FigSetGroup Functions.

FigSet C APIs are used to create, find, move, copy, append, prepend, clone, clear, and delete objects from FigSets; to access FigSet parameters; and to iterate over the objects stored in a cellview.

To learn how to use FigSet and FigSetGroup functions, see Example- Using the FigSet and FigSetGroup Code.

Supported functions include:

txAppendFig

Boolean

txAppendFig(
txFigSetId fsId,
dbFigId    figId
);

Description

Adds the specified figure as a member to the end of the given FigSet.

Arguments

fsId	ID of a FigSet.
figId	ID of a figure.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txAppendFigSet

Boolean

txAppendFigSet(
txFigSetId fsId,
txFigSetId fsId2
);

Description

Adds the second FigSet as a member to the end of the first FigSet.

Arguments

fsId	ID of the first FigSet.
fsId2	ID of the second FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txClearFigSet

Boolean

txClearFigSet(
txFigSetId fsId
);

Description

Clears the contents of the specified FigSet.

Arguments

fsId

ID of a FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txCloneFigSet

Boolean

txCloneFigSet(
txFigSetId fsId,
txFigSetId fsId2
);

Description

Clears the contents of the first FigSet and then, copies the contents of the second FigSet to the first FigSet. The name for the first FigSet is copied from the name of the second FigSet.

Arguments

fsId	ID of the first FigSet.
fsId2	ID of the second FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txConcatFigSet

Boolean

txConcatFigSet(
txFigSetId fsId,
txFigSetId fsId2
);

Description

Concatenates the contents of the second FigSet to the end of the first FigSet. The contents of the second FigSet remain unchanged.

Arguments

fsId	ID of the first FigSet.
fsId2	ID of the second FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txCopyFigSet

txFigSetId

txCopyFigSet(
txFigSetId  srcFigSetId,
dbTransform transform
);

Description

Creates copies of each figure in the specified FigSet with the specified transform. A new FigSet containing the copied figures is returned. The copies are named automatically by using the convention FS_n, where n is a generated number that makes the name unique. So, the first FigSet name will be FS_0, then FS_1 and so on.

Arguments

srcFigSetId	ID of the source FigSet.
transform	The transformation object that is applied while copying figures in the given FigSet.

Return Value

txFigSetId

ID of the new FigSet.

txCreateFigSet

txFigSetId

txCreateFigSet(
dbCellViewId cvId,
constString  name
);

Description

Creates an empty FigSet in the specified cellview. If the name argument is specified, the FigSet is created with the specified name. If the name argument is not specified (NULL), the FigSet is named automatically. Automatic naming is done using the convention FS_n, where n is a generated number that makes the name unique. So, the first FigSet name will be FS_0, then FS_1 and so on.

Arguments

cvId	ID of the cellview where the new empty FigSet is created.
name	Name of the FigSet to be created.

Return Value

txFigSetId

ID of the new FigSet.

txDeleteFigSet

Boolean

txDeleteFigSet(
txFigSetId fsId,
Boolean    deep
);

Description

Deletes the specified FigSet, but the objects that it contains are not deleted. If the FigSet is a member of another FigSet, it is removed from that FigSet before it is deleted. Deleting the FigSet frees its associated memory immediately.

Arguments

fsId

ID of a FigSet.

deep

Specifies whether referenced FigSets should be deleted or not.

TRUE, if the referenced FigSets are to be deleted.

FALSE, if the referenced FigSets are not to be deleted.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txFindFigSet

txFigSetId

txFindFigSet
(dbCellViewId cvId,
constString  name
);

Description

Searches the cellview for a FigSet with the specified name. When searching for the FigSet, a matching FigSetGroup is also searched and, if necessary, a corresponding FigSet is resurrected automatically from it.

Arguments

cvId	ID of the cellview in which search is performed.
name	Name of the FigSet to search.

Return Value

txFigSetId

ID of the FigSet, if found.

Returns NULL, if the specified FigSet is not found.

txGetCellViewFigSets

txFigSetId *

txGetCellViewFigSets(
dbCellViewId cvId
);

Description

Returns an array of FigSets contained in the given design. The array is terminated by txcNullFigSetId.

Arguments

cvId

ID of the cellview in which the FigSets are searched.

Return Value

txFigSetId

Array containing IDs of all FigSets in the specified cellview.

txGetFigSetBBox

dbBBox *

txGetFigSetBBox(
txFigSetId    fsId,
unsigned int  numIncludeLayers,
dbLayer       *includeLayers,
unsigned int  numExcludeLayers,
dbLayer       *excludeLayers,
unsigned int  numIncludeLPPs,
txLPP         *includeLPPs,
unsigned int  numExcludeLPPs,
txLPP         *excludeLPPs,
unsigned int  numIncludeTypes,
dbType        *includeTypes,
unsigned int  numExcludeTypes,
dbType        *excludeTypes
);

Description

Calculates the bounding box for the objects in the specified FigSet and returns a pointer to the resulting bounding box. Optionally, included and excluded layers, LPPs, and object types can also be specified.

Arguments

fsId	ID of the FigSet in which the bounding box of the objects is calculated.
numIncludeLayers	Number of layers in the array of layers to be included.
includeLayers	Array of layers to be included.
numExcludeLayers	Number of layers in the array of layers to be excluded.
excludeLayers	Array of layers to be excluded.
numIncludeLPPs	Number of LPPs in the array of LPPs to be included.
includeLPPs	Array of LPPs to be included.
numExcludeLPPs	Number of LPPs in the array of LPPs to be excluded.
excludeLPPs	Array of LPPs to be excluded.
numIncludeTypes	Number of object types in the array of object types to be included.
includeTypes	Array of object types to be included.
numExcludeTypes	Number of object types in the array of object types to be excluded.
excludeTypes	Array of object types to be excluded.

Return Value

dbBBox

Pointer to the resulting bounding box.

Returns NULL, if there is any error in validating the arguments.

txGetFigSetCellView

dbCellViewId

txGetFigSetCellView(
txFigSetId fsId
);

Description

Returns the ID of the parent cellview for the specified FigSet.

Arguments

fsId

ID of a FigSet.

Return Value

dbCellViewId

ID of the parent cellview.

txGetFigSetEntry

Boolean

txGetFigSetEntry(
txFigSetId    fsId,
unsigned int  index,
txFigSetEntry *entry
);

Description

Retrieves the FigSet element at the specified index location and places it at the memory area specified using entry.

Arguments

fsId	ID of a FigSet.
index	Index of an entry in the array of elements of fsId.
entry	Pointer to the memory area where the FigSet entry will be placed.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txGetFigSetLength

unsigned int

txGetFigSetLength(
txFigSetId fsId
);

Description

Returns the number of objects in the specified FigSet.

Arguments

fsId

ID of a FigSet.

Return Value

unsigned int

Number of objects in the specified FigSet.

txGetFigSetName

String

txGetFigSetName(
txFigSetId fsId
);

Description

Returns the name for the specified FigSet.

Arguments

fsId

ID of a FigSet.

Return Value

String

Name of the specified FigSet.

txIsFigSet

Boolean

txIsFigSet(
txId id
);

Description

Determines whether the specified database object is a FigSet object.

Arguments

id	ID of a database object.

Return Value

Boolean

TRUE, if the specified object is a FigSet.

FALSE, if the specified object is not a FigSet, or if an error occurred.

txMakeFigSet

txFigSetId

txMakeFigSet(
dbFigSetGroupId  figSetGroupId
);

Description

Creates a FigSet from the given FigSetGroup and returns the new FigSet. The FigSet will be created if it does not exist; if it already exists, its contents will be replaced.

Arguments

figSetGroupId

ID of a FigSetGroup.

Return Value

txFigSetId

ID of the new FigSet.

txMoveFigSet

Boolean

txMoveFigSet(
txFigSetId  figSetId,
dbTransform transform
);

Description

Moves each figure in the specified FigSet by the specified transform.

Arguments

figSetId	ID of a FigSet.
transform	Transformation object that is applied while moving the figures in the specified FigSet`.`

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txPrependFig

Boolean

txPrependFig(
txFigSetId fsId,
dbFigId    figId
);

Description

Adds the specified figure as a member at the beginning of the specified FigSet.

Arguments

fsId	ID of a FigSet.
figId	ID of a figure.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txPrependFigSet

Boolean

txPrependFigSet(
txFigSetId fsId,
txFigSetId fsId2
);

Description

Adds the second FigSet as a member to the beginning of the first FigSet.

Arguments

fsId	ID of the first FigSet.
fsId2	ID of the second FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txRemoveFig

Boolean

txRemoveFig(
txFigSetId   fsId,
dbFigId      figId
);

Description

Removes the specified figure from the specified FigSet.

Arguments Return Value

fsId	ID of a FigSet.
figId	ID of a figure.

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txRemoveFigSet

Boolean

txRemoveFigSet(
txFigSetId   fsId,
txFigSetId   fsId2
);

Description

Removes the second FigSet from the first FigSet.

Arguments

fsId	ID of the first FigSet.
fsId2	ID of the second FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

txRemoveFigSetEntry

Boolean

txRemoveFigSetEntry(
txFigSetId   fsId,
unsigned int index
);

Description

Removes the entry at the specified index from the specified FigSet.

Arguments

fsId	ID of a FigSet.
index	Index of an entry in the array of elements of the specified FigSet.

Return Value

Boolean

TRUE, if the operation succeeded.

FALSE, if the operation failed.

FigSetGroup Functions

A FigSetGroup is a method to store the contents of a FigSet in a database for use in different sessions.

FigSetGroup C APIs are used to create, delete, access, manage, and search FigSetGroup objects.

To learn how to use FigSet and FigSetGroup functions, see Example- Using the FigSet and FigSetGroup Code.

Supported functions include:

dbDeleteFigSetGroup

Boolean

dbDeleteFigSetGroup(
dbFigSetGroupId   figSetGroupId,
);

Description

Deletes the specified FigSetGroup and the hierarchy of FigSetGroups that might exist in it.

Arguments

figSetGroupId

ID of the FigSetGroup to be deleted.

Return Value

Boolean

TRUE, if the operation succeeds.

FALSE, if the procedure fails.

dbFindFigSetGroup

dbFigSetGroupId

dbFindFigSetGroup(
dbCellViewId   cvId,
txFigSetId     figSetId
);

Description

Searches the specified cellview for a FigSetGroup that has the same name as the specified FigSet.

Arguments

cvId	ID of the cellview in which the search is performed.
figSetId	ID of the FigSet for which the matching FigSetGroup is being searched.

Return Value

dbFigSetGroupId

ID of the found FigSetGroup.

dbFindFigSetGroupByName

dbFigSetGroupId

dbFindFigSetGroupByName(
dbCellViewId   cvId,
constString    name
);

Description

Searches the specified cellview for a FigSetGroup with the specified name.

Arguments

cvId	ID of the cellview in which the search is performed.
name	Name of the FigSetGroup for which the search is performed.

Return Value

dbFigSetGroupId

ID of the FigSetGroup.

Returns dbcNullId, if the named FigSetGroup does not exist.

dbGenFigSetGroups

Boolean

dbGenFigSetGroups(
dbGenStateId  pState,
dbFigSetGroup *figSetGroupId
);

Description

Retrieves the next FigSetGroup ID from the generator with the given dbGenStateId. The FigSetGroup ID is returned in the figSetGroupId argument.

Arguments

pState	State ID for the generator.
figSetGroupId	ID of the next FigSetGroup produced by the generator. This value is undefined if `FALSE` is returned.

Return Value

Boolean

TRUE, if the next FigSetGroup ID is successfully generated.

FALSE, if the list is exhausted or an error occurs.

dbGetFigSetGroupName

String

dbGetFigSetGroupName(
dbFigSetGroupId figSetGroupId
);

Description

Returns the name for the specified FigSetGroup object.

Arguments

figSetGroupId

ID of a FigSetGroup object.

Return Value

String

Name of the FigSetGroup object.

dbIsFigSetGroup

Boolean

dbIsFigSetGroup(
dbId   id
);

Description

Indicates whether the specified dbId is a FigSetGroup object.

Arguments

id	ID of the database object to be checked.

Return Value

Boolean

TRUE, if the specified dbId is a FigSetGroup object.

FALSE, if the specified dbId is not a FigSetGroup object or in case of failure.

dbMakeFigSetGroup

dbFigSetGroupId

dbMakeFigSetGroup(
dbCellViewId cvId,
txFigSetId   figSetId
);

Description

Makes a FigSetGroup in the specified cellview that is associated with the specified FigSet and populates it with the contents of the FigSet. If a FigSetGroup with the same name as the specified FigSet does not exist, it is created and assigned the name of the FigSet. If such a FigSetGroup exists, its contents are cleared and replaced with the contents of the FigSet.

Arguments

cvId	ID of a cellview.
figSetId	ID of a FigSet.

Return Value

dbFigSetGroupId

ID of the created FigSetGroup.

dbStartGenFigSetGroups

dbGenStateId

dbStartGenFigSetGroups(
dbCellViewId    cellViewId
);

Description

Initializes a generator for all FigSetGroup objects in the specified cellview. A generator state is returned, which is used with the dbGenFigSetGroups function.

Arguments

cellViewId

ID of the cellview containing the FigSetGroups to be generated.

Return Value

dbGenStateId

State ID for the generator.

Example- Using the FigSet and FigSetGroup Code

The following example illustrates how to use the FigSet and FigSetGroup APIs.

void print(txFigSetId figSet) {

    txFigSetEntry entry;

    printf(" %s=> [", txGetFigSetName(figSet));

    for (unsigned int i = 0; i < txGetFigSetLength(figSet);i++) {

      txGetFigSetEntry(figSet, i, &entry);

      if (entry.type == txcFigureSetFig) {

          printf("rect%d ", dbGetShapeRec(entry.data.figId)->layer);

      } else {

          print(entry.data.figSetId);

    printf("] ");

void example() {

    dbBBox          bbox0;

    dbBBox          bbox1;

    dbFillBBox(&bbox0, 0, 0, 100, 100);

    dbFillBBox(&bbox1, -100, -100, 0, 0);

    dbCellViewId    cvId = dbOpenCellViewByType(libName, "rect", "layout",

                                     "maskLayout", "r", dbcNullCellViewId);

    dbRectId        rect0   = dbCreateRect(cvId, 0, dbcDrawingPurpose, &bbox0);

    dbRectId        rect1   = dbCreateRect(cvId, 1, dbcDrawingPurpose, &bbox1);

    // Create a FigSet hierarchy

    txFigSetId      figSetTop = txCreateFigSet(cvId, "topFigSet");

    txFigSetId      figSet0 = txCreateFigSet(cvId, NULL); // Auto-named ->"FS_0"

    txFigSetId      figSet1 = txCreateFigSet(cvId, NULL); // Auto-named ->"FS_1"

    txAppendFig(figSet0, rect0);

    txAppendFig(figSet1, rect1);

    txAppendFigSet(figSetTop, figSet1);

    txPrependFigSet(figSetTop, figSet0);

    txPrependFig(figSetTop, rect1);

    printf("Initial state\n");

    print(figSetTop);

    printf("\n");

    txFigSetId      clone = txCreateFigSet(cvId, "clone");

    if (txCloneFigSet(clone, figSetTop)) {

      printf("Clone\n");

      print(clone);

      printf("\n");

    if (txClearFigSet(clone)) {

      printf("After clearing the contents of the clone\n");

      print(clone);

      printf("\n");

    dbTransform     transform;

    transform.offset.x = 50000;

    transform.offset.y = 0;

    transform.orient   = dbcR0;

    transform.mag      = 1.;

    txFigSetId      copy = txCopyFigSet(figSetTop, transform);

    printf("Copy\n");

    print(copy);

    printf("\n");

    dbBBox          *figSetBBox = txGetFigSetBBox(figSetTop, 0, NULL, 0, NULL, 0, NULL, 0, NULL, 0, NULL,  0, NULL);

    dbLayer         layers[1] = {0};

    dbLayer         layers2[2] = {0, 1};

    printf("BBox of figSetTop : (%d, %d), (%d, %d)\n",

         figSetBBox->lowerLeft.x,  figSetBBox->lowerLeft.y,

         figSetBBox->upperRight.x, figSetBBox->upperRight.y);

    figSetBBox = txGetFigSetBBox(figSetTop, 1, layers, 0, NULL, 0, NULL,

                                    0, NULL, 0, NULL,  0, NULL);

    printf("BBox of figSetTop including only Layer 0: (%d, %d), (%d, %d)\n",

         figSetBBox->lowerLeft.x,  figSetBBox->lowerLeft.y,

         figSetBBox->upperRight.x, figSetBBox->upperRight.y);

    figSetBBox = txGetFigSetBBox(figSetTop, 0, NULL, 1, layers, 0, NULL,

                        0, NULL, 0, NULL,  0, NULL);

    printf("BBox of figSetTop excluding only Layer 0: (%d, %d), (%d, %d)\n",

         figSetBBox->lowerLeft.x,  figSetBBox->lowerLeft.y,

         figSetBBox->upperRight.x, figSetBBox->upperRight.y);

    figSetBBox = txGetFigSetBBox(figSetTop, 0, NULL, 2, layers2, 0, NULL,

                        0, NULL, 0, NULL,  0, NULL);

    printf("BBox of figSetTop excluding Layer 0 and 1: (%d, %d), (%d, %d)\n",

         figSetBBox->lowerLeft.x,  figSetBBox->lowerLeft.y,

         figSetBBox->upperRight.x, figSetBBox->upperRight.y);

   // Make a figSetGRoup and vice-versa.

    dbFigSetGroupId figSetGrouTop0 = dbMakeFigSetGroup(cvId, figSetTop);

    if (txClearFigSet(figSetTop)) {

      txMakeFigSet(figSetGrouTop0);

      printf("After resurecting the top FigSet from a FigSet group\n");

      print(figSetTop);

      printf("\n");

// Iterate on all the existing FigSetGroups and print their name.

    printf("Existing FigSet group : ");

    dbGenStateId    genState = dbStartGenFigSetGroups(cvId);

    dbFigSetGroupId figSetGroupId;

    while (dbGenFigSetGroups(genState, &figSetGroupId)) {

      printf("%s ", dbGetFigSetGroupName(figSetGroupId));

The example above generates the following output:

Initial state

topFigSet=> [rect1 FS_0=> [rect0 ] FS_1=> [rect1 ] ]

Clone

clone=> [rect1 FS_0=> [rect0 ] FS_1=> [rect1 ] ]

Clear the contents of the clone

clone=> []

Copy

FS_2=> [rect1 FS_3=> [rect0 ] FS_4=> [rect1 ] ]

BBox of figSetTop : (-100, -100), (100, 100)

BBox of figSetTop including only Layer 0: (0, 0), (100, 100)

BBox of figSetTop excluding only Layer 0: (-100, -100), (0, 0)

BBox of figSetTop excluding Layer 0 and 1: (0, 0), (0, 0)

After resurrecting the top FigSet from a FigSetGroup

topFigSet=> [rect1 FS_0=> [rect0 ] FS_1=> [rect1 ] ]

Existing FigSetGroup : topFigSet FS_0 FS_1

Return to top

Cadence Integrators Toolkit Database ReferenceProduct Version IC23.1, June 2023

23

Figure Set Functions

FigSet Functions

txAppendFig

Description

Arguments

Return Value

txAppendFigSet

Description

Arguments

Return Value

txClearFigSet

Description

Arguments

Return Value

txCloneFigSet

Description

Arguments

Return Value

txConcatFigSet

Description

Arguments

Return Value

txCopyFigSet

Description

Arguments

Return Value

txCreateFigSet

Description

Arguments

Return Value

txDeleteFigSet

Description

Arguments

Return Value

txFindFigSet

Description

Arguments

Return Value

txGetCellViewFigSets

Description

Arguments

Return Value

txGetFigSetBBox

Description

Arguments

Return Value

txGetFigSetCellView

Description

Arguments

Return Value

txGetFigSetEntry

Description

Arguments

Return Value

txGetFigSetLength

Description

Arguments

Return Value

txGetFigSetName

Description

Arguments

Return Value

txIsFigSet

Description

Arguments

Return Value

txMakeFigSet

Description

Arguments

Return Value

txMoveFigSet

Description

Arguments

Return Value

txPrependFig

Description

Arguments

Return Value

Cadence Integrators Toolkit Database Reference
Product Version IC23.1, June 2023