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