SDK - Effects Plug-ins
 

The following rules apply to all plug-ins implementing this interface:

• Effects plug-ins need not be re-entrant. This interface is always called from a single thread as it requires a GUI
• The interface currently only allows the plug-in to access one layer per call; this layer is chosen by the user during plug-in invocation
• The plug-in should allow the user to set any necessary parameters via an appropriate dialog box. The changes should, where possible, be reflected in a live preview provided either by the plug-in within this dialog box or in the actual image via the refresh() callback. Any caching necessary for this is to be done by the plug-in using the provided memory allocation interface
• All access to the image buffer for this interface must be enclosed in calls to lock() and unlock(), unlike the other interfaces which allow the buffer to be accessed at any time
• Unlike the other interfaces, this one provides host-based memory allocation functions. The use of these is highly encouraged

The file format plug-in interface is made up of one function in addition to the general interface:

• efx_DoEffect - The one and only interface function

Chasys Draw IES looks for a function named efx_DoEffect() in the plug-in chosen by the user from a list. If it finds this function, Chasys Draw IES calls it with a pointer to a efx_IMAGE_T structure, which contains the data and callbacks needed to perform the operation(s) implemented by the effects plug-in.

Initially, only the callback functions and hwnd are set. hwnd points to the parent window to be used for any dialog boxes created by the lug-in. If you want your plug-in’s dialog box to be docked to the side (like the built-in effects), call dock() with the handle to your dialog box.

The plug-in would normally start by calling the load() member to instruct the host load the original image. The host sets width and height to describe the original bitmap.

When the plug-in needs to access the raw data for the image, it calls the lock() callback. The host then set pitch (in number of pixels, not bytes) and lp_pix to allow access to the original bitmap. lp_pix is an array of 32 bit integers, each representing a pixel in BGRA format (blue LSB, alpha MSB), with alpha values of zero(0x00) for opaque and 255 (0xff) for transparent. The color-space is always sRGB.

The plug-in does whatever manipulations it sees fit to apply the effect it wants. It then calls unlock() to release the buffer. If the image needs to be resized to apply the effect, the plug-in caches the original (again, if need be), sets width and height to the desired values then calls realloc(). If the requested size is too large for the host to allocate, it allocates a smaller bitmap of the same aspect ratio, sets width and height to the new values, then returns a negative value. In this case, the plug-in should make do with what is provided.

The plug-in is required to periodically call progress() when performing long tasks to update the progress bar and prevent Chasys Draw IES from appearing to hang. You need not check how long the operation will be, Chasys Draw IES ignores the first hundred or so milliseconds of updates to prevent slowing down quick jobs. Note that progress() returns 0 if the Escape key is pressed to indicate that the user wants to interrupt the process.

If the plug-in needs live preview, it calls refresh() to force the host to redraw its display with the new image. The plug-in may then wait for user-interface activity and repeat the process. An alternative strategy is to use a shrunk version of the original to perform preview in your dialog without ever modifying the original. Once the user is satisfied and clicks OK,  the algorithm is applied to the original (large) image. Please note that it is okay to call refresh() together with progress() to create a "scanning" update effect.

You are encouraged to use the mem_alloc(), mem_resize() and mem_free() member functions to do your memory management. Doing so allows your plug-in to take advantage of any special memory management scheme in use by the host.

Layer attachments may be accessed via the meta_query() function and meta_data parameter. Calling meta_query() with size set to zero is a "get" call. If the type exists, its size is returned and meta_data points to the data segment. If it doesn’t exist, the call fails and returns zero. Calling it with size set to a non-zero value is a "create" call. If the type exists, it is resized to size with data preservation. The new size is returned and meta_data points to the data segment. If it does not exist, a new resource size bytes long is created and returned.

If the operation succeeds, efx_DoEffect() should return PLUGIN_OKAY. Failure is indicated by returning the relevant PLUGIN_ERR_* code. The plug-in is at liberty to display its own error messages so as to provide detailed error information.

The flags parameter should be set to zero upon entry into the plug-in to allow your plug-in to work with future versions of this interface.

Please note that the metadata function pointers can be zero if the interface is not implemented or is disabled by the user. Also note that errors result in zero returns. The plug-in is expected to degrade gracefully in these circumstances.

The full listing of the main file for the Non-saturating Contrast Effect plug-in included with Chasys Draw IES for your reference:

You can also view other source code files here.