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 (theLWVP_COLOR
type code already includes theLWVPF_VECTOR
bit).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 thecgroup
is the channel group in which the envelopes are created. The event callback is described below. The plug-in name (the name in your ServerRecord'sname
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. Thevalue
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 theLWVPSF_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 asgetState
. 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 insetup
. 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.
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.