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 ifprev_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
andRGBSpot
functions during rendering. This tells Layout to prefilter the image for later spot evaluation. Currently this function can only be called from a shader'sinit
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
andy
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. Ifblend
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, andneedAA
must have been called previously from the shader'sinit
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
andRGBSpot
). 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 ListRGB
and Image UtilitysetPixel
. But the image is evaluated, meaning that the frame matching thetime
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.