Preview Functions
Availability LightWave 6.0 | Component Layout, Modeler | Header lwpreview.h
The Preview Functions global is the plug-in API for LightWave's VIPER (Versatile Interactive Preview Render) window. VIPER allows users to preview the effects of shader, environment, volumetric, pixel filter and image filter plug-ins. It uses image buffers from the most recent test render to generate a reduced-size rendering of the scene, and it can composite this with your plug-in's output while the user changes your parameters.
The previewer is an extension of your plug-in's interface. The API supplies functions that let you subscribe (install), set the context (tell VIPER that your interface is the active one), open the VIPER window, give VIPER your rendering callbacks, and get the prerendered image and information about the camera.
This is a low-level API, and you may never need to use it. Beginning with LightWave 7.0, VIPER can preview your plug-in automatically, without your intervention. It switches contexts transparently and calls your regular handler callbacks to render the preview. The rendering of the preview occurs whenever you call the Instance Update global.
Global Call
LWPreviewFuncs *pvf; pvf = global( LWPREVIEWFUNCS_GLOBAL, GFUSE_TRANSIENT );
The global function returns a pointer to an LWPreviewFuncs.
typedef struct st_LWPreviewFuncs { PvContextID (*subscribe) (char *title, void *userData, closeFunc *); void (*unsubscribe)(PvContextID); void (*open) (PvContextID); void (*close) (void); int (*isOpen) (void); void (*setContext) (PvContextID); void (*setClick) (PvContextID, ClickFunc *); void (*setRender) (PvContextID, void *renderData, InitFunc *, CleanupFunc *, EvaluateFunc *); void (*setOptions) (PvContextID, char **list, OptionsFunc *, int selection); void (*startRender)(PvContextID); void (*stopRender) (PvContextID); void (*getPixel) (PvSample *pixel); LWImageID (*getBitmap) (int *width, int *height); LWItemID (*getCamera) (double pos[3], double rot[3], double *zoomFactor); void (*getView) (int *width, int *height, double *pixelAspect); void (*setPreset) (PvContextID, presetFunc *); } LWPreviewFuncs;
preview = subscribe( title, userdata, close_func )
- Obtain a PvContextID that identifies your plug-in instance to the preview system. Generally you'll call this from your interface activation function. The title is the string that should appear in the preview window's title bar when the previewer is set to your context. The user data is passed to your click, options and close callbacks.
unsubscribe( context )
- Invalidate your context ID and free resources allocated by
subscribe
. open( context )
- Open the preview window.
close()
- Close the preview window.
isopen = isOpen()
- Returns TRUE if the preview window is open.
setContext( context )
- Set the preview window's context. After this, the interface and rendering callbacks associated with the context ID will be the ones the previewer calls when responding to the user and generating an image.
setClick( context, click_func )
- Set the callback that will be called when the user clicks on the preview image.
setRender( context, render_data, init_func, cleanup_func, eval_func )
- Set the callbacks that will be called when the previewer renders its display. The render data will be passed to each of the callbacks. Typically, it's your instance data, and the callbacks call your standard handler functions.
setOptions( context, list, options_func, selection )
- Set the options that will appear in the Options popup when your context is the active one. This includes a NULL-terminated array of strings, a callback that's called when an option is selected by the user, and the index of the option that should initially appear selected.
startRender( context )
- Force the previewer to render an image.
stopRender( context )
- Interrupt any rendering being done by the previewer.
getPixel( pixel )
- Get information about a pixel in the previewer's prerendered buffers. Fill in the
x
andy
fields of the PvSample structure for the position of the pixel in the preview image. The previewer will return information about the pixel in the other fields. image = getBitmap( width, height )
- Returns an image ID for the previewer's RGBA buffers. You can use this with the Image List global to query the image. The previewer writes the
image dimensions in the
width
andheight
arguments. camera = getCamera( pos, rot, zoom )
- Get information about the state of the camera at the time the previewer's buffers were generated. You can get more detailed information from the Item Info and Camera Info globals, but it may not match the image in the previewer, since the user may have moved the camera or changed its settings after the previewer image was created.
getView( width, height, pixel_aspect )
- Get information about the size and pixel aspect of the previewer image.
setPreset( context, preset_func )
- Set the callback that will be called when the user wants to create a shelf preset for your plug-in's settings.
Pixel Sample
The getPixel
function and the click and evaluate callbacks store information
about a pixel in a PvSample.
typedef struct st_PvSample { int x, y; float rgbaz[5]; LWMicropol mp; } PvSample;
x, y
- The pixel coordinates.
rgbaz
- The red, green, blue, alpha and depth value at the pixel.
mp
- An LWMicropol structure describing the geometry visible in the pixel. See the
explanation of this structure on the Texture Functions page.
The previewer can only fill in the fields for which it knows the values. These include
gNorm
,wNorm
(the same asgNorm
in this case),oPos
,wPos
,oAxis
,wAxis
and theverts
andweights
arrays. If the display and render subdivision levels differ, the point IDs in theverts
array may not be valid (the previewer has the render mesh, but the plug-in may have the display mesh).
Callbacks
The previewer uses callbacks both for rendering and to allow your plug-in to respond to user actions.
Interface
typedef int clickFunc(int count, void *userData, PvSample *pixel); typedef void optionsFunc(int option, void *userData); typedef void presetFunc(void *userData, LWImageID image); typedef void closeFunc(void *userData);
The click callback tells you that the user has clicked on the preview image and gives
you information about the pixel. The options callback is called when the user has selected
an option from the custom Options pop-up on the preview window. The first argument is an
index into the array of strings you passed to setOptions
. The close callback is
called when the user closes the preview window.
The preset callback tells you that the user wants to add a preset to the shelf for your
plug-in's settings. The image is the same one returned by getBitmap
. Use the Shelf Functions global to add the preset.
The user data for all of these is the pointer you passed to subscribe
.
Rendering
typedef int initFunc(void *renderData, int manual); typedef void cleanupFunc(void *renderData); typedef int evaluateFunc(void *renderData, int w, int h, PvSample *pixel);
Your preview init function should perform the same kinds of operations that your
handler init
and newTime
callbacks perform, and your preview cleanup is
analogous to your handler cleanup
. The second argument to the init callback is
TRUE if the user explicitly requested the render (by clicking on a button in the
previewer's window).
The evaluate callback receives the width and height of the preview image and a PvSample
for the pixel to be evaluated. Your evaluate writes new values in the rgbaz
field
of the PvSample. The PvSample's LWMicropol is read-only (writing to it has no effect).
History
The setPreset
function was added in LightWave 7.0, but LWPREVIEWFUNCS_GLOBAL
was not incremented. Before calling setPreset
, you can use the Product Info global to determine whether you're running in a
version of LightWave prior to 7.0.