[Artwork] / [QisMLib]

QisMLib Data Structures

C++ API (qismbase.h)

struct QisMWindow

A data structure to hold rectangular window information

• The co-ordinate values are always in file units (e.g microns, inch, mils etc)

​x
struct QISMLIB_LNX_DECLSPEC QisMWindow
{
  double minX; /* lower-left x */
  double minY; /* lower-left y */
  double maxX; /* upper-right x */
  double maxY; /* upper-right y */

  QisMWindow(): minX(0.0), minY(0.0), maxX(0.0), maxY(0.0) {}

  /*----------------------------------------------------------------------------
  Test if the window is valid (width, height > threshold)
  ----------------------------------------------------------------------------*/
  bool Is_valid(const double threshold) const {
    return((maxX > (minX + threshold)) && (maxY > (minY + threshold)));
  }
};

class QisMBoxSet

xxxxxxxxxx
class QisMBoxSet { ... };

Interface that represents a container of boxes (rectangular windows)

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived).

• Get the latest version number.

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied).

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMBoxSet_cast(const int version) = 0;
virtual const void* QisMBoxSet_cast(const int version) const = 0;
virtual int QisMBoxSet_version() const = 0;

Add_box()

Add a box to the set

• name : name associated with the box to be added

• lx, ly, ux, uy : box extents (min-max)

• Return: number of items in the set

xxxxxxxxxx
virtual int Add_box(
  const char* name, const double lx, const double ly, const double ux,
  const double uy
  ) = 0;

Get_count()

Get number of boxes in the set

xxxxxxxxxx
virtual int Get_count() const = 0;

Get_box()

Get a box from the set

• `lx, ly, ux, uy : box extents (min-max)

• Return: name of the box (if !NULL), otherwise the specified index is invalid (out-of-bounds)

xxxxxxxxxx
virtual const char* Get_box(
  const int index, double& lx, double& ly, double& ux, double& uy
  ) const = 0; 

Reset()

Reset the contents

xxxxxxxxxx
virtual void Reset() = 0;

Copy()

Copy from another set (assign, not append)

xxxxxxxxxx
virtual void Copy(const QisMBoxSet* obj) = 0;

class QisMBoxSetV2

xxxxxxxxxx
class QisMBoxSetV2: public QisMBoxSet { ... };

Add_spec()

Add boxes based on a spec. string.

• spec : one of the following syntax :-

  xxxxxxxxxx
  "llur={name}:{lx},{ly},{ux},{uy}" 
  "llwh={name}:{lx},{ly},{width},{height}" 
  "cwh={name}:{cx},{cy},{width},{height}"
  "@llur={name}:{txt_file}" 
  "@whll={name}:{txt_file}" 
  "@whc={name}:{txt_file}" 
  "tilerc={name}:{roi_lx},{roi_ly},{roi_ux},{roi_uy}:{cols},{rows}[:{i},{j}]*" 
  "tilewh={name}:{roi_lx},{roi_ly},{roi_ux},{roi_uy}:{width},{height}[:{i},{j}]*" 
  "cxy={name}:{width},{height}[:{cx},{cy}]+" 
  "rand={name}:{roi_lx},{roi_ly},{roi_ux},{roi_uy}:{width},{height}:{count}"
  

• emsg, emsglen : error message buffer and buffer size

• returns the number of boxes added (0 implies no box added)

xxxxxxxxxx
virtual int Add_spec(const char* spec, char* emsg, const int emsglen) = 0;

struct QisMVector

Flags that indicate the type of vector

xxxxxxxxxx
struct QISMLIB_LNX_DECLSPEC QisMVector
{
  //Vector types
  enum Type {
    BOUNDARY='B', /* Closed polygons (at-least three points) */
    PATH='P', /* Open polygon segment with width */
    TEXT='T', /* Text elements */
    SREF='S', /* Single cell reference */
    AREF='A', /* Arrayed cell reference */
    AREF_ELEMENT='E', /* Single element of an Aref */
    FILTERED='F' /* Filetered Area (QisMBoundary) */
  };
  typedef void* Handle; /* Opaque handle to a vector. Needs to be type-casted
  to the appropriate struct-pointer before use */
};

struct QisMBoundary

A data structure to store information for QisMVector::BOUNDARY

• units/grid => file units in meter. E.g for a micron file with nanometer resolution, grid = 0.001 (microns) and units = 1e-9 (meter)

• No. vertices includes the first and the last point which are identical. E.g a rectangular boundary contains 5 vertices (10 x,y values). The 5th vertex is identical to the 1st since the boundary is closed

xxxxxxxxxx
struct QISMLIB_LNX_DECLSPEC QisMBoundary
{
  const char* parentCell; /* Parent cell name */
  const double* xy; /* An array of x,y co-ordinates for the boundary.
    This array contains vertNum x,y pairs or vertNum*2 values. The co-ordinates
    are in file units (e.g micron) */
  double grid; /* Size of a single database unit expressed in file units */
  double units; /* Size of a single database unit expressed in meter (m) */
  int nestingLevel; /* Hierarchy level of this item w.r.t the current view cell */
  int vertNum; /* No. vertices in the boundary */
  unsigned short layer; /* Layer number */
  unsigned short dataType; /* Datatype number */;

  QisMBoundary(): parentCell(0), xy(0), grid(1.0), units(1.0), nestingLevel(0),
    vertNum(0), layer(0), dataType(0) {}
};

struct QisMPath

A data structure to store information for QisMVector::PATH

• units/grid => file units in meter. E.g for a micron file with nanometer resolution, grid = 0.001 (microns) and units = 1e-9 (meter)

• A path is not closed so the last vertex and the first need not be the same

xxxxxxxxxx
struct QISMLIB_LNX_DECLSPEC QisMPath
{
  enum PathType { /* Path type flags */
    FLUSH='F', /* GDSII/OASIS Flush path */
    ROUND='R',  /* GDSII Round path */
    HALF_EXT='H' /* GDSII/OASIS half-extended path */
  };
  const char* parentCell; /* Parent cell name */
  const double* xy; /* An array of x,y co-ordinates for the path.
    This array contains vertNum x,y pairs or vertNum*2 values. The co-ordinates
    are in file units (e.g micron) */
  double grid; /* Size of a single database unit expressed in file units */
  double units; /* Size of a single database unit expressed in meter (m) */
  double width; /* Path width in file units */
  int nestingLevel; /* Hierarchy level of this item w.r.t the current view cell */
  int vertNum; /* No. vertices in the boundary */
  unsigned short layer; /* Layer number */
  unsigned short dataType; /* Datatype number */
  QisMPath::PathType type; /* Type of path */

  QisMPath(): parentCell(0), xy(0), grid(1.0), units(1.0), nestingLevel(0),
    vertNum(0), layer(0), dataType(0), type(QisMPath::FLUSH) {}
};

struct QisMText

A data structure to store information for QisMVector::TEXT

• units/grid => file units in meter. E.g for a micron file with nanometer resolution, grid = 0.001 (microns) and units = 1e-9 (meter)

xxxxxxxxxx
struct QISMLIB_LNX_DECLSPEC QisMText
{
  const char* parentCell; /* Parent cell name */
  const char* textstring; /* Text item string */
  const double* textBox; /* Extents box of the text item. Contains 5 vertices/
    10 values all in file units */
  double grid; /* Size of a single database unit expressed in file units */
  double units; /* Size of a single database unit expressed in meter (m) */
  double x; /* Insertion point x in file units */
  double y; /* Insertion point y in file units */
  int nestingLevel; /* Hierarchy level of this item w.r.t the current view cell */
  unsigned short layer; /* Layer number */
  unsigned short textType; /* Texttype number */

  QisMText(): parentCell(0),textstring(0), textBox(0), grid(1.0), units(1.0),
  x(0.0), y(0.0), nestingLevel(0), layer(0), textType(0){}
};

struct QisMSref

A data structure to store information for QisMVector::SREF

• units/grid => file units in meter. E.g for a micron file with nanometer resolution, grid = 0.001 (microns) and units = 1e-9 (meter)

• The transformation matrix is a 2x2 matric represented as

  xxxxxxxxxx
  | tm[0] tm[1] |
  | tm[2] tm[3] | 
  

  • It contains the cumulative transformation of the reference in the current view.

• If Xin,Yin is a point in the cell (in that referenced cell's space),

  xxxxxxxxxx
  Xout = (Tm[0]*Xin + Tm[1]*Yin) + InsertX
  Yout = (Tm[2]*Xin + Tm[3]*Yin) + InsertY
  

  • Where Xout,Yout is the transformed position of that point in the current view

• scale, angle and flipY are not cumulative

xxxxxxxxxx
struct QISMLIB_LNX_DECLSPEC QisMSref
{
  const char* parentCell; /* Parent cell name */
  const char* refCell; /* Name of the cell being referenced */
  const double* refBox; /* Extents box of the cell reference. Contains 5 x,y
    pairs/10 values all in file units */
  double tm[4]; /* Cumulative transformation matrix */
  double grid; /* Size of a single database unit expressed in file units */
  double units; /* Size of a single database unit expressed in meter (m) */
  double x; /* Insertion point x in file units */
  double y; /* Insertion point y in file units */
  double scale; /* Amount of scaling applied to this reference */
  double angle; /* Amount of rotation applied to this reference in degress
    (counter-clockwise) */
  int nestingLevel; /* Hierarchy level of this item w.r.t the current view cell */
  bool flipY; /* If true, the reference is reflected about X axis */

  QisMSref(): parentCell(0), refCell(0), refBox(0), grid(1.0), units(1.0),
    x(0.0), y(0.0), scale(1.0), angle(0.0), nestingLevel(0), flipY(false)
    {
      tm[0] = tm[1] = tm[2] = tm[3] = 0.0;
    }
};

struct QisMAref

A data structure to store information for QisMVector::AREF

• units/grid => file units in meter. E.g for a micron file with nanometer resolution, grid = 0.001 (microns) and units = 1e-9 (meter)

• The transformation matrix is a 2x2 matric represented as

  xxxxxxxxxx
  | tm[0] tm[1] |
  | tm[2] tm[3] | 
  

  • It contains the cumulative transformation of the reference in the current view.

• If Xin,Yin is a point in the cell (in that referenced cell's space),

  xxxxxxxxxx
  Xout = (Tm[0]*Xin + Tm[1]*Yin) + InsertX + (i*rowOffsetX + j*colOffsetX)
  Yout = (Tm[2]*Xin + Tm[3]*Yin) + InsertY + (i*rowOffsetY + j*colOffsetY)
  

  • Where Xout,Yout is the transformed position of that point in the current view and i,j are the row and column numbers for a particular aref element (0 <= i < nRows), (0 <= j < nColumns)

• scale, angle and flipY are not cumulative

struct QisMArrayElement

A data structure to store information for QisMVector::AREF_ELEMENT

xxxxxxxxxx
struct QISMLIB_LNX_DECLSPEC QisMArrayElement
{
  unsigned int column; /* Column position of the element (>=0, <nColumns) */
  unsigned int row; /* Row position of the element (>=0, <nRows) */
  unsigned int sequence; /* Sequence of the element in the array
    (>=1, <=(nRows*nColumns)) */
  unsigned int cellId; /* Unique identifier(index) of the cell being referenced */

  QisMArrayElement(): column(0), row(0), sequence(0), cellId(0) {}
};

class QisMNotify

xxxxxxxxxx
class QisMNotify { ... };

API for the various QisMLib notifications to be handled by the client software

Notification handler return codes

xxxxxxxxxx
enum {
  PASS_REFERENCE=101 /* For On_qismt_vector and for QisMVector::AREF,
  QisMVector::SREF and QisMVector::AREF_ELEMENT vectors only. Skip the
  processing of the reference (and it's entire sub-tree) in question and move
  on to the next element in the view.*/
};

Version Control

Cast a pointer to your handler to any type in the QisMNotify hierarchy using the version number.

• The version of a class is embedded in the name in form of a suffix V.

• The version of the topmost base class is 1. E.g if QisMNotify is the topmost base class (version 1), QisMNotifyV2 QisMNotifyV3 etc. would be the future extensions of QisMNotify.

• Return NULL if the version number is not recognized/implemented

xxxxxxxxxx
virtual void* QisMNotify_cast(const int version) = 0;
/* PLEASE ADD THE FOLLOWING IMPLEMENTATION IN YOUR HANDLER {
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<QisMNotify*>(this);
    //Add more casts based on the implementation of your handler
  }
  return 0;
} */
virtual const void* QisMNotify_cast(const int version) const = 0;
/* PLEASE ADD THE FOLLOWING IMPLEMENTATION IN YOUR HANDLER {
  switch(version) {
    case 0: return this;
    case 1: return dynamic_cast<const QisMNotify*>(this);
    //Add more casts based on the implementation of your handler
  }
  return 0;
} */
virtual int QisMNotify_latest_version() const = 0;
/* PLEASE ADD THE FOLLOWING IMPLEMENTATION IN YOUR HANDLER {
  return 1; //Return the newest version implemented by your handler
} */

On_qismt_warning()

Notifications containing warning messages

• pre : Formatting string to be used optionally as a prefix to the message

• msg : Message string

• post : Formatting string to be used optionally as a suffix to the message

• Currently used to report file open warnings (QisMLib::Load_file)

• The return code does not impact execution. It is recommended however to to return 0 from this notification

• In order to recieve this notification, the client handler must inherit the QisMNotify class and override this method. The address of the handler should be passed to the method that generates this notification

xxxxxxxxxx
virtual int On_qismt_warning(
  const char* pre, const char* msg, const char* post
  ) { return 0; }

On_qismt_progress()

Notifications containing progress updates

• pre : Formatting string to be used optionally as a prefix to the message

• msg : Message string

• post : Formatting string to be used optionally as a suffix to the message

• Currently used to report file open progress (QisMLib::Load_file)

• The return code DOES impact execution. If the return != 0, it is considered an indication to stop execution. Otherwise, the execution continues

• In order to recieve this notification, the client handler must inherit the QisMNotify class and override this method. The address of the handler should be passed to the method that generates this notification

xxxxxxxxxx
virtual int On_qismt_progress(
  const char* pre, const char* msg, const char* post
  ) { return 0; }

On_qismt_vector_data_begin()

Notification that database traversal (Get_vector_data) is about to begin

• newThread : true if a new thread was created for this traversal. false if the traversal will execute in the calling thread

• The return code does not impact execution. It is recommended however to to return 0 from this notification

• In order to recieve this notification, the client handler must inherit the QisMNotify class and override this method.

• The address of the handler should be passed to the method that generates this notification

xxxxxxxxxx
virtual int On_qismt_vector_data_begin(const bool newThread) { return 0; }

On_qismt_vector()

Notification for each data vector encoutered during database traversal (Get_vector_data)

• type : Type of vector datum

• handle : An opaque pointer to the data structure holding the information for this vector datum. It must be type-casted to the appropriate data structure before use

• clientHandle : A client specified handle that was passed to QisMExploder::Get_vector_data or QisMDrawObject::Get_display_vector_data

• Return 0 : Continue database traversal

• Return Non-zero : Terminate the database traversal. This will cause operation to return with error and the returned number will appear in the corresponding error message

• The handle to the vector datum should be typecasted as follows:

  • QisMVector::BOUNDARY => const QisMBoundary*

  • QisMVector::PATH => const QisMPath*

  • QisMVector::TEXT => const QisMText*

  • QisMVector::SREF => const QisMSref*

  • QisMVector::AREF => const QisMAref*

  • QisMVector::AREF_ELEMENT => const QisMArrayElement*

  • QisMVector::FILTERED => QisMBoundary*

• The information stored in this data structure is for read-only use and should not be motified by the client code

• The information available via this callback is temporary and valid only during the duration of this callback. The client must make a deep copy of any pointers as they may not be valid beyond this callback

• To terminate the operation, return a non-zero code from this callback

• If the operation is executed in an independent thread, it is the responsibility of the client to ensure the thread-safety of the code that executes within this callback

• It is forbidden to modify the state of the QisMExploder/QisMDrawObject while this operation is in progress

xxxxxxxxxx
virtual int On_qismt_vector(
  const QisMVector::Type type, const QisMVector::Handle handle,
  void* clientHandle
  ) { return 0; }

On_qismt_vector_data_end()

Notification that database traversal (Get_vector_data) is about to end

• newThread : true if a new thread was created for this traversal. false if the traversal will execute in the calling thread

• The return code does not impact execution. It is recommended however to to return 0 from this notification

• In order to recieve this notification, the client handler must inherit the QisMNotify class and override this method. The address of the handler should be passed to the method that generates this notification

• The client is forbidden to change the view settings of the current exploder until this notification is received

xxxxxxxxxx
virtual int On_qismt_vector_data_end(const bool newThread_) { return 0; }

class QisMNotifyRefresh

xxxxxxxxxx
class QisMNotifyRefresh: public QisMNotify { ... };

Extends QisMNotify to support refresh callbacks during drawing

On_qismt_refresh()

A refresh notification while the drawing is in progress

• true : Continue the drawing operation

• false : Terminate the drawing operation

• In order to recieve this notification, the client handler must inherit the QisMNotifyRefresh class and override this method. The address of the handler should be passed to QisMDrawObject::Redraw_direct or QisMDrawObject::Redraw_image methods with a non-zero refresh interval

• This callback will be triggered at regular refesh intervals until the drawing is complete or has been terminated

• This callback can be used to process GUI events and get partially drawn image during QisMDrawObject::Redraw_image

xxxxxxxxxx
virtual bool On_qismt_refresh() { return true; }

typedef QisMNotifyV2

xxxxxxxxxx
typedef QisMNotifyRefresh QisMNotifyV2;

class QisMThreadLock

Interface that represents a Mutex

Version Control

Cast to a pointer of another version in the class hierarchy (base/derived).

• Get the latest version number.

• Version numbers start at 1 and are reflected in the class name using the suffix V. E.g V

• The topmost base class is version 1 (V1 implied).

• The cast returns NULL if a version number is not recognized/implemented

xxxxxxxxxx
virtual const char* QisMThreadLock_name() const = 0;
virtual void* QisMThreadLock_cast(const int version) = 0;
virtual const void* QisMThreadLock_cast(const int version) const = 0;
virtual int QisMThreadLock_latest_version() const = 0;

Lock()

Unlock()

Begin (Lock)/End (Unlock) critical section

xxxxxxxxxx
virtual void Lock() {}
virtual void Unlock() {}

struct QisMError

Tags for various error conditions

xxxxxxxxxx
struct QisMError
{
  static const char* ETAG_OP__S() { return "operation failed - %s"; }
  static const char* ETAG_COND__S() { return "condition failed - %s"; }
  static const char* ETAG_PARAM__S() { return "invalid parameter - %s"; }
  static const char* ETAG_LICENSE__S() { return "license failed - %s"; }
  static const char* ETAG_FEATURE__S() { return "missing feature - %s"; }
};