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