Globals: Image List

Image List

Availability  LightWave 6.0
Component  Layout, Modeler
Header  lwimage.h

This global provides access to LightWave's internal image list. Also see the Image Utility global.

A single image ID can refer to image sequences and animations as well as stills, and "image" is used here to refer to all of these. Most of the functions that return pixel information do so for the current state of the image, which generally depends on the current frame during rendering and on the most recently rendered frame at other times.

Global Call

   LWImageList *imglist;
   imglist = global( LWIMAGELIST_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWImageList.

   typedef struct st_LWImageList {
      LWImageID     (*first)    (void);
      LWImageID     (*next)     (LWImageID);
      LWImageID     (*load)     (const char *);
      const char *  (*name)     (LWImageID);
      const char *  (*filename) (LWImageID, LWFrame);
      int           (*isColor)  (LWImageID);
      void          (*needAA)   (LWImageID);
      void          (*size)     (LWImageID, int *w, int *h);
      LWBufferValue (*luma)     (LWImageID, int x, int y);
      void          (*RGB)      (LWImageID, int x, int y,
                                   LWBufferValue[3]);
      double        (*lumaSpot) (LWImageID, double x, double y,
                                   double spotSize, int blend);
      void          (*RGBSpot)  (LWImageID, double x, double y,
                                   double spotSize, int blend, double[3]);
      void          (*clear)    (LWImageID);
      LWImageID     (*sceneLoad)(const LWLoadState *);
      void          (*sceneSave)(const LWSaveState *, LWImageID);
      int           (*hasAlpha) (LWImageID);
      LWBufferValue (*alpha)    (LWImageID, int x, int y);
      double        (*alphaSpot)(LWImageID, double x, double y,
                                   double spotSize, int blend);
      LWPixmapID    (*evaluate) (LWImageID, LWTime t);
   } LWImageList;

image = first()

Returns the first image in the list.

image = next( prev_image )

Returns the image after prev_image in the list, or NULL if prev_image is the last image in the list.

image = load( filename )

Add the image to the list and return its ID. Animation files can be loaded with this function, but image sequences cannot.

iname = name( image )

Returns the name of the image as it appears to the user.

fname = filename( image, frame )

Returns the filename of the image. This is the value that should be stored for later retrieval of the image using load.

iscol = isColor( image )

True for images with color data and false for grayscale images.

needAA( image )

Called by shaders that want to use the image list lumaSpot and RGBSpot functions during rendering. This tells Layout to prefilter the image for later spot evaluation. Currently this function can only be called from a shader's init function.

size( image, width, height )

Returns the width and height of the image in pixels.

gray = luma( image, x, y )

Returns the grayscale value of a pixel. If this is a color image (isColor is true), the value returned is the NTSC/PAL luminance, which combines the RGB levels using the weights 0.2989 red, 0.5866 green, 0.1144 blue.

RGB( image, x, y, color )

Returns the red, green and blue values of a pixel.

gray = lumaSpot( image, x, y, spotsize, blend )

Returns the grayscale value of a spot on the image. x and y are the center of the spot in pixels, and the spot size is the diameter of the spot in pixel units. The value is the weighted average of the pixels within the spot. If blend is true and the spot size is small, however, the value will be interpolated from neighboring pixels that may be outside the spot. Currently this function can only be called during the spot evaluation function of a shader, and needAA must have been called previously from the shader's init function.

RGBSpot( image, x, y, spotsize, blend, color )

Returns the color values of a spot on the image. Like lumaSpot, this function can only be called during the spot evaluation function of a shader.

clear( image )

Remove the image from the image list. This has the effect of removing all references to the image in the scene.

image = sceneLoad( loadstate )

Read an image reference from a file and add the image to the image list. This is meant to be called by a handler's load callback to retrieve an image that's part of its instance data. The reference will have been written by sceneSave.

sceneSave( savestate, image )

Write an image reference to a file. This is meant to be called by a handler's save callback to store a reference to the image as part of the handler's instance data.

hasa = hasAlpha( image )

True if the image includes an alpha channel.

a = alpha( image, x, y )

Returns the alpha value of a pixel.

a = alphaSpot( image, x, y, spotsize, blend )

Returns the alpha value of a spot (see lumaSpot and RGBSpot).

pixmap = evaluate( image, time )

Returns a pixmap of the image that can be used with the Image Utility global. This function creates a copy of the image, similar to calling the Image Utility create function and then copying the pixels using Image List RGB and Image Utility setPixel. But the image is evaluated, meaning that the frame matching the time argument is retrieved for sequences and animations, and any adjustments and filters are applied.

Example

The zcomp sample includes a pixel filter that composites the rendered image with a previously generated image based on the z-depth. It uses the Image List global to manage both the image to be composited and its z-buffer, which is treated as a floating-point grayscale image and read using the luma function.