next up previous contents index
Next: Other Object Management Functions Up: Geometry Creation and Management Previous: Pseudo-Flat Generator Functions   Contents   Index

Clipping Functions

(int) ClipAround(object_handle1, object_handle2 [, all1, all2])
This function will clip out the pieces of objects in the second handle list that intersect with objects in the first handle list. The third and fourth arguments are optional, and default to 0 if not given. If all1 is nonzero, all objects in the first handle are used for clipping, otherwise only the first object is used. If all2 is nonzero, all objects in the second handle list may be clipped, otherwise only the first object in the list is a candidate for clipping. Only boxes, polygons, and wires that appear in the second handle list will be clipped. The objects in the first handle list can be of any type, and labels and subcells will use the bounding box. The objects in the second list must be database objects, if they are are copies, no clipping is performed. The objects in the first list can be copies.

The newly created objects are added to the front of the second handle list, and the original object is removed from the list. The return value is the number of objects created, or -1 if either handle is empty or some other error occurred. The function fails if either handle does not reference an object list.

(object_handle) ClipAroundCopy(object_handle1, object_handle2 [, lname, all1, all2])
This function is similar to ClipAround, however no new objects are created in the database, and neither of the lists passed as arguments is altered. Instead, a new object list handle is returned, which references a list of ``copies'' of objects that are created by the clipping. The new objects are the pieces of the object or objects referenced by the second handle that do not intersect the object or objects referenced by the first handle. The remaining arguments are optional, and default to 0 if not given. The all1 and all2 are flags specifying whether to use all objects in the respective lists, or just the first, as in ClipAround. Unlike ClipAround, the second handle can reference object copies.

If lname is given and is a non-empty string, it is taken as the name for a layer on which all of the returned objects will be placed. The layer will be created if it does not exist. If zero or an empty or null string is passed, the object copies will retain the layer of the original object from the second handle list.

The returned list can be used by most functions that expect a list of objects, however they are not copies of ``real'' objects. If no new object copy would be created by clipping, the function returns 0. The function will fail if either handle is not an object-list handle.

(int) ClipAroundAll(object_handle1, object_handle2)
This function is deprecated -- see ClipAround.
This function is similar to the ClipAround function, however all items in both object lists are processed. New objects created are added to the front of the object_handle2 list. Objects that are deleted are removed from both lists. Objects that appear in both lists will be deleted, unlike ClipAround. HandlePurgeList can be called to eliminate these objects should this be a potential problem. The returned value is the total number of new objects created, or -1 if there was an error. Any object can appear in the object_handle1 list, the bounding box is used for labels and subcells. Only boxes, polygons, and wires in the object_handle2 list will be processed. The function fails it either handle does not reference a list of objects.

(object_handle) ClipAroundAllCopy(object_handle1, object_handle2)
This function is deprecated -- see ClipAround.
This function is similar to ClipAroundAll, however no new objects are created in the database, and neither of the lists passed as arguments is touched. Instead, a new object list handle is returned, which references a list of ``copies'' of objects that are created by the clipping. The new objects are the pieces of the objects referenced by the second handle that do not intersect the objects referenced by the first handle. The returned list can be used just as any list of object copies, however they are not copies of "real" objects. If no new object would be created by clipping, the function returns 0. Unlike ClipAroundAll, the second handle can reference object copies.

(int) ClipTo(object_handle1, object_handle2 [, all1, all2])
This function will clip objects referenced by the second handle to the boundaries of objects referenced by the first handle. The third and fourth arguments are optional, and default to 0 if not given. If all1 is nonzero, all objects in the first handle are used for clipping, otherwise only the first object is used. If all2 is nonzero, all objects in the second handle list may be clipped, otherwise only the first object in the list is a candidate for clipping. Only boxes, polygons, and wires that appear in the second handle list will be clipped. The objects in the first handle list can be of any type, and labels and subcells will use the bounding box. The objects in the second list must be database objects, if they are are copies, no clipping is performed. The objects in the first list can be copies.

The newly created objects are added to the front of the second handle list, and the original object is removed from the list. The return value is the number of objects created, or -1 if either handle is empty or some other error occurred. The function fails if either handle does not reference an object list.

(object_handle) ClipToCopy(object_handle1, object_handle2 [, lname, all1, all2])
This function is similar to ClipTo, however no new objects are created in the database, and neither of the lists passed as arguments is altered. Instead, a new object list handle is returned, which references a list of ``copies'' of objects that are created by the clipping. The new objects are the pieces of the object or objects referenced by the second handle that intersect the object or objects referenced by the first handle. The remaining arguments are optional, and default to 0 if not given. The all1 and all2 are flags specifying whether to use all objects in the respective lists, or just the first, as in ClipTo. Unlike ClipTo, the second handle can reference object copies.

If lname is given and is a non-empty string, it is taken as the name for a layer on which all of the returned objects will be placed. The layer will be created if it does not exist. If zero or an empty or null string is passed, the object copies will retain the layer of the original object from the second handle list.

The returned list can be used by most functions that expect a list of objects, however they are not copies of ``real'' objects. If no new object copy would be created by clipping, the function returns 0. The function will fail if either handle is not an object-list handle.

(int) ClipToAll(object_handle1, object_handle2)
This function is deprecated -- see ClipTo.
This is similar to the ClipTo function, however all objects in the handle lists are processed. Only the parts of the boxes, polygons, and wires in the second object list that overlap one of the objects in the first list will remain. Labels and subcells in the second list are ignored. The newly created objects are added to the front of the second handle list. The return value is the number of new objects created, or -1 if either handle is empty or some other error occurred. The function will fail if either handle does not reference an object list.

(object_handle) ClipToAllCopy(object_handle1, object_handle2)
This function is deprecated -- see ClipTo.
This function is similar to ClipToAll, however no new objects are created in the database, and neither of the lists passed as arguments is touched. Instead, a new object list handle is returned, which references a list of ``copies'' of objects that are created by the clipping. The new objects are the pieces of the objects referenced by the second handle that intersect the objects referenced by the first handle. The returned list can be used just as any list of object copies, however they are not copies of "real" objects. If no new object would be created by clipping, the function returns 0. Unlike ClipToAll, the second handle can reference object copies.

(int) ClipObjects(object_handle, merge)
This function will clip boxes, polygons, and wires in the list on the same layer as the first such object in the list so that none of these objects overlap. Newly created objects are added to the front of the handle list, and deleted objects are removed from the list. Objects in the list that are not on the same layer as the first box, polygon, or wire or are not boxes, polygons or wires are ignored. If the merge argument is nonzero, adjacent new objects will be merged, otherwise the pieces will remain separate objects. If successful, the number of newly created objects is returned, otherwise -1 is returned. The function will fail if the handle does not reference an object list.

(object_handle) ClipIntersectCopy(object_handle1, object_handle2, lname, all1, all2)
This function returns a list of object copies which represent the exclusive-or of box, polygon, and wire objects in the two object lists passed. The lists are not altered in any way, and the new objects, being ``copies'', are not added to the database. Objects found in the lists that are not boxes, polygons, or wires are ignored. The new objects are placed on the layer with the name given in lname, which is created if it does not exist, independent of the originating layer of the objects. If a null string or 0 is passed for lname, the target layer is the first layer found in object_handle1, or object_handle2 if object_handle1 is empty. The all1 and all2 are integer arguments indicating whether to use only the first object in the list, or all objects in the list. If nonzero, then all boxes, polygons, and wires in the corresponding list will be used, otherwise only the first box, polygon, or wire will be processed. On success, a handle to a list of object copies is returned, zero is returned otherwise. A fatal error is triggered if either argument is not a handle to a list of objects.


next up previous contents index
Next: Other Object Management Functions Up: Geometry Creation and Management Previous: Pseudo-Flat Generator Functions   Contents   Index
Stephen R. Whiteley 2006-10-23