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