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( 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
anddone
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 callbegin
, you must also calldone
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 calldone
if you previously calledbegin
.
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.