Clipping Functions

(int) ClipAround(object_handle1, all1, object_handle2, all2)
This function will clip out the pieces of objects in the second handle list that intersect with objects in the first handle list.

If the boolean value all1 is nonzero, all objects in the first handle are used for clipping, otherwise only the first object is used. If the boolean value 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, all1, object_handle2, all2, lname)
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.

If the boolean value all1 is nonzero, all objects in the first handle are used for clipping, otherwise only the first object is used. If the boolean value 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 can be database objects or copies.

If lname 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) ClipTo(object_handle1, all1, object_handle2, all2)
This function will clip objects referenced by the second handle to the boundaries of objects referenced by the first handle.

If the boolean value all1 is nonzero, all objects in the first handle are used for clipping, otherwise only the first object is used. If the boolean value 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, all1, object_handle2, all2, lname)
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.

If the boolean value all1 is nonzero, all objects in the first handle are used for clipping, otherwise only the first object is used. If the boolean value 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 can be database objects or copies.

If lname 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) 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, all1, object_handle2, all2, lname)
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.