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);
      void          (*changeEvent) (LWImageEventFunc *,int);
      int           (*replace)  (LWImageID, const char *);
      LWPixmapID    (*create)   (const char *name, int width, int height, LWImageType type);
      void          (*saverNotifyAttach)( LWInstance, LWImageSaverNotify );
      void          (*saverNotifyDetach)( LWInstance );
      void          (*saverNotifyMarkUsage)( LWTextureID );
   } 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. The pixmap should not be destroyed. It will be managed by the image editor.; Note that the returned pixmap may become invalid if the image is evaluated again, either by a plugin or the image editor. Evaluate the image just before the pixmap is needed, and do not hold on to it for any length of time (for example, after a plugin returns control back to LightWave).
changeEvent( func, code )(LW8.0+): A plug-in can register for notification whenever the state of an image changes. The func paramter is a pointer to a function (whose prototype matches the LWImageEventFunc typedef) that will be called by the application when the state of a LWImage change. An event code and the LWImageID that is effected are provide as arguments to the registered callback function.; The code argument is one of LWERC_REGISTER, to register the provided func as an active callback, or LWERC_UNREGISTER, to remove the specified func from the callback database.; It is extremely important that the plug-in unregister its callback function from the internal database before it is removed from memory. Otherwise, a dangling pointer condition can lead to a crash the next time an event occurs on any LWImage.; The following events are available:
: LWCEV_CHANGE: This is sent after an image has been updated. The image source reamined the same, but modifiers may have been altered that affect the final image.; LWCEV_REPLACE: This is sent after an image has been replaced by another image. This is similar to LWCEV_CHANGE except that it refers to the source of the image has changed, not elements that modify it.; LWCEV_DESTROY: This is sent just before an image is going to be removed and destroyed from the image list. This allows the plugin to remove references to the image to avoid dangling pointers.
result = replace( image, filename )(LW8.0+): This function will perform an in-place substitution of the specified LWImageID with the image found in the provided filename. If the replacement succeeds, a non-zero value is returned.
pixmap = create( name, width, height, type )(LW9.2+): Creates a new image to the image list. The pixmap of the image is returned, which can be used with the Image Utility global. This pixmap should not be destroyed. The type can be any of the pixel types. The created image will be blank. Although the image can be referenced (in for example textures), the contents of the image will not be saved. When the scene is loaded, a blank image will be recreated instead.; The name should be unique. If an image with the given name already exists, the pixmap for the existing image is returned.; The image created in this way could be used as a blank canvas to bake filters, or to create temporary images.
saverNotifyAttach( LWInstance, LWImageSaverNotify )(LW9.6+): This called is made to attach a callback to enable textures to be saved in LWO's. This call should be made shortly after the plugin is created.
saverNotifyDetach( LWInstance )(LW9.6+): When the plugin instance is not longer in use, this call should be made to remove the callback to texture being saved in LWO's. If the plugin instance is removed without making this call, LightWave will crash.
saverNotifyMarkUsage( LWTextureID )(LW9.6+): This is useded within the callback LWImageSaverNotify, to save LightWave layer textures. It is ok to return NULL from within the callback.

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.