ImageLoader

Availability  LightWave® 6.0
Component  Layout, Modeler
Header  lwimageio.h

Image loaders read image files. Each of them typically supports a single format.

When an image loader's activation function is called, it should open the image file and try to recognize its contents. LightWave® calls all of the installed image loaders in sequence until one of them recognizes the file. Each image loader is therefore responsible for identifying the files it can load. If the file isn't one the loader understands, the loader sets the result field of the local structure to IPSTAT_NOREC and returns AFUNC_OK.

If, on the other hand, the loader understands the image file, it calls local->begin to get the image protocol functions and then loads the file.

Activation Function

   XCALL_( int ) MyImageLoader( int version, GlobalFunc *global,
      LWImageLoaderLocal *local, void *serverData );

The local argument to an image loader's activation function is an LWImageLoaderLocal.

   typedef struct st_LWImageLoaderLocal {
      void              *priv_data;
      int                result;
      const char        *filename;
      LWMonitor         *monitor;
      LWImageProtocolID (*begin) (void *, LWImageType);
      void              (*done)  (void *, LWImageProtocolID);
   } LWImageLoaderLocal;

priv_data

Pass this as the first argument to the begin and done functions. It's an opaque pointer to data used internally by LightWave®.

result

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

IPSTAT_OK

The image was loaded successfully.

IPSTAT_NOREC

The loader didn't recognize the file. This can happen frequently, since all loaders are called in sequence until one of them doesn't return this result.

IPSTAT_BADFILE

The loader couldn't open the file. If the loader is able to open the file but believes it has found an error in the contents, it should return IPSTAT_NOREC.

IPSTAT_ABORT

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

IPSTAT_FAILED

An error occurred during loading, for example a memory allocation failed.

filename

The name of the file to load.

monitor

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

protocol = begin( priv_data, pixeltype )

Call this when you're ready to begin sending image data to LightWave®. This will be after you've opened and examined the image file and know what it contains. The pixel type code tells LightWave® what kind of pixel data you will be sending, and this will in general depend on what kind of pixel data the file contains, although it doesn't have to. Pixel type codes are listed on the Image I/O page.

The begin function returns a pointer to an LWImageProtocol, which is the structure you'll use to actually transfer the image data. See the Image I/O page. If you call begin, you must also call done so that LightWave® can free resources associated with the LWImageProtocol it allocates for you.

done( priv_data, protocol )

Completes the image loading process. The protocol is the LWImageProtocolID returned by begin. Only call done if you previously called begin.

Example

The iff sample is a complete IFF ILBM loader and saver. The zcomp sample includes an image loader that creates a floating-point grayscale image from the values in a previously saved LWBUF_DEPTH buffer.