Render a view of the QisMLib database
QisMDraw QisMDraw C++ API (qismdraw.h)struct QisMDrawFlagtypedef WindowHandle_tstruct QisMColorclass QisMDrawObjectSet_display_filter_size()Get_display_filter_size()Set_cell_display_filter_size()Get_cell_display_filter_size()Set_draw_filtered_areas()Get_draw_filtered_areas()Set_cell_display_filter_outline_color()Get_cell_display_filter_outline_color()Set_cell_display_filter_fill_color()Get_cell_display_filter_fill_color()Set_cell_display_filter_color()Get_cell_display_filter_color()Set_cell_display_filter_pattern()Get_cell_display_filter_pattern()Set_outline_filter()Get_outline_filter()Set_fill()Get_fill()Set_background_color()Get_background_color()Set_reference_marker()Get_reference_marker()Set_sref_marker()Get_sref_marker()Set_text_marker()Get_text_marker()Set_geometry_marker()Get_geometry_marker()Set_marker_shape()Get_marker_shape()Set_scale_bar()Get_scale_bar()Set_cell_labels()Get_cell_labels()Set_cell_label_position()Get_cell_label_position()Set_cell_label_height()Get_cell_label_height()Set_cell_outline()Get_cell_outline()Set_cell_outline_label_sref()Get_cell_outline_label_sref()Set_cell_outline_label_aref()Get_cell_outline_label_aref()Set_layers_outline_color()Get_layers_outline_color()Set_layers_fill_color()Get_layers_fill_color()Set_layers_fill()Get_layers_fill()Set_layers_outline_type()Get_layers_outline_type()Set_window()Set_image_size()Redraw_direct()Redraw_image()Get_partial_image()Get_display_vector_data()Stop_draw()class QisMDrawVersion ControlGet_last_error_msg()Open_draw()Close_draw()QisMDraw commandsdraw.imageQisMDraw Licensing
Flags used by QisMDraw API
struct QISMLIB_LNX_DECLSPEC QisMDrawFlag{ enum ImageFormat { IFF_NONE=0 /* No image will be generated */ ,IFF_GIF=1 /* GIF Image */ ,IFF_BITMAP8=2 /* Bitmap8U on Unix, Bitmap8C on Windows */ ,IFF_XPM=3 /* XPM Format */ }; enum BackgroundColor { BCF_WHITE=0 /* White background */ ,BCF_BLACK=1 /* Black background */ }; enum MarkerShape { MSF_DIAMOND=0 /* Diamond marker */ ,MSF_X=1 /* X shaed marker */ }; enum ScaleBarPos { SBF_OFF=0 /* No scale bar present */ ,SBF_UL=1 /* Scale bar on the upper left of the screen */ ,SBF_LL=2 /* Scale bar on the lower left of the screen */ ,SBF_LR=3 /* Scale bar on the lower right of the screen */ ,SBF_UR=4 /* Scale bar on the upper right of the screen */ }; enum FilterArea { DFF_ON=0 /* All parts of the filtered areas are drawn, quads and crossing */ ,DFF_OFF=1 /* No filtered areas are drawn */ ,DFF_QUAD=2 /* Only the 4 quads of the filtered areas are drawn, crossing areas empty */ ,DFF_CROSS=3 /* Only the crossing parts of the filtered areas are drawn, quads empty */ }; enum LabelPos { LPF_INSERTION=1 /* Insert cell labels at the reference insertion */ ,LPF_CENTER=2 /* Insert cell labels at the reference center */ };};Window identifier for direct draw
xxxxxxxxxxtypedef void* WindowHandle_t; typedef unsigned long WindowHandle_t;RGB Color specification
xxxxxxxxxxstruct QISMLIB_LNX_DECLSPEC QisMColor{ unsigned short r, g, b; /* 0 - 65535 */ QisMColor(): r(0), g(0), b(0) {}};xxxxxxxxxxclass QisMDrawObject: public QisMView { ... };QisMLib drawing API
Performs various drawing operations and controls the draw settings
Inherits from QisMView
Set/Get a threshold to filter (not process) items that are smaller than a certain size in pixels in the current view
sizeInPixel : Items smaller (largest dimension) than the specified size will not be processed
The manner in which the filtered data appears to the user of the library depends on the operation being performed. e.g during Get_display_vector_data, filtered data appears as QisMVector::FILTERED vector. During Redraw_direct/Redraw_image/Get_partial_image, the filtered data may appear as a solid colored box. It also depends on the Set_draw_filtered_areas setting
This settings takes precedence over Set_cell_display_filter_size for cell references
If sizeInPixel is 0, filtering is OFF and all data will be processed
Changing the extents of the current view window will change the size of an item in pixels (for the same image size) and may qualify/disqualify it for filtering
Default display filter size is 20 pixels
Specifying a non-zero filter size can significantly speed up drawing for very large view windows
xxxxxxxxxxvirtual void Set_display_filter_size(const int sizeInPixel) = 0;virtual int Get_display_filter_size() const = 0;Set/Get a threshold to filter (not process) references that are smaller than a certain size in pixels in the current view
sizeInPixel : Items smaller (largest dimension) than the specified size will not be processed
This setting only affects cell references. If it's value is smaller than Set_display_filter_size, Set_display_filter_size is used instead
The manner in which the filtered refs appears to the user of the library depends on the operation being performed. e.g during Get_display_vector_data, filtered data appears as 'F' type vector. During Redraw_direct/Redraw_image/ Get_partial_image, the filtered data may appear as a solid colored box. It also depends on the Set_draw_filtered_areas setting
Methods such as Set_cell_display_filter_outline_color, Set_cell_display_filter_fill_color, Set_cell_display_filter_color or Set_cell_display_filter_pattern can determine how these areas are drawn in an image
If sizeInPixel is 0, filtering is OFF and all refs will be processed
Changing the extents of the current view window will change the size of a ref in pixels (for the same image size) and may qualify/disqualify it for filtering
Default display filter size is 20 pixels
Specifying a non-zero filter size can significantly speed up drawing for very large view windows
xxxxxxxxxxvirtual void Set_cell_display_filter_size(const int sizeInPixel) = 0;virtual int Get_cell_display_filter_size() const = 0;Controls how filtered areas are drawn
mode : One of the QisMDrawFlag::FilterArea flags
An area is filtered if its size in pixels is smaller than the size specified by the Set_display_filter_size or Set_cell_display_filter_size method.
This setting only impacts layer data. Cell display filters will be rendered independent of this setting
Rectangular areas are divided into the 4 quadrants/areas and 2 crossing areas along the vertical and horizontal center line of the rectangular area
Set this control to DFF_OFF if all areas smaller than the display filter are to be left empty without drawing anything
Set it to DFF_QUAD if only the 4 quadrants are to be drawn as a colored area, the 2 crossing areas are left empty
Set it to DFF_CROSS if only the 2 crossing areas are to be drawn as a colored area, the 4 quadrants are left empty
If DFF_ON entire filtered areas are drawn as colored boxes. This is the default behavior
xxxxxxxxxxvirtual void Set_draw_filtered_areas(const QisMDrawFlag::FilterArea mode) = 0;virtual QisMDrawFlag::FilterArea Get_draw_filtered_areas() const = 0;Set/Get the outline color for filtered areas
color : R,G,B values for the outline color
xxxxxxxxxxvirtual void Set_cell_display_filter_outline_color(const QisMColor& color) = 0;virtual const QisMColor& Get_cell_display_filter_outline_color() const = 0;Set/Get the fill color for filtered areas
color : R,G,B values for the fill color
xxxxxxxxxxvirtual void Set_cell_display_filter_fill_color(const QisMColor& color) = 0;virtual const QisMColor& Get_cell_display_filter_fill_color() const = 0;Set/Get the fill & outline color for filtered areas
color : R,G,B values for the fill & outline color
xxxxxxxxxxvirtual void Set_cell_display_filter_color(const QisMColor& color) = 0;virtual const QisMColor& Get_cell_display_filter_color() const = 0;Set/Get the fill pattern for filtered areas
index : Pattern number as identified by colfill.pat
xxxxxxxxxxvirtual void Set_cell_display_filter_pattern(const int index) = 0;virtual int Get_cell_display_filter_pattern() const = 0;Control if a polygon outline is drawn or not if ALL of the following conditions are true:
fill mode is ON (Set_fill)
outline type is 1 (Set_layers_outline_type)
fill color is same as outline color (Set_layers_outline_color, Set_layers_fill_color)
fill pattern is solid color (Set_layers_fill)
onOff : if true (default), then under the above circumstances, polygon outline is deemed redundant and therefore not drawn. If false, the polygon outline is always drawn
xxxxxxxxxxvirtual void Set_outline_filter(const bool onOff) = 0;virtual bool Get_outline_filter() const = 0;Set/Get the fill/outline setting for drawing data
onOff : true - Turn ON fill. false - Only draw outlines
xxxxxxxxxxvirtual void Set_fill(const bool onOff) = 0;virtual bool Get_fill() const = 0;Set/Get background color (Black/White)
color : BCF_BLACK or BCF_WHITE
xxxxxxxxxxvirtual void Set_background_color( const QisMDrawFlag::BackgroundColor color ) = 0;virtual QisMDrawFlag::BackgroundColor Get_background_color() const = 0;Show/Hide markers for cell references (default: false)
onOff : true - show, false - hide
The marker shape can be controlled using Set_market_shape
To show reference markers, either sref marker or aref marker or both settings have to be ON
xxxxxxxxxxvirtual void Set_reference_marker(const bool onOff) = 0;virtual bool Get_reference_marker() const = 0;Show/Hide single reference markers (default: false)
onOff : true - show, false - hide
xxxxxxxxxxvirtual void Set_sref_marker(const bool onOff) = 0;virtual bool Get_sref_marker() const = 0;Show/Hide array reference markers (default: false)
onOff : true - show, false - hide
xxxxxxxxxxvirtual void Set_text_marker(const bool onOff) = 0;virtual bool Get_text_marker() const = 0;Show/Hide geometry markers for one or more layers
options : "On" to show markers for all layers, "Off" to hide all markers, layer[:datatype][,layer[:datatype]]* to show markers for select layers and/or layers:datatypes
The marker shape can be controlled using Set_market_shape
The marker is drawn at the first vertex of each polygon
Default: "Off"
xxxxxxxxxxvirtual void Set_geometry_marker(const char* options) = 0;virtual const char* Get_geometry_marker() const = 0;Set/Get the shape for reference/text/geometry markers (default: MSF_DIAMOND)
xxxxxxxxxxvirtual void Set_marker_shape(const QisMDrawFlag::MarkerShape shape) = 0;virtual QisMDrawFlag::MarkerShape Get_marker_shape() const = 0;Show/Hide scale bar at any one corner of the screen (default: SBF_OFF)
xxxxxxxxxxvirtual void Set_scale_bar(const QisMDrawFlag::ScaleBarPos pos) = 0;virtual QisMDrawFlag::ScaleBarPos Get_scale_bar() const = 0;Display cell-name labels for cell references at select nesting levels
options : "All" - All nesting levels, "Off" - No nesting level,
The position of the label relative to the reference can be controlled using Set_cell_label_position
To show labels, either sref labels or aref labels or both settings have to be ON
xxxxxxxxxxvirtual void Set_cell_labels(const char* options) = 0;virtual const char* Get_cell_labels() const = 0;Set/Get the label position for cell references when displayed at a given nesting level (default: LPF_CENTER)
xxxxxxxxxxvirtual void Set_cell_label_position(const QisMDrawFlag::LabelPos pos) = 0;virtual QisMDrawFlag::LabelPos Get_cell_label_position() const = 0;Set/Get the height of cell reference labels in pixels when displayed at a given nesting level (default: 10 pixels)
xxxxxxxxxxvirtual void Set_cell_label_height(const int heightInPx) = 0;virtual int Get_cell_label_height() const = 0;Display an outline for cell reference extents box at select nesting levels
options : "All" - All nesting levels, "Off" - No nesting level,
To show outlines, either sref outlines or aref outlines or both settings have to be ON
xxxxxxxxxxvirtual void Set_cell_outline(const char* options) = 0;virtual const char* Get_cell_outline() const = 0;Show/Hide labels and outlines for single references at the specified nesting level
onOff : true - ON, false - OFF
xxxxxxxxxxvirtual void Set_cell_outline_label_sref(const bool onOff) = 0;virtual bool Get_cell_outline_label_sref() const = 0;Show/Hide labels and outlines for array references at the specified nesting level
onOff : true - ON, false - OFF
xxxxxxxxxxvirtual void Set_cell_outline_label_aref(const bool onOff) = 0;virtual bool Get_cell_outline_label_aref() const = 0;Set the outline color for the specified layers if outline is visible
options :
If datatype is omitted, the color is applied to all datatypes of the said layer
color-number is a fixed set of basic colors:
0(Background) 1(Foreground) 2(Red) 3(Green) 4(Yellow) 5(Blue) 6(Magenta) 7(Cyan)
The specified color will be matched to the nearest color supported by the system
xxxxxxxxxxvirtual void Set_layers_outline_color(const char* options) = 0;virtual const char* Get_layers_outline_color() const = 0;Set the fill color for the specified layers
options :
If datatype is omitted, the color is applied to all datatypes of the said layer
color-number is a fixed set of basic colors:
0(Background) 1(Foreground) 2(Red) 3(Green) 4(Yellow) 5(Blue) 6(Magenta) 7(Cyan)
The specified color will be matched to the nearest color supported by the system
The specified color will override the fill pattern color specified in colfill.pat
xxxxxxxxxxvirtual void Set_layers_fill_color(const char* options) = 0;virtual const char* Get_layers_fill_color() const = 0;Set the fill pattern for the specified layers
options :
If datatype is omitted, the pattern is applied to all datatypes of the said layer
Default color for the pattern is also defined in colfill.pat. It can be overridden by Set_layers_fill_color
xxxxxxxxxxvirtual void Set_layers_fill(const char* options) = 0;virtual const char* Get_layers_fill() const = 0;Show/Hide outline for the specified layers
options :
If datatype is omitted, the outline type is applied to all datatypes of the said layer
1 - Show outline, 0 - Hide outline
The color of the outline will be determined by Set_layers_outline_color
xxxxxxxxxxvirtual void Set_layers_outline_type(const char* options) = 0;virtual const char* Get_layers_outline_type() const = 0;Set the current view window adjusted to match the aspect ratio of the drawing area (unlike Set_exact_window)
window : Extents of the window to be set (in file units)
Success : true
Failure : false. Use Get_last_error_code or Get_last_error_message to get details about this error
xxxxxxxxxxvirtual bool Set_window(const QisMWindow& window_) = 0;Set the image size in pixels for drawing with Redraw_direct and Redraw_image
xRes : No. pixels along X
yRes : No. pixels along Y
Success : true
Failure : false. Use Get_last_error_code or Get_last_error_message to get details about this error
For Redraw_direct, use this method to inform QisMLib about the size of the drawing area. For Redraw_image, use this method to specify the resolution of the image to be rendered
Default image size is 800x600
xxxxxxxxxxvirtual bool Set_image_size( const unsigned int xRes, const unsigned int yRes ) = 0;Perform a redraw directly to the client window
handle : Handle to the client window (HWND on Windows, Pixmap handle on linux)
refreshCb : Callback handle to recieve a refresh every refreshIntervalSec milli seconds while the redraw is in progress
refreshInterval : Refresh interval in milli seconds
zoomHome : true - set and redraw home view, false - redraw current view
clearDraw : true - Clear the drawin area before redraw
Success : true
Failure : false. Use Get_last_error_code or Get_last_error_msg to get more information
The drawing happens in an independent thread while the invoking thread waits
In order to be able to process user events while the drawing is in progress, the client must implement the QisMNotifyRefresh::On_qismt_refresh callback and pass the address of the object and a non-zero refresh interval
It is the client's responsibility to ensure thread safety of any operation executed in the refresh callback
To stop the draw, either call Stop_draw or return false from the refresh callback
On linux, the client application MUST enable X11 multi-threading by calling XInitThreads() declared in X11/Intrinsic.h
xxxxxxxxxxvirtual bool Redraw_direct( WindowHandle_t handle, QisMNotifyRefresh* refreshCb, const int refreshInterval, const bool zoomHome = false, const bool clearDraw = false ) = 0;Generate an image for the current view
format : Any one of the supported image formats
imageSize : Buffer to obtain the size of the image buffer in bytes
imageBuffer : Buffer to obtain the address of the image buffer
refreshCb : Callback handle to recieve a refresh every refreshIntervalSec milli seconds while the redraw is in progress
refreshInterval : Refresh interval in milli seconds
zoomHome : true - set and redraw home view, false - redraw current view
clearDraw : Not used
Success : true
Failure : false. Use Get_last_error_code or Get_last_error_msg to get more information
The drawing happens in an independent thread while the invoking thread waits
In order to be able to process user events while the drawing is in progress, the client must implement the QisMNotifyRefresh::On_qismt_refresh callback and pass the address of the object and a non-zero refresh interval
To get partial updates to the drawing, call Get_partial_image inside the refresh callback
It is the client's responsibility to ensure thread safety of any operation executed in the refresh callback
To stop the draw, either call Stop_draw or return false from the refresh callback
On linux, the client application MUST enable X11 multi-threading by calling XInitThreads() declared in X11/Intrinsic.h
The image buffer is read-only and managed inside QisMLib. The client program should not attempt to delete/modify the buffer or it's contents
xxxxxxxxxxvirtual bool Redraw_image( const QisMDrawFlag::ImageFormat format, int& imageSize, const char*& imageBuffer, QisMNotifyRefresh* refreshCb, const int refreshInterval, const bool zoomHome = false, const bool clearDraw = false ) = 0;Get partial image while Redraw_image is in progress
imageSize : Buffer to obtain the size of the image buffer in bytes
imageBuffer : Buffer to obtain the address of the image buffer
Success : true
Failure : false. Use Get_last_error_code or Get_last_error_msg to get more information
Use this method inside the refresh callback to get a snapshot of the partially drawn image
The image buffer is read-only and managed inside QisMLib. The client program should not attempt to delete/modify the buffer or it's contents
Get_partial_image may occasionally fail to obtain the image because of thread synchronization. Therefore, failure of Get_partial_image should be treated more like a warning than an error. Since the only situation where this method is used in inside the refresh callback, it's best to ignore the call that failed and attemp to get partial image in the next refresh callback
xxxxxxxxxxvirtual bool Get_partial_image(int& imageSize, const char*& imageBuffer) = 0;Get display information in form of vector data
target : Address of a callback handler to get notifications for vector data
clientHandle : Client specific opaque handle to be passed as a parameter to the vector data callbacks
createThread : If true, perform database traversal in a separate thread
This operation is same as QisMExploder::Get_vector_data except that it emits a new type of vector QisMVector::FILTERED (of type QisMBoundary) that represents areas filtered by the display filters
xxxxxxxxxxvirtual bool Get_display_vector_data( QisMNotify* target, void* clientHandle = 0, const bool createThread = false ) = 0;Stop Redraw_direct, Redraw_image and Get_display_vector_data operations
This must be called either inside the refresh callback On_qismt_refresh, vector data callback On_qismt_vector or in a separate thread
An alternate way to stop the drawing is to return false from the refresh callback On_qismt_refresh or non-zero value from On_qismt_vector callback
xxxxxxxxxxvirtual void Stop_draw() = 0;xxxxxxxxxxclass QisMDraw: public QisMExtensionAPI { ... };QisMLib draw extension manager
Available via call to QisMLib::Get_extension_api() with QISMEXTENSION_QISMDRAW as the api name
Requires ONE license of QISMCODE_QISMDRAW per instance of the drawing object
Currently supports only ONE drawing object per QisMFile
On LINUX, requires QisMLib to be intialized (QisMLib_initialize_once) with the application display handle (Display*) passed as QISM_ARG_DISPLAY to the optional argument
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
The topmost base class is version 1 (V1 implied).
The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual void* QisMDraw_cast(const int version) = 0;virtual const void* QisMDraw_cast(const int version) const = 0;virtual int QisMDraw_latest_version() const = 0;Get more information about the last error condition
xxxxxxxxxxvirtual const char* Get_last_error_msg() const = 0;Create an instance of the QisMLib drawing object
filedb : Handle to the currently loaded QisMFile database
argC : Number of optional arguments
argT : Optional argument type (per argument)
argV : Optional argument value (per argument)
Success : A non-null handle to an instance of the QisMDrawObject api
Failure: NULL. Use Get_last_error_msg() or Get_last_error_code() to get information about the error
Create an instance of the drawing object in order to perform various drawing operations
At the moment, only ONE such instance can exist at a time per QisMFile.
Every object created this way MUST be destroyed using Close_draw() to avoid memory/license leak
A single license of QISMCODE_QISMDRAW is required per instance of this api
This validity of this object is only as long as filedb is alive. This object must be destroyed as soon as the filedb is closed/destroyed and a new object should be created when a new file is loaded
xxxxxxxxxxvirtual QisMDrawObject* Open_draw( QisMFile* filedb, const int argC = 0, const char* const* argT = 0, void* const* argV = 0 ) = 0;Get more information about the last error condition
handle : Handle to an instance of QisMDrawObject
Every object created this way MUST be destroyed using Close_draw() to avoid memory/license leak
A QisMDrawObject is only valid as long as filedb is alive. This object must be destroyed as soon as the filedb is closed/destroyed and a new object should be created when a new file is loaded
xxxxxxxxxxvirtual void Close_draw(QisMDrawObject* handle) = 0;See qismdraw.h for the corresponding C++ API
xxxxxxxxxxdraw.image $filedb={filedb_id} [path={img_path_base}] [cell={cellname}] [layers={layer_list}] [window={minx},{miny},{maxx},{maxy}] [nesting={level}] [format={GIF | DIB | XPM}] [background={BLACK | WHITE}] [filtersize={dfs}] [fill={ON | OFF}] [text={ON | OFF}] [res={x},{y}] [refboxes={ON | OFF | NL}] [color={OUTLINE | FILL},{str}]Render a view of the database to an colored image file on disk
Makes use of the QisMDraw API defined in qismdraw.h
Requires ONE license of (11057) per call
{filedb_id} is name of the variable associated with the file database
{img_base_path} if specified generates an output file at the specified path (extension automatically added). Otherwise, the image is generated but not written to disk
{cellname} if specified set the view cell. Default view cell is the deepest top cell
{layer_list} if specified, is a comma-separated list of layer and/or layer:datatype numbers to be visible. Default: ALL loaded layers
{minx}..{maxy} if specified represents the window to be set (adjusted to match the image aspect ratio). Default: Extents of the view cell is used
{level} if specified sets a max. nesting level for drawing. Default: ALL levels
format if specified sets the output file format. Default: GIF. XPM is only available on Linux.
background if specified sets the background color. Default: BLACK
{dfs} if specified sets the display filter size (for both geometries and references). Default: 0
fill controls the fill mode. Default : OFF
text controls if TEXT elements are drawn. Default: ON
{x},{y} if used is the image resolution in pixels along X and Y. Default: 800, 600 pixels
refboxes if specified controls if the references are drawn with outlines and labels. If ON, references at all nesting levels are drawn with outline and labels. If OFF, outlines and labels are not drawn. If NL, outlines and labels are only drawn for references at the specified nesting level (> 0)
color=... specifies the colors for various layers for outline and/or fill. See QisMDrawObject::Set_layers_outline_color or QisMDrawObject::Set_layers_fill_color for details
| COUNT | CODE | OPERATION | NOTES |
|---|---|---|---|
| +1 | 11057 | C++ QisMDraw::Open_draw() | ONCE per call |
| -1 | 11057 | C++ QisMDraw::Close_draw() | ONCE per call |
| +/-1 | 11057 | Script draw.image | ONCE per call |
Last Updated -- Wed Nov 19 18:22:04 UTC 2025