An SDK is a collection of information that tells you how to
go about building software that works together with another piece of
software. Any piece of software has its own structures and symbols, designed
or chosen by the programmer at his own discretion, with which you must be
familiar to successfully link with it. For example, to build a program that
runs under the Windows operating system, you need the Win32 SDK.
This particular SDK is targeted at developers who intend to
build plug-ins for Chasys Draw IES. Some sample source-code may be included with your copy. This SDK also includes some embedded sample code, and the common plug-in header file. It is strongly adviced that you always compile your code against the latest version of the header.
development and distribution of plug-ins based on this SDK is subject to the terms and conditions laid out in the license agreement. Be advised that some copy-left open-source licenses may be incompatible with the said license agreement.
Chasys Draw IES comes bundled with a plug-in that allows you to use plug-ins intended for Adobe's
Photoshop (8BF format). It has the display name "Photoshop Plug-ins Bridge".
Any plug-in designed for Chasys Draw IES must adhere strictly to the specifications set forth below,
otherwise Chasys Draw IES's internal security sub-system will reject the rogue plug-in and may delete it as a preemptive security measure.
Should this ever happen to your plug-in, I suggest that you return to the drawing table forthwith, as a truly monumental error has been made.
General Rules for Plug-ins
The preferred language for building Chasys Draw IES plug-ins is C/C++, although any language that can produce DLLs linkable
from standard C will do. The use of C# is discouraged because of its dependency on the so-called Microsoft Common Languages Runtime
(mscoree.dll), which is not a particularly common DLL. Visual BASIC is simply too basic to cut it (and also has dependencies).
Filename & Location
The plug-in file name must have a ".dll " extension, and its name (including the extension) must not exceed 30 characters.
The plug-in must be placed in the "\Plugins" directory (folder) or a sub-directory thereof. If the plug-in is in a subdirectory, it must no be more than four levels deep because Chasys Draw IES will not search deeper than that. The name of the plug-in's .dll file must be unique, even if the plugin is in its own separate folder. It is highly recommended that you follow the naming convention used by the default plug-ins.
Never store configuration information in the system registry or in files because you won't get a chance to clean up that info, and you
may lack the permissions to do so. If you need to store configuration infomation, do so using the permanent state-stores provided by
Never assume the validity of data across function calls. Most of the data Chasys Draw IES exchanges with plug-ins is created immediately
before the call and destroyed immediately afterwards.
All linkage to Chasys Draw IES must use the C/C++ calling convection ( __cdecl ), and strings of type "wchar_t* "
where applicable. The use of standard Win32 functions and structures is encouraged (as opposed to using extensions such as dot-NET).
Avoid dependency on non-universal system DLLs or third-party DLLs. First, doing so will negate the principle of universal compatibility
that Chasys Draw IES has always stuck to. Secondly, Chasys Draw IES will not let you install them, and will certainly not give you a chance
to even think of removing them. If you are wondering why this is so, it is because most people (myself included) hate it when software
decides to start installing stuff left, right and center without asking for permission first. In other words, it's not your computer - it's
the user's, and he/she doesn't want you filling it with bloat-ware.
Most of the structures defined in this SDK float in a 1024-byte pool, and thus have a range of reserved bytes. Do not access
these, they are meant for future expansion of the API. This ensures that older plug-ins can work in newer hosts and vice-versa, since an older host
will initialize them to zero.
All structures exposed by this interface use 1-byte padding. The included headers have #pragma pack(1) defined for this reason.
Plug-ins can access (and in some cases create) layer attachments. These may be used for plug-in-specific purposes. See the Layer Attachments section for more information.
General Plug-in Interface
Chasys Draw IES expects all plug-ins to have the following
functions, irrespective of type. The sample code for the PNG plug-in shows how to use these functions.
Please refer to it later on.
// called to query plugin's name and type
unsigned long plg_GetInfo(plg_INFO* info);
// called to display plugin dialogs
unsigned long plg_ShowDialog(plg_DIALOG* data);
plg_GetInfo() is called by the host to collect information about the plug-in. It takes a
pointer to a struct of type plg_INFO:
unsignedlong api_flags;//do not touch
unsignedlong api_extra;//do not touch
unsignedlong plugin_flags; //do not touch
unsignedlong plugin_extra; //do not touch
unsignedchar reserved_x[1024-288];//do not touch
Upon entry, the api_version member contains the version number of the FastExternalsTM interface implemented
by the host (PLUGIN_INTERFACE_VERSION, see plugin.h for definition). The plug-in is required to return the
version it was compiled for.
The plug-in should fill the api_type member with a combination of one or more of the
following constants to indicate which interfaces in implements:
0x00000001: File format Plug-in
0x00000002: Device Plug-in
0x00000004: Effect Plug-in
The api_flags andapi_extra members are reserved and should be left untouched.
The plug-in should fill the plugin_nameand plugin_author members with strings containing the name of the plug-in and the name of the vendor. These strings should not exceed 64 wide characters, including
the null characters that terminate them. The plug-in should also fill the plugin_version memberwith its own version number (major in high
word and minor in low word).The plugin_flags andplugin_extra members are reserved and should be left untouched.
plg_ShowDialog() is called by the host to display a plugin dialog box, such as the "about" or the "config" window. It takes a
pointer to a struct of type plg_DIALOG:
The dialog member indicates which dialog box to display. It can be any of the following:
0x00000000: Show the About box for the plug-in
0x00000001: Show the Config box for the plug-in
0x00000002: Show the Help box for the plug-in
The hwnd member contains the window handle that should be used as the parent for the dialog box. The param_1 and param_2 members are dialog-specific, but are currently not used. Config dialog boxes must use the
pi_StateStore member to persist the plug-ins settings; plug-ins are not allowed to directly write their settings to configuration files.
If the plug-in manages to display the dialog box, it should return PLUGIN_OKAY to indicate success. If the specified dialog is unnecessary (e.g. config box for a plug-in with no user-selectable options), it should return PLUGIN_ERR_NO_SUPPORT instead. The plug-in should return one of the other PLUGIN_ERR_* codes if an error occurs.
Chasys Draw IES requires
that all plug-ins that need configuration store the configuration data as
outlined above. The stored settings should be used whenever required. When
these are not available, and a window handle is provided, a configuration
dialog box should be shown.
your configuration information directly to file or to the registry. All configuration data must be managed via the provided StateStore object. Chasys Draw IES will generally avoid executing your plug-in with elevated priviledges and may flag it as rogue if it writes data to the "plugins" folder.
Chasys Draw IES supports various interfaces for the various
types of plug-ins. Every plug-in must implement at least one of these
interfaces; you may implement more than one if you wish.
Used to allow Chasys Draw IES to exchange images with external devices
Each interface has rules governing its plug-ins' construction.
Your plug-in is up and running, so what's next?
Chasys Draw IES is a high-speed graphics environment, and if your
plug-in can't keep up, things might get a little rough for it. Here are some
tips that will help you keep the code flying like bullets:
Always use the latest FastExternals interface.
Where possible, use the utilities and callback suites exposed by the interface.
Stick to the rules: Chasys Draw IES spends less time authenticating well-behaved plug-ins.
plug-in filenames short and unambiguous. Chasys Draw IES implements a
speculative loading mechanism that maintains a short cache of plug-in filenames.
If the filename is too long (more than about 28 characters) or is ambiguous (causing the user to install two
plug-ins that serve the same purpose) the loading mechanism will award it a
low priority when deciding what to try first.
Draw IES keeps plug-ins in memory for only a few seconds at most (with the
exception of FastExternals file format plug-ins, which may be speculatively kept in memory for up to half a minute).
Keep this in mind when developing your plug-ins.