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