ImageSaver

Availability  LightWave® 6.0
Component  Layout
Header  lwimageio.h

Image savers write image files. Each of them typically supports a single format.

When a saver's activation function is called, it should try to open the output file named in the local structure. If the open fails, the saver can set local->result to IPSTAT_BADFILE and return immediately. Otherwise, the saver creates and initializes an image protocol and calls sendData to tell LightWave® it's ready to receive image data. LightWave® then calls the saver's callbacks to transfer the data. sendData doesn't return until LightWave® calls the saver's done callback.

Activation Function

   XCALL_( int ) MyImageSaver( int version, GlobalFunc *global,
      LWImageSaverLocal *local, void *serverData );

The local argument to an image saver's activation function is an LWImageSaverLocal.

   typedef struct st_LWImageSaverLocal {
      void        *priv_data;
      int          result;
      LWImageType  type;
      const char  *filename;
      LWMonitor   *monitor;
      int         (*sendData) (void *, LWImageProtocolID, int flags);
   } LWImageSaverLocal;

priv_data

Pass this to the sendData function. It's an opaque pointer to data used internally by LightWave®.

result

Set this to indicate whether the image was saved successfully. The result codes are

IPSTAT_OK

The image was saved successfully.

IPSTAT_BADFILE

The saver couldn't open the file.

IPSTAT_ABORT

Use this to indicate that the user cancelled the save operation. This can happen if you use the monitor to indicate the progress of a lengthy image saving operation.

IPSTAT_FAILED

An error occurred during saving.

type

The kind of pixel data to be saved. Pixel types are listed on the Image I/O page. The most common types will be LWIMTYP_RGBAFP for color images and LWIMTYP_GREYFP for grayscale images. Use this to decide what kind of pixel data you want to receive. If your file format supports 24-bit color and 8-bit grayscale, for example, you would set your image protocol type to LWIMTYP_RGB24 when the local type field contains any of the RGB types, and LWIMTYP_GREY8 when it contained either LWIMTYP_GREYFP or LWIMTYP_GREY8.

filename

The name of the image file to write.

monitor

A monitor for displaying the progress of the save to the user. You don't have to use this, but you're encouraged to if your image saving takes an unusual amount of time. This is the same structure returned by the monitor global.

result = sendData( priv_data, protocol, flags )

Call this when you're ready to begin receiving image data from LightWave®. This will be after you've filled in the fields of an appropriate LWImageProtocol structure, which is described on the Image I/O page. The only flag currently defined is IMGF_REVERSE, which instructs LightWave® to send scanlines in bottom-to-top order. When you call sendData, LightWave® calls the functions you provided in your image protocol structure to actually save the image. sendData won't return until the image is saved.

Example

The iff sample is a complete IFF ILBM loader and saver.