SDK (Software Development Kit)
 

What is this SDK?

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 source code may be included with your copy. This SDK also includes some embedded sample code.

The development and distribution of third party plug-ins is no-longer restricted. However, to prevent abuse, plug-ins can be blacklisted if considered harmful.

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 Effects".

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

  Programming Language

The preferred language for making Chasys Draw IES plug-ins is C/C++. Although any language that can produce DLLs linkable from ANSI C will do, the use of C# is discouraged because of it's 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. The plug-in must be placed in the "\Plugins" directory (folder).
 

  Configuration Information

Never store configuration information in the system registry because you won't get a chance to remove it. Instead, if you must store configuration data, create a .cfg or .ini file that has exactly the same name as the plug-in (except the extension)  in the same directory as the plugin - usually "\Plugins". For example, if your plug-in is named "JPEG Filter.dll", store your configuration data in "JPEG Filter.ini". Do not make any assumptions about the name of your DLL because the user if free to change it - use GetModuleFileName() to obtain it. You can then use strcpy( strrchr(name,'.'), ".cfg") to modify the name. Remember, configuration information should only be committed to disk during a plg_Config() call. Chasys Draw IES will handle the Vista UAC requirements for this action.
 

  Data Validity

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.
 

  Linkage

All linkage to Chasys Draw IES must use the C/C++ calling convection ( __cdecl ), and strings of type " char* " where applicable. The use of standard Win32 functions and structures is encouraged.
 

  Dependencies

Avoid dependency on non-universal system 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 and right 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.
 

  Extensibility

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.
 

  Metadata (Attachments)

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.
 

  Extensibility

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.
 

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.

The first two function are pretty straight forward; the host will call them with a handle to a parent window and expect your plug-in to display a meaningful dialog box. Remember, plg_Config() is the only function in a plug-in that is allowed to store configuration information to disk. Chasys Draw IES will handle the Vista UAC requirements for this action.

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:

The plug-in should fill the plugin_name member with a string that does not exceed 64 characters (including the null that terminates it). It should also fill the plugin_version member with its own version number (major in high word and minor in low word).

Upon entry, the interface_version member contains the version number of the FastExternals^TM interface implemented by the host. Currently, this is 0x00020003 (2,03). The plug-in is required to return the version it was compiled for. Please note that currently, the host and plug-in are not expected to reject each other on the basis of this value. 

The plug-in should fill the interface_type member with a combination of one or more of the following constants to indicate which interfaces in implements:

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. Chasys Draw IES will handle the UAC requirements for this action (since it translates to modifying a file in the Program Files folder).

Never write to your configuration file outside a plg_Configure() call initiated by Chasys Draw IES. It is only during that time that your plug-in is executed with the elevated privileges required for that action. Doing so will trigger UAC in Vista, your plug-in will be denied access, and Chasys Draw IES might then deem your plug-in unfit for use and delete it.

Type-specific Plug-in Interfaces

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. Each interface has rules governing it's plug-in's construction.

  File Filter Interface - Used to open files that are not supported natively by Chasys Draw IES.

  Effects Processor Interface - Used to add external visual effects and transforms to Chasys Draw IES.

  Device Interface - Used to allow Chasys Draw IES to exchange images with external devices.

Plug-in Optimization Guide

Your plug-in is up and running, so what's next?

Chasys Draw IES is a high speed 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 FastExternals interface. This is the only interface that Chasys Draw IES accepts.

  Keep your plug-in names short and unambiguous. Chasys Draw IES implements a speculative loading mechanism that maintains a short cache of plug-in names. If the name 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.

Chasys Draw IES keeps plug-ins in memory for only a few seconds at most (with the exception of FastExternals image file filters, which may be speculatively kept in memory for up to half a minute). Keep this in mind when developing your plug-ins.