ImageFilterHandler ImageSaver Classes Table of Contents

ImageLoader

Availability:  LightWave 6.0
Component:  Layout, Modeler

Image loaders move still image data into LightWave, translating to LightWave's internal image formats from the myriad file formats available for image storage.

When an image loader's activation function is called, it should open the image file and try to recognize its contents. This first step is important. 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 obtain the functions it will use to send the image data to LightWave and then calls those functions.

Activation Function

   XCALL_( int ) MyImageLoader( long 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 returned by the global monitor call. See the global monitor page for details.

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. The type must be one of the types listed later in the Pixel Data section.

The begin function returns a pointer to an LWImageProtocol, which is the structure you'll use to actually transfer the image data. The LWImageProtocol structure is described in detail below. 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 argument should be the LWImageProtocolID returned to you by begin. Only call done if you previously called begin.

Image Protocol

The LWImageProtocol structure returned by the local begin function provides the functions you'll call to send the image data to LightWave. The lwimageio.h header file defines macros that slightly simplify calls to these functions, although they won't be described here. Using the macros is optional.

   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
LightWave sets this to the pixel type code you sent in the call to begin.

priv_data
Pass this to the protocol functions. It's an opaque pointer to data used internally by LightWave.

done( priv_data, result )
Call this when you've finished sending image data. The result should be IPSTAT_OK or IPSTAT_FAILED.

setSize( priv_data, width, height )
Call this to tell LightWave 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 must be called before the first call to sendLine.

setParam( priv_data, paramid, intparam, floatparam )
Use this to tell LightWave 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. Set the value in floatparam and set intparam to 0.

LWIMPAR_NUMCOLS
The size of the color table in an indexed-color image (an image of type LWIMTYP_INDEX8). Valid values are between 2 and 256. Set the value in intparam and set floatparam to 0.

sendLine( priv_data, y, scanline_pixels )
Send one scanline from the image. setSize must be called before the first call to sendLine. Scanlines don't have to be sent in a particular order. Scanlines are numbered from the top of the image, starting at 0. The first data item in each scanline describes the leftmost pixel. The structure of the pixel data will depend on the pixel type you set in the local begin function. Details about specific types are below.

setMap( priv_data, index, rgb )
Call this to set the color of an entry in the color table of an indexed-color image. You need to call setParam with a LWIMPAR_NUMCOLS parameter before calling setMap for the first time, but you may call setMap any time after that. The index identifies the color table entry and must be between 0 and numcolors-1.

Pixel Data

The structure of the data in a scanline will vary, depending on the pixel type. Each scanline is an array of either unsigned bytes or floats. Bytes can contain any value between 0 and 255. The nominal range of float values is 0.0 to 1.0, but values outside that range may also be valid.

Each pixel's data is contiguous--the scanline contains all of the channel values for the first pixel, followed by the values for the second, and so on. The lwimageio.h header file contains typedefs for some pixel types, but use of these in your code is currently optional.

For each pixel type, the data is organized as follows.

LWIMTYP_RGB24
Each scanline is an array of unsigned char in RGBRGB... order. The corresponding typedef is LWPixelRGB24.
LWIMTYP_GREY8
Each scanline is an array of unsigned char, with one byte per grayscale pixel.
LWIMTYP_INDEX8
Each scanline is an array of unsigned char, with one byte per pixel containing color map indexes.
LWIMTYP_GREYFP
Each scanline is an array of float, with one float per pixel.
LWIMTYP_RGBFP
Each scanline is an array of float in RGBRGB... order. The corresponding typedef is LWPixelRGBFP.
LWIMTYP_RGBA32
Each scanline is an array of unsigned char in RGBARGBA... order and contains both RGB color and alpha channel values. The corresponding typedef is LWPixelRGBA32.
LWIMTYP_RGBAFP
Each scanline is an array of float in RGBARGBA... order and contains both RGB color and alpha channel values. The corresponding typedef is LWPixelRGBAFP.
LWIMTYP_RGBAZFP
Each scanline is an array of float in RGBAZRGBAZ... order and contains RGB color, alpha, and depth channel values. The corresponding typedef is LWPixelRGBAZFP. The depth, or z, channel contains viewing coordinate system z coordinates, in meters.