ChannelHandler

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

A channel is a value that can vary continuously with time. Channels are everywhere in LightWave®. Any animation parameter that can be enveloped is associated with an underlying channel. Channel handlers dip into the stream of a parameter and alter its value.

Handler Activation Function

   XCALL_( int ) MyChannel( int version, GlobalFunc *global,
      LWChannelHandler *local, void *serverData );

The local argument to a channel handler's activation function is an LWChannelHandler.

   typedef struct st_LWChannelHandler {
      LWInstanceFuncs *inst;
      LWItemFuncs     *item;
      void            (*evaluate) (LWInstance, const LWChannelAccess *);
      unsigned int    (*flags)    (LWInstance);
   } LWChannelHandler;

The first two members of this structure are standard instance handler functions. The context argument to the create function is the LWChannelID of the associated channel. When the plug-in is activated by Modeler, the item member of the LWChannelHandler will be NULL. Check for this before assigning the item callbacks.

A channel handler also provides an evaluation function and a flags function.

evaluate( instance, access )

The channel value is examined and modified at each time step using functions in the channel access structure, described below.

f = flags( instance )

Returns an integer containing bit flags combined using bitwise-or. No flags are currently defined for channel handlers, so this should return 0.

Interface Activation Function

   XCALL_( int ) MyInterface( int version, GlobalFunc *global,
      LWInterface *local, void *serverData );

This is the standard interface activation for handlers. Channel handlers are selected on the graph editor panel, and their non-modal interfaces will be drawn there.

Channel Access

This is the structure passed to the handler's evaluation function.

   typedef struct st_LWChannelAccess {
      LWChannelID   chan;
      LWFrame       frame;
      LWTime        time;
      double        value;
      void         (*getChannel)  (LWChannelID chan, LWTime t,
                                     double *value);
      void         (*setChannel)  (LWChannelID chan, const double value);
      const char * (*channelName) (LWChannelID chan);
   } LWChannelAccess;

chan

The channel ID.

frame

The frame number of the evaluation.

time

The time of the evaluation, in seconds.

value

The current value of the channel at the given time.

getChannel( channel, time, value )

Retrieves a value from a channel.

setChannel( channel, value )

Sets the value of the channel.

name = channelName( channel )

Returns the name associated with the channel ID.

Example

Several of the SDK samples are channel handlers. NoisyChan uses the texture system's noise function to modify a channel. A channel handler is one of four classes demonstrated in txchan, which also uses textures as channel modifiers. xpanchan is a channel handler that demonstrates four ways of displaying the same XPanels interface.