ImageLoader ItemMotionHandler Classes Table of Contents

ImageSaver

Availability:  LightWave 6.0
Component:  Layout

Image savers move still image data out of LightWave, translating from LightWave's internal image formats to one of the myriad file formats available for image storage.

Activation Function

   XCALL_( int ) MyImageSaver( long 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 LightWave would like to send to you. Pixel types are explained on the ImageLoader page. If the pixel data isn't in a form you can handle, the activation function should set the local->result field to IPSTAT_FAILED and return AFUNC_OK.

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 global monitor call. See the global monitor page for details.

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 in detail below. The protocol structure is what LightWave will use to actually send you the image data. The only flag currently defined is IMGF_REVERSE, which instructs LightWave to send scanlines in right-to-left order.

Image Protocol

The LWImageProtocol structure you send in the local sendData function tells LightWave where to find callbacks in your image saver. LightWave calls these to send the image data to the saver. This is the same protocol structure used by ImageLoader plug-ins, but here the roles are reversed. Rather than the plug-in calling these functions, LightWave calls them, and the saver provides them.

   typedef struct st_LWImageProtocol {
      int   type;
      void *priv_data;
      int  (*done)     (void *, int);
      void (*setSize)  (void *, int w, int h);
      void (*setParam) (void *, LWImageParam, int, float);
      int  (*sendLine) (void *, int, const LWPixelID);
      void (*setMap)   (void *, int, const unsigned char[3]);
   } LWImageProtocol, *LWImageProtocolID;
type
Set this to local->type.

priv_data
LightWave sends this as the first argument to each of your saver callbacks. Your private data will typically point to a structure containing information that pertains to the particular file being saved, although it can be anything.

done( priv_data, result )
LightWave calls this when it's finished sending image data. The result will be IPSTAT_OK or IPSTAT_FAILED. Return IPSTAT_OK if done is successful and result is IPSTAT_OK, otherwise return IPSTAT_FAILED.

setSize( priv_data, width, height )
LightWave calls this to tell you the pixel dimensions of the image. The width and height are the number of pixels in a scanline and the number of scanlines, respectively. This will be called before the first call to sendLine.

setParam( priv_data, paramid, intparam, floatparam )
LightWave uses this to tell you other information about the image. The parameter ID can be one of the following.

LWIMPAR_ASPECT
The pixel aspect ratio, defined as width/height. This will most often be 1.0 (the default), but D1 NTSC images, for example, use a pixel aspect of 0.9, meaning that each pixel is 0.9 times as wide as it is high. The value will be set in floatparam and intparam can be ignored.

LWIMPAR_NUMCOLS
The size of the color table in an indexed-color image (an image of type LWIMTYP_INDEX8). Values will be between 2 and 256. The value will be set in intparam and floatparam can be ignored.

sendLine( priv_data, y, scanline_pixels )
LightWave calls this to send one scanline from the image. setSize will be called before the first call to sendLine. Scanlines are numbered from the top of the image, starting at 0, and will be sent in this order. The pixels within a scanlines are in left-to-right order, unless the flags passed to the sendData function included the IMGF_REVERSE flag. The structure of the pixel data you receive will depend on the pixel type. Details about specific types are on the ImageLoader page.

Return IPSTAT_OK or IPSTAT_FAILED as appropriate. If sendLine fails, you should still be prepared to receive further sendLine calls, all of which you should fail.

setMap( priv_data, index, rgb )
LightWave calls this to set the color of an entry in the color table of an indexed-color image. LightWave will call setParam with a LWIMPAR_NUMCOLS parameter before calling setMap for the first time, so that you'll know how many color table entries there are. But setMap may be called any time after that. The index identifies the color table entry and must be between 0 and numcolors-1.