SDK – Device Plug-ins

Interface Rules

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

• Device 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 image buffer for this interface is prelocked, and can be accessed at any time

Interface Description

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

• dev_ReadImage - Used to read images from external devices
• dev_SendImage - Used to send images to external devices

Plug-ins are not required to implement the entire interface - you may implement dev_ReadImage, or dev_SendImage or both of them as you see fit.

Image Import via dev_ReadImage()

Chasys Photo looks for a function named dev_ReadImage() in the plug-in the user selects. If it finds this function, Chasys Photo calls it with a pointer to a dev_IMAGE_Rstructure.

dev_ReadImage() is expected to set the width and height members, then call the create() member function to request Chasys Photo to allocate the bitmap for each layer in the image.

create() 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 the argument flags contains PLUGIN_CREATE_RESIZE, it attempts to allocate a smaller bitmap of the same aspect ratio, sets width and height to the new values, then returns non-zero to indicate success. You can use pi_BasicImage::downsample_* to resize your image on the fly scanline-by-scanline. On failure, create() returns zero and sets host_response to the appropriate PLUGIN_ERR_* code. If the failure was as a result of requesting a bitmap size the is too big, host_response will be PLUGIN_ERR_BITMAP_BIG.

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 dev_ReadImage) 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 due to internal or host constraints, it should add the relevant PLUGIN_WARN_* flag to warnings to inform the host that the 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. Device plugins that must show dialogs should interpret this as an error and return 0.

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 Photo 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.

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):