SDK - File Format Plug-ins
 

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

• All file format plug-ins must be thread-safe (re-entrant); a plug-in function may be called from several threads simultaneously, especially when running with GUIs blocked. It is also possible for a plug-in to indirectly call itself via the host. Thus, the use of global variables is highly discouraged, as is the use of __declspec(thread), which doesn’t work with dynamically loaded DLLs.
• The host may (and usually does) choose to cache (or 'hog') file format plug-ins by keeping them loaded in memory between calls. Your plug-in should therefore not make any assumptions about its life-span.

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

• flt_LoadImage - Used to load images from files
• flt_SaveImage - Used to save images to files
• flt_CheckLoad - Used in conjunction with  flt_LoadImage
• flt_CheckSave - Used in conjunction with  flt_SaveImage
• flt_TransformImage - For file formats that support generic lossless transformations (e.g. JPEG rotation)

Plug-ins are not required to implement the entire interface - you may implement flt_LoadImage alone, or implement flt_SaveImage and flt_CheckSave or all of them as you deem fit.
 

Chasys Draw IES looks for a function named flt_CheckLoad() in each plug-in it tries. This is the function that Chasys Draw IES calls to check if the plug-in can load files in the specified file format. If it doesn’t find this function, the plug-in is moved to the bottom of the priority list and will be tried last. If it is found, Chasys Draw IES calls it with a flt_CHECK_L:

Chasys Draw IES may provide the file extension (e.g. “.jpg”), and/or up to the first 32 bytes of data from the file in extension and hdr_data respectively. If provided, the extension always begins with a dot. The plug-in should use this information to check if it supports that file. If it finds that it supports the file, it should set up the appropriate support data as outlined under support levels then return 1. If not, it should return 0.

The main purpose of flt_CheckLoad() is to enable prioritization. It is generally expected that dedicated plug-ins will have more features than multi-format ones, and that the author of a plug-in that doesn’t support the full specification/semantics for a file format would be aware of this fact.

If Chasys Draw IES chooses to use this plug-in, it looks for and calls flt_LoadImage() with a pointer to a flt_IMAGE_L structure. Embedded in the structure is the file name, which is stored as a unicode string (wchar_t*). The first order of business for the plug-in should be checking if the referenced file is in a format it recognizes (e.g. by checking the magic number/pattern in the file). If the file is not supported, the plug-in should immediately fail and return PLUGIN_ERR_NO_SUPPORT to the host. This should be done in the most timely manner possible, and the host may elect to rank plug-ins by how quickly they hand back control after encountering an unknown format.

flt_LoadImage() is expected to set the width, height and where applicable, x_pos, y_pos, options, transparency and name members, then call the create() member function to request Chasys Draw IES to allocate the bitmap for each layer in the image. This process is repeated until all layers have been loaded.

create() takes the flt_IMAGE_L object as a parameter and returns non-zero to indicate success. It also sets the width, height, pitch (in number of pixels, not bytes) and lp_pix. If the requested size is too large for the host to allocate and host_flags contains PLUGIN_HOSTFLAG_RESIZE, it attempts to allocate a smaller bitmap of the same aspect ratio, sets width and height to the new values, then leaves PLUGIN_HOSTFLAG_RESIZE set (normally, it is cleared). In this case, the host requires that the plug-in resizes the image locally. Your plug-in should either resize the loaded image internally without assistance from the host, or indicate failure by returning the error code PLUGIN_ERR_BITMAP_BIG. On failure, create() returns zero and sets host_response to the appropriate PLUGIN_ERR_* code.

The plug-in proceeds to fill lp_pix as 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. If the image has additional layers, the plug-in sets width, height, etc, then calls create() again; this is repeated until all the layers have been loaded.

The plug-in returns (from flt_LoadImage) the number of layers loaded (greater than 0) to indicate success. If the image had more layers but the plug-in was unable to load them or some of their features due to internal or host constraints, the plug-in should add the relevant PLUGIN_WARN_* flag to warnings to inform the host that the loaded image may be incomplete. Failure is indicated by returning the relevant PLUGIN_ERR_* code (these codes are defined in plugin.h). Error details may be provided via set_infostr() if it is not zero by setting type to PLUGIN_INFOTYPE_ERROR and providing the error string.

Progress data may be shared with the host via set_progress() if it is not zero. It is up to the host to decide what to do with the progress information. A zero return from set_progress() indicates that the user wishes to cancel the operation. The plug-in should respond to this be immediately ceasing all operations and returning PLUGIN_ERR_USER_CANCEL. The host is expected to adapt to the progress update frequency of the plug-in and to minimize the time penalty associated with progress reporting.

The color-space is always sRGB. You are not required to perform any color matching except converting colors to sRGB if the file format uses another color-space. You can use pi_BasicColor to perform this and many other conversions.

The hwnd member being set to a valid handle (non-zero) is an indication to the plug-in that it is free to display a dialog box. DO NOT display a user interface of any sort if this member is zero.

If the plug-in generates metadata (a.k.a. layer attachments), it should pass the metadata entry by entry after calling create() by calling the meta_write() function with the size and type of data and optionally setting meta_data to the memory location of the data, e.g. calling meta_write(data,"MARK",256) will create an attachment of type MARK and write 256 bytes of data into it from meta_data. If meta_data is set to zero before calling meta_write() and a non-zero size is provided, Chasys Draw IES will create null metadata of the specified size and type and return the pointer in meta_data.

It is no longer necessary to set meta_data to zero before calling create(). To pass or request a metadata archive in a plug that knows how to handle archives, use the standard metadata functions with the archive four character code. The ability to provide or accept raw archives is an optional host feature that may not be available in all scenarios..

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.

These are the flags for the img_type and img_subtype members (this list is not exhaustive; see plugin.h for complete list):

The options member a combination of zero or more of the LAYER_OPTION_* flags below and exactly one of the LAYER_BLEND_* flags (this list is not exhaustive; see layerdefs.h for complete list):

The following may be used in combination for the host_flags member (this list is not exhaustive. See layerdefs.h for complete list):

The following may be used in combination for the warnings member (this list is not exhaustive; see layerdefs.h for complete list):

Data corruption should generally be treated as a permanent error that causes the loading process to fail with the appropriate PLUGIN_ERR_ error code. The PLUGIN_WARN_IMAGE_DATA option should only be used by experimental plug-ins that support file formats for which better support is known not to exist and for which some data corruption may be acceptable.

If the timeout member is non-zero, the plug-in has that many milliseconds to finish the operation. Chasys Draw IES may enforce this timeout by, for example, refusing to honour create() requests after the timeout period. In this case, Chasys Draw IES will add PLUGIN_WARN_TIMEOUT to warnings.

Chasys Draw IES may advise the plug-in that a thumbnail is okay if the full image will take long to retrieve by setting PLUGIN_HOSTFLAG_WANT_THUMB. If the plug-in elects to only provide a thumbnail, PLUGIN_WARN_THUMB_ONLY must be added to warnings.

The maximum allowed number of layers is application-dependent. If create() fails, your plug-in should abort decoding. Do not attempt to perform any memory management functions (like de-allocation or page-locking) on lp_pix.

So as to keep rogue plug-ins at bay, Chasys Draw IES will send test data to flt_CheckLoad() from time to time, just to see whether or not it is implemented properly. Plug-ins that fail the test will be blacklisted by the application.

Chasys Draw IES looks for a function named flt_CheckSave() in each plug-in it tries. This is the function that Chasys Draw IES calls to check if the plug-in can save files in the specified file format. If this function is not found, plug-in will be rejected and Chasys Draw IES will not use it. If it is found, Chasys Draw IES calls it with a flt_CHECK_S:

Chasys Draw IES will provide the file extension (e.g. “.jpg”). The extension provided always begins with a dot. The plug-in should use this information to check if it supports that file. If it finds that it supports the file, it should set up the appropriate support data as outlined under support levels then return 1. If not, it should return 0.

The main purpose of flt_CheckSave() is to enable prioritization. It is generally expected that dedicated plug-ins will have more features than multi-format ones, and that the author of a plug-in that doesn’t support the full specification/semantics for a file format would be aware of this fact.

If Chasys Draw IES chooses to use this plug-in, it looks for and calls flt_SaveImage() with a pointer to a flt_IMAGE_S structure, which contains all the information needed to save the image: width, height, pitch (in number of pixels, not bytes) and lp_pix are set to describe the bitmap, file to the save path, and hwnd to the parent window if GUIs are allowed. Initially, layer_count will be set to the number of layers in the image. If your plug-in does not support layers, or layer_count is greater than what your plug-in can handle, you should abort immediately by returning PLUGIN_ERR_NOT_FLAT. The host will then flatten the image for you and call flt_SaveImage() again with the flattened image and a layer_count of 1.

The hwnd member being set to a valid handle (non-zero) is an indication to the plug-in that it is free to display a dialog box. DO NOT display a user interface of any sort if this member is zero.

As usual, 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. It should not be altered by the plug-in in any way. The plug-in, if capable of storing alpha data, should check all pixels to determine whether or not the alpha values are used (i.e. some are non-zero). If the plug-in is capable of handling layered images, it should check the transparency value as well.

If the image has metadata, the meta_data parameter will be a non-zero metadata archive handle. The host owns this memory handle; the plug-in should not free or change it. If the plug-in doesn’t know how to process a metadata archive, it can call the meta_read() function to load specific metadata elements into meta_data, e.g. calling meta_read(data,"MARK") will load the markup attachment if available. The function returns the size of the metadata or zero if the type is not found. Setting type to zero will load the entire metadata archive.

After the plug-in saves the current layer, it calls select() with the zero-based identifier of the next layer to retrieve it; the data for which is placed in the width, height, pitch and lp_pix members. This is repeated until all the layers have been saved. Please note that the select() member may be null if there’s only one layer. Some hosts allow specifying “-1” to return the merged image with limited functionality and without any metadata. If you use this extension, be sure to call select() again with a valid layer identifier before calling any other function.

The img_type and options members have the same meanings are described above.

The plug-in should return the number of layers saved (greater than 0) if it succeeds. If the image has more layers than what the plug-in was able to save, or some of their features were dropped due to internal or host constraints, the plug-in should add the relevant PLUGIN_WARN_* flag to warnings to inform the host that the saved image may be incomplete. Failure is indicated by returning the relevant PLUGIN_ERR_* code (these codes are defined in plugin.h). Error details may be provided via set_infostr() if it is not zero by setting type to PLUGIN_INFOTYPE_ERROR and providing the error string.

Progress data may be shared with the host via set_progress() if it is not zero. It is up to the host to decide what to do with the progress information. A zero return from set_progress() indicates that the user wishes to cancel the operation. The plug-in should respond to this be immediately ceasing all operations and returning PLUGIN_ERR_USER_CANCEL. The host is expected to adapt to the progress update frequency of the plug-in and to minimize the time penalty associated with progress reporting.

Previous versions of this SDK recommended that flt_SaveImage() should check the file extension by calling flt_CheckSave() internally and fail with PLUGIN_ERR_NO_SUPPORT if the file extension is not supported. This is no longer recommended; Chasys Draw IES will make a choice using the results of flt_CheckSave() and the plug-in should proceed with saving if Chasys Draw IES instructs it to do so.

So as to keep rogue plug-ins at bay, Chasys Draw IES will send test data to flt_CheckSave() from time to time, just to see whether or not it is implemented properly. Plug-ins that fail the test will be blacklisted by the application.

Some lossy file formats, such as JPEG, support some generic transformations which are carried out losslessly without recompressing the image. This functionality may be exposed through the flt_TransformImage() call. It takes a pointer to a structure of type flt_IMAGE_X. Embedded in this structure is the unicode filename and transformation identifiers:

The file member contains the file to be transformed. One of the following constants must be specified for the xform_id parameter:

The xform_id2 parameter is currently not used.

The function should return a value greater than zero if the transformation was done. Failure is indicated by returning the relevant PLUGIN_ERR_* code (these codes are defined in plugin.h). Error details may be provided via set_infostr() if it is not zero by setting type to PLUGIN_INFOTYPE_ERROR and providing the error string.

Plug-ins that only support lossless file formats must never implement this function, so as to allow the host to use its own methods.

Never emulate this function, i.e. by loading the file, transforming the image then saving. This is considered rogue behaviour and will cause your plug-in to be blacklisted and tagged as “software that destroys images”.

Chasys Draw IES currently uses a file type whitelist to decide whether or not to call this function. As such, you should report to the author when you make a plug-in implementing it so that you file format may be added to the white-list. Currently, only JPEG and JPEG-2000 files are allowed through.

Support Levels indicate how well a plug-in supports a specific file format, with 0 indicating no support (or "not sure") and 255 indicating full support including all semantics. The support level is calculated as shown below; the exact values used are at the discretion of the plug-in author. Plug-ins that do not directly load the image (and can therefore not guarantee a specific level of support) should always specify the SUPPORT_FLAG_IS_BRIDGE flag to allow plug-ins that are specifically designed for those file formats to take precedence.

The level_image member should be set to a value between 0 and 255 depending on the completeness of image data decoding implemented by the plug-in. If this value is zero, Chasys Draw IES will assume that the plug-in cannot guarantee any level of support and will use it only after everything else has failed.

The level_layer member should be set to a value between 0 and 255 depending on the completeness of multi-layer/multi-frame decoding implemented by the plug-in. If the plug-in can only decode the first frame/layer, it should set this memeber to zero.

The level_other member should be set to a value between 0 and 255 depending on the completeness of metadata decoding implemented by the plug-in. Metadata may include thing such as EXIF data, vector data, etc.

The support_flags member should be set to the logical OR of the appropriate flags.

Here’s the full listing of the main file for the PNG plug-in included with Chasys Draw IES for your reference:

You can also view other source code files here.