Globals: Preview Functions

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 and y 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 and height 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 as gNorm in this case), oPos, wPos, oAxis, wAxis and the verts and weights arrays. If the display and render subdivision levels differ, the point IDs in the verts 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.