QisMLib Header

QisMBool API

The QisMBool group of functions is used for Boolean operations on polygons produced by QisMExplode.

api and classes for qislibm.so QisMlib API QisMFile API QisMExplode API QisMDraw API QisMBool API QisMView Super Class

Click on any of the API class boxes in the illustration to get details on specific functions.



QisMBool API

Creating a QisMBool Instance

Description

This function is used to create or destroy an instance of QisMBool

Syntax

  virtual QisMBoolInst* Create_instance
          (
            const int argC, 
            const char* const* argT, 
            void* const* argV
           ) 
  = 0;


  virtual void Destroy_instance(QisMBoolInst* handle) = 0;

Parameters

 argC - Reserved for internal use
 argT - Reserved for internal use
 argV - Reserved for internal use

Notes

Every instance of QisMBool created using Create_instance() must be destroyed using Destroy_instance() to avoid memory leaks


Create/Destroy/ Boolean Settings Object

Description

This function is used to Create/Destroy an instance of the Boolean settings object

Syntax

  virtual QisMBoolSettings* New_settings() = 0;
  virtual void Delete_settings(QisMBoolSettings* handle_) = 0;

Notes

Every instance of QisMBool created using New_settings() must be destroyed using Delete_settings() to avoid memory leaks


QisMBool Extension Interface

Description

To get access to this interface, call QisMLib::Get_extension_api with QISMEXTENSION_QISMBOOL as the api name and typecast (dynamic_cast) to QisMBool*

Syntax

 #define QISMEXTENSION_QISMBOOL "QisMBool"
 #define QISMCODE_QISMBOOL 11047
 class QisMBool: public QisMExtensionAPI

Clipping Window

Description

Set or Get the extents of the clipping window. The default is OFF (i.e. 0,0,0,0) The units are in the GDSII or OASIS database units (for a micron GDSII file with resolution = 0.001, 1 dbu = 1 nanometer.)

clipping window

Syntax

virtual void Clip_window
                         ( const int minX, 
                           const int minY, 
                           const int maxX, 
                           const int maxY
                          ) 
  = 0;

  virtual int Clip_window_minX() const = 0;
  virtual int Clip_window_minY() const = 0;
  virtual int Clip_window_maxX() const = 0;
  virtual int Clip_window_maxY() const = 0;

Parameters

minX, minY are the lower left coordinate of the clipping window
maxX, maxY are the upper right coordinate of the clipping window

Polygon with Holes - Output Options

Description

When dealing with a polygon with holes or when a Boolean operation produces a polygon with a hole there are different ways to represent it in the output: as a Leonov polygon (outer parent, one or more inner children; as a polygons with cutlines (also known as a keyhole polygon); as two or more butting polygons.

polygon hole options

Syntax

  virtual void Leonov_output(const QisMBoolFlag::Leonov mode) = 0;
  virtual QisMBoolFlag::Leonov Leonov_output() const = 0;

Flags

enum Leonov {
             LNV_OUT_CUTLINES=0,
             LNV_OUT_LEONOV=1, 
             LNV_OUT_BUTTING=-1,
             LNV_OUT_ENH_CUTLINES=2
            };

Notes

LNV_OUT_ENH_CUTLINES=2 - Introduces cutlines just like LNV_OUT_CUTLINES with insertion of redundant vertices at suitable locations along a cutline to make the polygon more resilient to transformations.


Polygon Sizing Mode

Description

Read or Set the sizing settings (also known as edge bias) value and behavior with this function. The default setting is no sizing.

Syntax

  virtual void Sizing_mode(const QisMBoolFlag::Sizing mode) = 0;
  virtual QisMBoolFlag::Sizing Sizing_mode() const = 0;

Flags

enum Sizing {
             NO_SIZING=0,
             STD_SIZING=1,
             ISOTR_SIZING=2,
             NONISOTR_SIZING=3
            };

Polygon Sizing Value

Description

Sets the amount of sizing (see Polygon Sizing Mode above) in dbu.

Syntax

  virtual void Sizing(const double value) = 0;
  virtual double Sizing() const = 0;

Maximum Polygon Vertex Count

Description

Set or Get the maximum polygon vertex count. If an output polygon contains more vertices than the maximum, it will be split into smaller butting polygons. Default value is 8190 which is related the maximum number of vertices that could be referenced in a GDSII record. If you do not plan on creating GDSII with the output data you can exceed this value.

polygons that exceed the max vertex count are split into two or more as needed to keep under the maximum.

Syntax

  virtual void Max_points(const int value) = 0;
  virtual int Max_points() const = 0;

Edge Overlap Butting Polygons

Description

Set or Get the value (in dbu) of overlap between butting polygons - these are created by the option LNV_OUT_BUTTING=-1 when slicing polygons with holes. The default is no overlap.

overlap can be applied to polygons with holes that are sliced into butting polygons.

Syntax

  virtual void Overlap(const double value) = 0;
  virtual double Overlap() const = 0;

Boolean Operation - Single Threaded

This function is used for Boolean operations on either a single or two sets of polygons. Before calling this function, the programmer should have checked the various settings and flags (or explicitly set them) to insure that the operation will proceed as intended.

Syntax

virtual bool BooleanST(
                        const int* const* xy1, 
                        const int* nv1, 
                        const int n1,
                        const int* const* xy2, 
                        const int* nv2, 
                        const int n2,
                        const QisMBoolSettings* options, 
                        const QisMBoolFlag::OpCode opCode, 
                        int*** xyO, 
                        int** nvO, 
                        int* nO
                      ) 
= 0;

Parameters

 xy1 -     Array of xy co-ordinates per polygons in set 1
 nv1 -     Array of number of vertices per polygon in set 1
 n1 -      Number of polygons in set 1
 xy2 -     Array of xy co-ordinates per polygon in set 2 (NULL for OP_UNARY_UNION)
 nv2 -     Array of number of vertices per polygon in set 2 (NULL for OP_UNARY_UNION)
 n2 -      Number of polygons in set 2 (0 for OP_UNARY_UNION)
 options - Handle to a boolean settings object
 opCode -  A numeric code to specify the Boolean operation to be performed between the two sets. 
           Any one of QisMBoolFlag::OpCode
 xyO -     Buffer to retrieve the array of xy co-ordinates of the output polygons
 nvO -     Buffer to retrieve the array of number of vertices per output polygon
 nO -      Buffer to retrieve the number of output polygons

Return

Success : true
Failure : false. Call Get_last_error_msg() or Get_last_error_code() to get details.

Notes

This method allocates new memory to store the output polygons. This memory must be released eventually using Release() to avoid memory leaks

.

Union Operation - Multi Threaded

This function is used to unionize a set of polygons and uses multiple threads to do so.

Syntax

  virtual bool UnionMT(
                       const int* const* xy, 
                       const int* nv, 
                       const int n, 
                       const QisMBoolSettings* options, 
                       const int thrnum,
                       int*** xyO, 
                       int** nvO, 
                       int* nO
                       ) 
= 0;

Parameters

 xy      -  Array of xy co-ordinates per polygons in set 1
 nv      -  Array of number of vertices per polygon in set 1
 n       -  Number of polygons in set 1
 options -  Handle to a boolean settings object
 opCode  -  A numeric code to specify the Boolean operation to be performed between the two sets.
 thrnum  -  Number of concurrent threads to be used to perform this operation
 xyO     -  Buffer to retrieve the array of xy co-ordinates of the output polygons
 nvO     -  Buffer to retrieve the array of number of vertices per output polygon
 nO      -  Buffer to retrieve the number of output polygons

Return

Success : true
Failure : false. Call Get_last_error_msg() or Get_last_error_code() to get details.

Notes

This method allocates new memory to store the output polygons. This memory must be released eventually using Release() to avoid memory leaks

.

Boolean Operation - Multi Threaded

This function is used for Boolean operations on either a single or two sets of polygons. Before calling this function, the programmer should have checked the various settings and flags (or explicitly set them) to insure that the operation will proceed as intended.

Syntax

virtual bool BinaryMT(
                        const int* const* xy1, 
                        const int* nv1, 
                        const int n1,
                        const int* const* xy2, 
                        const int* nv2, 
                        const int n2,
                        const QisMBoolSettings* options, 
                        const QisMBoolFlag::OpCode opCode, 
                        const int thrnum
                        int*** xyO, 
                        int** nvO, 
                        int* nO
                      ) 
= 0;

Parameters

 xy1 -     Array of xy co-ordinates per polygons in set 1
 nv1 -     Array of number of vertices per polygon in set 1
 n1 -      Number of polygons in set 1
 xy2 -     Array of xy co-ordinates per polygon in set 2 (NULL for OP_UNARY_UNION)
 nv2 -     Array of number of vertices per polygon in set 2 (NULL for OP_UNARY_UNION)
 n2 -      Number of polygons in set 2 (0 for OP_UNARY_UNION)
 options - Handle to a boolean settings object
 opCode -  A numeric code to specify the Boolean operation to be performed between the two sets. 
           Any one of QisMBoolFlag::OpCode
thrnum -   Number of concurrent threads to be used to perform this operation
 xyO -     Buffer to retrieve the array of xy co-ordinates of the output polygons
 nvO -     Buffer to retrieve the array of number of vertices per output polygon
 nO -      Buffer to retrieve the number of output polygons

Return

Success : true
Failure : false. Call Get_last_error_msg() or Get_last_error_code() to get details.

Notes

This method allocates new memory to store the output polygons. This memory must be released eventually using Release() to avoid memory leaks

.

Releasing Memory

Description

After calling any of the Boolean/Union Operations (BooleanST, BinaryMT or UnionMT) the memory allocated by these functions to store the output polygons should be released.

Syntax

 virtual void Release(int** xyO, int* nvO, const int nO) = 0;

Parameters

xyO -  Array of the X,Y co-ordinates of the output polygons
nvO -  Array of number of vertices for each output polygon
nO  -  Number of output polygons.

Notes

Every successful call to BooleanST(), UnionMT() or BinaryMT() must be eventually matched by a call to this function or a memory leak will occur

See Polygon Representations for more information on polygon representation.




QisMBool Errors

Description

Error codes and their description

Syntax

struct QisMBoolError
{
  enum Create_instance_codes
   {
    CI_BOOL_INIT=-1    /* Failed to initialize boolean [<code>] */
   ,CI_LICENSE=-2      /* Failed to acquire qismbool license, <why> */
   };
  enum BooleanST_codes 
   {
    BST_INV_SET1=-1    /* Invalid input polygon set */
   ,BST_INV_OUT=-2     /* Invalid output polygon set */
   ,BST_ILL_POLYS=-3   /* Input contains illegal polygons [<code>] */
   ,BST_OPEN_POLYS=-4  /* Data contains at least one open polygon */
   ,BST_INTERNAL=-5    /* Internal error [<code>] */
   };
  enum UnionMT_codes 
   {
    UMT_INV_SET=-1    /* Invalid input polygon set */
   ,UMT_INV_OUT=-2    /* Invalid output polygon set */
   ,UMT_INTERNAL=-3   /* Internal error [<code>] */
   }; 
  enum BinaryMT_codes 
   {
    BMT_INV_SET1=-1   /* Invalid input polygon set */
   ,BMT_INV_OUT=-2    /* Invalid output polygon set */
   ,BMT_INTERNAL=-3   /* Internal error [<code>] */
   ,BMT_INV_OPCODE=-4 /* Invalid operation code <code> */
   };
};

Last Error Condition

Description

Get more information about the last error condition.

Syntax

 virtual const char* Get_last_error_msg() const = 0;
 virtual int Get_last_error_code() const = 0;