[Artwork] / [QisMLib] / [Programmer's Corner]

QisMGbrPS C++ API (qismgbrps.h)

QisMGbrPSNotify

• Represents an interface to recieve notifications from QisMGbrPS

class QisMGbrPSNotify { ... };

Version control (QisMGbrPSNotify)

• 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<number>. E.g <baseclass>V<version>
• 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* QisMGbrPSNotify_name() const = 0;
virtual void* QisMGbrPSNotify_cast(const int version) = 0;
virtual const void* QisMGbrPSNotify_cast(const int version) const = 0;
virtual int QisMGbrPSNotify_latest_version() const = 0;

On_qismgbr_progress

• Callback to get progress message while Gbr is being processed
• Return 0 to continue, non-zero to terminated the load

xxxxxxxxxx
virtual int On_qismgbr_progress(const char* msg) { return 0; }

QisMGbrPSOpts

• Represents an object to store options for importing Gbr

xxxxxxxxxx
class QisMGbrPSOpts { ... };

ParamType

• Represents the parameter to be Set or Get

• PRM_DBG is used to preseve temp. files for troubleshooting

  • Set: MUST be followed by an int 1 (ON) or 0 (OFF)
  • Get: MUST be followed by int* to get the setting value
  • Default: 0

• PRM_UM is used to set um as the units for all user specified values

  • Set: MUST be followed by an int value from QisMGbrPSOpts::UnitType
  • Get: MUST be followed by int* to get the setting value
  • Default: Same units as the Gerber file

• PRM_MAXPTS is used to set the max. no. vetices per output polygon

  • Set: MUST be followed by an int value >= 4
  • Get: MUST be followed by int* to get the setting value
  • Default: 8190

• PRM_ARCRES is used to control the arc resolution (degrees) (smoothing of arcs)

  • Set: MUST be followed by a double value
  • Get: MUST be followed by double* to get the setting value
  • Default: 45

• PRM_ARCSAG is used to control the chord error (smoothing of arcs)

  • Set: MUST be followed by a double value
  • Get: MUST be followed by double* to get the setting value
  • Default: 1

• PRM_ARCSAGUNIT is used to indicate the units associated with the chord error

  • Set: MUST be followed by an int value from QisMGbrPSOpts::UnitType
  • Get: MUST be followed by int* to get the setting value
  • Default: UnitType::PRM_UM

• PRM_THRNUM is used to control the no. threads used for gerber processing

  • Set: MUST be followed by an int value > 0
  • Get: MUST be followed by int* to get the setting value
  • Default: no. cpu(s) in the system

• PRM_SPLITARGS is used to pass advanced arguments to the underlying gerber processor

  • Set: MUST be followed by a const char* of arguments separated by <space>
  • Get: MUST be followed by const char** to get the setting value
  • Default: <empty string>
  • To be used only in consultation with the Artwork team

• PRM_ROT90 is used to rotate the design by a multiple of 90 deg. before loading

  • Set: MUST be followed by int that is multipled by 90 to form the angle
  • Get: MUST be followed by int* to get the setting value
  • Default: 0
  • Rotation is performed before mirror

• PRM_MIRROR is used to reflex the design about X, Y or both before loading

  • Set: MUST be followed by int value from QisMGbrPSOpts::Mirror
  • Get: MUST be followed by int* to get the setting value
  • Default: Mirror::M_N
  • Rotation is performed before mirror

• PRM_SCALEX is used to scale the design along X before loading

  • Set: MUST be followed by double value > 0.0
  • Get: MUST be followed by double* to get the setting value
  • Default: 1.0

• PRM_SCALEY is used to scale the design along Y before loading

  • Set: MUST be followed by double value > 0.0
  • Get: MUST be followed by double* to get the setting value
  • Default: 1.0

xxxxxxxxxx
enum ParamType {
  PRM_DBG=1,
  PRM_UM,
  PRM_MAXPTS,
  PRM_ARCRES,
  PRM_ARCSAG,
  PRM_ARCSAGUNIT,
  PRM_THRNUM,
  PRM_SPLITARGS,
  PRM_ROT90,
  PRM_MIRROR,
  PRM_SCALEX,
  PRM_SCALEY
};

UnitType

• Codes for various units supported by QisMGbrPS

xxxxxxxxxx
enum UnitType {
  GBR_UNIT_MM = 0,
  GBR_UNIT_CM,
  GBR_UNIT_UM,
  GBR_UNIT_INCH,
  GBR_UNIT_MILS
};

Mirror

• Codes for types of mirroring
• M_N - no mirroring
• M_X - flip (negate) x
• M_Y - flip (negate) y
• M_XY - flip (negate) x and y

xxxxxxxxxx
enum Mirror {
  M_N=0,
  M_X,
  M_Y,
  M_XY
};

Version control (QisMGbrPSOpts)

• 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<number>. E.g <baseclass>V<version>
• 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* QisMGbrPSOpts_name() const = 0;
virtual void* QisMGbrPSOpts_cast(const int version) = 0;
virtual const void* QisMGbrPSOpts_cast(const int version) const = 0;
virtual int QisMGbrPSOpts_latest_version() const = 0;

Set_param

Get_param

• Set/Get value for a specific option
• type is a code for the option type. It can be any one of QisMGbrPSOpts::ParamType
• ... is used to pass the variable holding the value. It's type and count depends on the paramter in question.
• Returns true if the paramter type was recognized and processed. false implies unknown/unsupported paramter type

xxxxxxxxxx
virtual bool Set_param(const int type, ...) = 0;
virtual bool Get_param(const int type, ...) const = 0;

Reset (QisMGbrPSOpts)

• Reset options to default values

xxxxxxxxxx
virtual void Reset() = 0;

Clone

• Create a clone from the current object. MUST be eventually destroyed using QisMGbrPS::Delete_object

xxxxxxxxxx
virtual QisMGbrPSOpts* Clone() const = 0;

Copy

• Copy settings from another object

xxxxxxxxxx
virtual bool Copy(const QisMGbrPSOpts* obj) = 0;

QisMGbrPSFile

• Represents a single database created from Gbr source

xxxxxxxxxx
class QisMGbrPSFile { ... };

MetaInfo

• Represents the type of information about the Gerber source to be queried

• MIF_IP_POS checks if the Gerber file polarity is positive (IPPOS) or negative (IPNEG)

  • MUST be followed by int* to get the value 1 (POS) 0 (NEG)

• MIF_IGN_LAYERS returns a comma-separated list of layers (in the db) that do not participate in rasterization

  • MUST be followed by const char** to get the layer string

xxxxxxxxxx
enum MetaInfo {
   MIF_IP_POS=1
  ,MIF_IGN_LAYERS
};

Version control (QisMGbrPSFile)

• 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<number>. E.g <baseclass>V<version>
• 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* QisMGbrPSFile_name() const = 0;
virtual void* QisMGbrPSFile_cast(const int version) = 0;
virtual const void* QisMGbrPSFile_cast(const int version) const = 0;
virtual int QisMGbrPSFile_latest_version() const = 0;

File_db

• Get handle to the underlying QisMFile db so that it can be used with other APIs in the QisM system.
• DO NOT destroy this handle using QisMLib::Unload_file. Use QisMGbrPS::Unload_gbr instead

xxxxxxxxxx
virtual NsQisMLib::QisMFile* File_db() = 0;
virtual const NsQisMLib::QisMFile* File_db() const = 0;

Get_error_msg (QisMGbrPSFile)

Get_error_tag (QisMGbrPSFile)

• Get error message and tag (error code as a string) for a recent error

xxxxxxxxxx
virtual const char* Get_error_msg(const int code) const = 0;
virtual const char* Get_error_tag(const int code) const = 0;

Save_to_gdsii

• Export the database to a GDSII file on disk at the specified path gds_output_path (dir + filename + extension)
• Returns 0 on success. Otherwise call Get_error_msg/Get_error_tag for more information

xxxxxxxxxx
virtual int Save_to_gdsii(const char* gds_output_path) const = 0;

Get_meta_info

• Get select information about the source Gerber file
• info_type is the code associated with the information requested

xxxxxxxxxx
virtual bool Get_meta_info(const int info_type, ...) const = 0;

QisMGbrPS

• QisMLib extension to create a db from Gbr data

xxxxxxxxxx
class QisMGbrPS: public NsQisMLib::QisMExtensionAPI { ... };

Version control (QisMGbrPS)

• 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<number>. E.g <baseclass>V<version>
• 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* QisMGbrPS_name() const = 0;
virtual void* QisMGbrPS_cast(const int version) = 0;
virtual const void* QisMGbrPS_cast(const int version) const = 0;
virtual int QisMGbrPS_latest_version() const = 0;

Get_error_msg (QisMGbrPS)

Get_error_tag (QisMGbrPS)

• Get error message and tag (error code as a string) for a recent error

xxxxxxxxxx
virtual const char* Get_error_msg(const int code) const = 0;
virtual const char* Get_error_tag(const int code) const = 0;

New_object

Delete_object

• Create/Destroy an instance of an object

• class_name is name of the class whose object is to be created. Acceptable types are:

  • QisMGbrPSOpts

• Returns handle to the newly created object. MUST be type-casted to the specified class before use

• Every object created this way MUST be eventually destroyed using Delete_object to avoid memory/resource leak

xxxxxxxxxx
virtual void* New_object(const char* class_name) = 0;
virtual void Delete_object(const char* class_name, void* handle) = 0;

Load_gbr

Unload_gbr

• Create a database from a gbr file
• filedb will contain a handle to the newly created db on success
• lib_handle is the handle to QisMLib obtained via QisMLib_initialize_once
• gbr_path is the path to a valid gbr (RS274X) file
• working_dir if specified is path to a valid readable/writeable directory
• options if specified is handle to an object carrying various import options
• progress_updates if specified is a handler to receive progress updates
• argc, argt, argv are reserved for internal/future use
• Returns 0 on success. Otherwise call Get_error_msg, Get_error_tag for error information
• Every QisMFile database created using Load_gbr MUST be eventually destroyed using Unload_gbr only
• Requires ONE license of QISMCODE_GBRPS per call. The license is released once the database is created (The database itself does not require a license)
• Multiple databases can co-exist and are only limited by system resources

xxxxxxxxxx
virtual int Load_gbr(
  QisMGbrPSFile*& filedb, 
  NsQisMLib::QisMLib* lib_handle, const char* gbr_path, 
  const char* working_dir = 0, 
  const QisMGbrPSOpts* options = 0, QisMGbrPSNotify* progress_updates = 0,
  const int argc = 0, const char* const* argt = 0, void* const* argv = 0
  ) = 0;
virtual void Unload_gbr(QisMGbrPSFile* handle) = 0;

QisMGbrPS Licensing (API)

• Code : 11501
• Acquire : QisMGbrPS::Load_gbr
• Release : QisMGbrPS::Unload_gbr
• Policy : One per call

Version History

qismgbrps dll v1.1 2021-12-01

• Bug fix - Loading failed if QisMLib was initialized without logging (QisMLog)

qismgbrps dll v1.0 2021-06-10

• First cut