Variant Parameters

Availability  LightWave® 6.0
Component  Layout, Modeler
Header  lwvparm.h

A variant parameter, or vparm, is a double-precision variable or 3-vector that can vary as a function of time. Vparms are used as containers for the values of XPanel controls that can be enveloped or textured (any control with "-env" in its type name). That's the rationale for the existence of vparms, but you're free to use them for other things as well.

The variant parameters global supplies the implementation of the vparm data type.

Global Call

   LWVParmFuncs *vparmf;
   vparmf = global( LWVPARMFUNCS_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWVParmFuncs.

   typedef struct st_LWVParmFuncs {
      LWVParmID   (*create)  (int envType, int texType);
      void        (*destroy) (LWVParmID);
      void        (*setup)   (LWVParmID,
                                const char *channelName,
                                LWChanGroupID group,
                                LWTxtrContextID gc,
                                LWVP_EventFunc *eventFunc,
                                const char *pluginName,
                                void *userData);
      LWError     (*copy)    (LWVParmID to, LWVParmID from);
      LWError     (*load)    (LWVParmID, const LWLoadState *load);
      LWError     (*save)    (LWVParmID, const LWSaveState *save);
      double      (*getVal)  (LWVParmID, LWTime t,
                                LWMicropolID mp, double *result);
      int         (*setVal)  (LWVParmID, double *value);
      int         (*getState)(LWVParmID);
      void        (*setState)(LWVParmID, int state);
      void        (*editEnv) (LWVParmID);
      void        (*editTex) (LWVParmID);
      void        (*initMP)  (LWMicropolID mp);
      void        (*getEnv)  (LWVParmID, LWEnvelopeID envlist[3]);
      LWTextureID (*getTex)  (LWVParmID);
   } LWVParmFuncs;

vparm = create( envtype, txtype )

Create a new vparm. The envelope type can be one of the following.

LWVP_FLOAT

A floating-point number.

LWVP_PERCENT

A floating-point number with a nominal range of 0.0 to 1.0. This value will be represented to the user as a percentage.

LWVP_DIST

A floating-point distance. In meters internally, it may appear in the interface with a variety of units.

LWVP_ANGLE

An angle. In radians internally but in degrees for users.

LWVP_COLOR

A floating-point color vector.

Each of these types corresponds to an XPanel control type. To create a 3-vector vparm, add LWVPF_VECTOR to one of the first four types (the LWVP_COLOR type code already includes the LWVPF_VECTOR bit).

By default, the channel names of the vector vparms is determined from the envelope type. For example, for a LWVP_DIST vector envelope the channels will be named "Distance.X", "Distance.Y", and "Distance.Z". Different naming schemes can be selected for vector envelope types by adding one of the naming flags to envtype:

LWVPF_VECTOR_DEFAULTNAMES

The default naming scheme

LWVPF_VECTOR_NONAMES

The channels are named only using the vector type postfixes

LWVPF_VECTOR_PARMNAMES

Uses the name of the vparm plus the vector type postfix

Note that the channel name, no matter how constructed, must be unique.

The texture type corresponds to the return type you would specify in the Texture Functions create function and can be one of the following.

LWVPDT_NOTXTR
LWVPDT_VECTOR
LWVPDT_COLOR
LWVPDT_PERCENT
LWVPDT_SCALAR
LWVPDT_DISPLACEMENT

destroy( vparm )

Free a vparm.

setup( vparm, name, cgroup, txcontext, eventfunc, plugname, userdata )

Initialize a vparm. This must be called for every vparm you create. The name is the name of the envelope (the base name for vectors), and the cgroup is the channel group in which the envelopes are created. The name must be unique within the group. The event callback is described below. The plug-in name (the name in your ServerRecord's name field) and user data are used by LightWave® to identify the owner of a vparm. The user data is also passed to the event callback.

error = copy( vpto, vpfrom )

Copy a vparm. This will primarily be called by handler copy callbacks.

error = load( vparm, loadstate )

Read a vparm from a file. This is meant to be called by handler load callbacks, but it might also be called by plug-ins using the file I/O global to read a file containing vparm data.

error = save( vparm, savestate )

Write a vparm to a file. This is meant to be called by handler save callbacks, but might also be used to save the vparm to a file created through the file I/O global.

result = getVal( vparm, time, micropol, value )

Get the value of a vparm. The micropol is used by textures. If it is NULL, the texture's contribution to the value is ignored. See the Texture Functions global for a description of the LWMicropol structure. The value argument should always point to storage for three doubles, whether or not the vparm is a vector. If the vparm is textured, getVal returns the texture opacity.

result = setVal( vparm, value )

Set the value of a vparm. If the value is enveloped, calling this has no effect. Returns the number of elements processed (0, 1, or 3).

state = getState( vparm )

Returns a set of state bits. If the LWVPSF_ENV bit is set, an envelope exists for the vparm, and if the LWVPSF_TEX bit is set, the vparm has a texture.

setState( vparm, state )

Create or destroy the vparm's underlying envelope or texture. The state argument uses the same state bits as getState. If the bit is clear (0), the envelope or texture is destroyed, and if the bit is set (1), an envelope or texture is created for the vparm using the information previously specified in setup. Never call this for a vparm associated with an XPanel control. The XPanel system takes care of creating and destroying vparm envelopes and textures automatically.

editEnv( vparm )

Open the graph editor for the vparm. This does nothing if the vparm isn't enveloped. You won't need to call this for a vparm associated with an XPanel control, since the control will give the user a way to call the graph editor without your help.

editTex( vparm )

Open the texture editor for the vparm. This has no effect if no texture has been created for the vparm. You won't need to call this for vparms used with XPanel controls.

initMP( micropol )

Initialize a micropolygon. The transformation matrices are set to the identity matrix. Most other fields are set to 0.

getEnv( vparm, envarray )

Gets the envelope IDs of the vparm's envelopes. The first element of the array will contain the single ID for non-vector vparms. If no envelopes exist for the vparm, the array elements will be NULL.

texture = getTex( vparm )

Returns the texture ID for the vparm's texture.

Event Callback

The event callback you pass to setup is used to inform you of changes to the underlying envelopes and texture of your vparm, and in one case to ask you for data needed by the texture.

   typedef int LWVP_EventFunc( LWVParmID vp, void *userdata,
      en_lwvpec eventcode, void *eventdata );

The userdata is whatever you passed as the last argument to setup. The eventcode will be one of the following.

LWVPEC_TXTRACK

Generated as the texture changes.

LWVPEC_TXUPDATE

Generated after the texture has changed.

LWVPEC_TXAUTOSIZE

Request for texture autosize. For this event, eventdata is an array of six doubles (x low, x high, y low, y high, z low, z high) that you're being asked to initialize for the default size of the texture.

LWVPEC_ENVTRACK

Generated as the envelope changes.

LWVPEC_ENVUPDATE

Generated after the envelope has changed.

LWVPEC_ENVNEW

An envelope has been created.

LWVPEC_ENVOLD

An envelope is being destroyed.

LWVPEC_TEXNEW

A texture has been created.

LWVPEC_TEXOLD

The texture is being destroyed.

LWVPEC_ENVRENAME

The envelope group has been renamed.

Currently, for all events other than TXAUTOSIZE, the eventdata will be NULL and can be ignored.

Example

Several of the SDK samples (blotch, inertia, mandfilt and rapts) use vparms as part of their XPanel interfaces. It's not a coincidence that all of these are handlers, since handlers are more likely to need time-dependent parameters.