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