Global ImageLoader Classes Table of Contents

ImageFilterHandler
ImageFilterInterface

Image filter plug-ins apply image post processing (filtering) effects to the final rendered image.

Handler Activation Function

   XCALL_( int ) MyImageFilter( long version, GlobalFunc *global,
      LWImageFilterHandler *local, void *serverData );

The local argument to an image filter's activation function is an LWImageFilterHandler.

   typedef struct st_LWImageFilterHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      void            (*process) (LWInstance, const LWFilterAccess *);
      unsigned int    (*flags) (LWInstance);
   } LWImageFilterHandler;

The first two members of this structure are standard handler functions. In addition to these, an image filter provides a processing function and a flags function.

process( instance, access )
This is where the image filter does its work. For each frame, the filter is given access to the red, green, blue and alpha channels of the rendered image, along with any other image buffers requested by the flags function. The access structure, described below, provides image information and functions for examining the buffers and writing new RGB and alpha values.

flags( instance )
Returns an int that tells the renderer which buffers the image filter will need to examine. The return value contains bitfields combined using bitwise-OR. The symbols listed here and in lwfilter.h are bit positions, not the flags themselves, so you'll need to form the expression (1 << LWBUF_WHATEVER) to create the flags before ORing them together. For efficiency reasons, the renderer will ignore requests from the processing function for access to any buffers that weren't indicated by the bit flags returned from the flags function. The buffers are

LWBUF_RED
LWBUF_GREEN
LWBUF_BLUE
LWBUF_ALPHA
The final output of the rendering pass. These form the image to be modified by the filter. They are always provided to every image filter (it isn't necessary to return flags for them in the flags function).
LWBUF_LUMINOUS
LWBUF_DIFFUSE
LWBUF_SPECULAR
LWBUF_MIRROR
LWBUF_TRANS
LWBUF_RAW_RED
LWBUF_RAW_GREEN
LWBUF_RAW_BLUE
The raw, unshaded values of the surface parameters at each pixel.
LWBUF_SHADING
A picture of the diffuse shading and specular highlights applied to the objects in the scene. This is a component of the rendering calculations that depends solely on the angle of incidence of the lights on a surface. It doesn't include the effects of explicit shadow calculations.
LWBUF_DIFFSHADE
LWBUF_SPECSHADE
Like the LWBUF_SHADING buffer, but these store the amount of diffuse and specular shading (highlighting) separately, rather than adding them together. They should not be confused with the LWBUF_DIFFUSE and LWBUF_SPECULAR buffers, which store the unshaded surface values for those parameters.
LWBUF_SHADOW
Indicates where shadows are falling in the final image. It may also be thought of as an illumination map, showing what parts of the image are visible to the lights in the scene.
LWBUF_GEOMETRY
The values in this buffer are proportional to the dot-products of the surface normals with the eye vector (or the cosine of the angle of the surfaces to the eye). They reveal something about the underlying shape of the objects in the image. Where the value is 255 (or 1.0) the surface is facing directly toward the camera, and where it's 0, the surface is edge-on to the camera.
LWBUF_DEPTH
A map of the distance from each pixel on the viewplane to the nearest object the pixel sees. Also known as the z-buffer.
LWBUF_SPECIAL
This value is assigned by the user on a surface by surface basis which is used only for this filter. This is designed to be used to activate the post processing effect for specific surfaces, and user-assigned percentages show up here as 0-255 values in the buffer.

Interface Activation Function

   XCALL_( int ) MyInterface( long version, GlobalFunc *global,
      ??? *???, void *serverData );

TBD.

Filter Access

This is the access structure passed to the processing function. The data members are read-only. The functions provide the means to get and set pixel values, and the optional monitor informs the user of the filter's progress.

   typedef struct st_LWFilterAccess {
      int              width, height;
      LWFrame          frame;
      LWTime           start, end;
      LWBufferValue * (*bufLine)  (int type, int y);
      float *         (*fltLine)  (int type, int y);
      void            (*setRGB)   (int x, int y, LWBufferValue[3]);
      void            (*setAlpha) (int x, int y, LWBufferValue);
      LWMonitor       *monitor;
   } LWFilterAccess;
width, height
The image dimensions of all of the image buffers. Filters can't change the size of the image.
frame
The frame number.
start, end
The start and end times for the frame. The times are the same unless the frame was rendered with motion blur, in which case the difference between them can be considered the exposure time for the frame.

bufLine( buftype, y )
fltLine( buftype, y )
Call these to get a pointer to the start of a scanline from the specified buffer. y = 0 is the top line of the buffer, and y = width - 1 is the bottom line. bufLine returns lines from byte-encoded buffers and fltLine returns lines from float-encoded buffers. Don't try to look past the end of a scanline. Layout may not store scanlines contiguously for a given buffer. In fact, scanlines aren't guaranteed to exist at all until they're requested through these functions. The type codes are the same as those used by the flags function. NULL is returned for invalid type codes, or type codes for buffers not requested by the flags function.

setRGB( x, y, rgb )
setAlpha( x, y, a )
Use these functions to set the output values of the filter. The input RGBA buffers do not change as the output buffers are modified. A filter must set every pixel in the output image even if it does not alter the value, but it can set them in any order.

monitor
The filter can use this to update the user about its progress through the frame. This also allows the user to cancel the rendering during the filter's processing. The monitor mechanism is the same one provided by the monitor global. As with all monitors, the number of steps should be kept fairly low since checking for abort can have significant overhead on some systems. Every line or every other line should be about right.