The Channel Object Agent provides a structured interface to individual channel functionality. The methods firstChannel() and nextChannel() return a Channel Object type. In some cases, a Channel Object Agent will be provided to a UDF (as in the case of the create() UDF for the Channel Filter LScript).

Your script does not directly use keyframe identifiers, and returns them as integer data types. Keyframe identifiers serve only as arguments to methods that require them.

Data Members

name
name is the name of the channel as it appears in the Layout interface. (e.g., Graph Editor).

id
id is the integer id of the channel.

type
type is the type of the channel. This can be one of the following:

CHAN_NUMBER, CHAN_DISTANCE, CHAN_PERCENT, or CHAN_ANGLE.

parent(only works from LW9.31 onwards)
parent contains the LightWave Object Agent to whom the channel belongs.

keyCount
keyCount returns the number of keys in the envelope associated with the channel.

keys[ ]
keys[] is a linear array that holds the keyframe identifiers for all the keys in the envelope. It will always be 'keyCount' in length.

preBehavior
preBehavior holds the type of pre-behavior associated with the envelope. It will be one of: CHAN_RESET, CHAN_CONSTANT, CHAN_REPEAT, CHAN_OSCILLATE, CHAN_OFFSET, CHAN_LINEAR.

The string values: ‘reset,’, ‘constant,’ ‘repeat,’ ‘oscillate,’ ‘offset,’ or ‘linear’ can also be used.

Unlike most data members, this data member is NOT read-only. Assigning one of the above constants to it will actually alter the prebehavior of the associated envelope.

postBehavior
postBehavior holds the type of the post-behavior associated with the envelope. Except for its name, this data member functions identically to the 'preBehavior' data member. It returns or alters the post-behavioral setting for the envelope.

Methods

value(time)
The value(time) method causes the channel to be evaluated at the specified time. The return values are floating-point numbers that should be interpreted based on the channel's type.

event(UDF)
The event(UDF) method activates a callback function that is invoked whenever an event occurs on the channel. Such events could be creating or deleting keyframes in the envelope, or a changing the keyframe's value.

keyExists(<time>)
keyExists(<time>) returns either 'nil' if no key exists at the specified time index, or the identifier of the keyframe if it does.

setKeyValue(<key>,<value>)
setKeyValue(<key>,<value>) sets the value of the provided keyframe to the provided value. <value> is always a floating-point number.

setKeyCurve(<key>,<shape>)
setKeyCurve(<key>,<shape> sets the type of interpolation that evaluates the keyframe. This can be one of: CHAN_TCB, CHAN_HERMITE, CHAN_BEZIER, CHAN_LINEAR, CHAN_STEPPED.

Also, the strings: ‘TCB,’ ‘Hermite,’ ‘Bezier,’ ‘Linear,’ and ‘Stepped’ are acceptable.

setKeyHermite(<key>,<parm1>,<parm2>,<parm3>,<parm4>)
setKeyHermite(<key>,<parm1>,<parm2>,<parm3>,<parm 4> allows you to set the four Hermite Spline coefficients. If you do not understand their use, you probably will not be using this method anyway.

setKeyTension(<key>,<value>)
setKeyTension(<key>,<value>) sets the tension value for the specified keyframe.

setKeyContinuity(<key>,<value>)
setKeyContinuity(<key>,<value>) sets the continuity value for the specified keyframe.

setKeyBias(<key>,<value>)
setKeyBias(<key>,<value>) sets the bias value for the specified keyframe.

getKeyValue(<key>)
getKeyValue(<key>) returns the floating-point value associated with the specified keyframe.

getKeyTime(<key>)
getKeyTime(<key>) returns the time index for the specified keyframe.

getKeyCurve(<key>)
getKeyCurve(<key>) returns the curve type for the specified keyframe. See the entry for setKeyCurve() for a list of the constant values that are returned.

getKeyHermite(<key>)
getKeyHermite(<key>) returns the four Hermite Spline coefficients that are currently in use for the specified keyframe. If get KeyCurve() does not return CHAN_HERMITE, then you probably do not want to call this method.

getKeyTension(<key>)
getKeyTension(<key>) returns the current tension setting for the keyframe.

getKeyContinuity(<key>)
getKeyContinuity(<key>) returns the current continuity setting for the keyframe.

getKeyBias(<key>)
getKeyBias(<key>) returns the current bias setting for the keyframe.

createKey(<time>,<value>)
The createKey(<time>,<value>) method creates a new keyframe at the specified time index with the provided initial value. If the key is created successfully, the keyframe identifier is returned, otherwise 'nil' is returned. This method will cause the 'keyCount' and 'keys[]' data members to instantly update.

deleteKey(<key>)

Keyframes can be deleted from the channel's envelope with the deleteKey(<key>) method. Because this method also causes the 'keyCount' and 'keys[]' data members to update in real time, you need to be very careful when using it within loops that are based on these data members.

Examples:

The following Channel Filter script illustrates the use of the Channel Object Agent:

@warnings
@script channel
@version 2.0

create: channel
{
    light = Light();
    c = light.firstChannel();
    while(c)
    {
         last if c.name == "Position.X";
         c = light.nextChannel();
    }
    // keep abreast of changes in this channel...
    c.event("lightEvent");
}
process: ca, frame, time
{
    ca.set(0.0);
}
lightEvent: channel,
// Channel Object Agent event
// event code
{
    // something happened to Light's
    //"Position.X" channel
    info(event);
}

General Commands

AddingExpressions

Expressions can be added and attached to channels by using the Graph editor CommandImput commands, found in the SDK. All expression names/ names of items referenced should be unique, or this could cause a crash in LW. Also, expression names and expressions should for safety be enclosed in quote marks as this will stop spaces or other odd characters crashing LW.Example

add_exp
{
    com = string("GE_CreateExpression ",exp_name," ",exp);
    CommandInput(com);

    com = string("GE_AttachExpression ","Camera.Position.X"," ",exp_name);
    CommandInput(com);
}

Example 2
    mypar=pobj.parent;
    drivername=mypar.name+"."+pswitch.name;
    myvisible=pobj.name+".Layer_visibility";
    myalpha=pobj.name+".Layer_alpha";
    myexp="\"Value * (1 -["+drivername+"]*["+myvisible+"]*["+myalpha+"])\""; // \" will give you a quote mark within a quote
    myexpname="\"Switch_"+pobj.name+"\"";
    mycom="GE_CreateExpression "+myexpname+" "+myexp;
    CommandInput(mycom);
    chanid=pchan.id;
    mycom="GE_AttachExpressionID "+chanid.asStr()+myexpname;
    CommandInput(mycom);


LW11.6 :
Added graph editor commands to allow detaching of expressions, and clearing of unused expressions.


GE_DetachExpression schannelname sexpressionname [nclear]
GE_DetachExpressionID xchannelid sexpressionname [nclear]

Detached an expression from the channel identified either by name or by channel ID. If the optional clear argument is set to 1, then the expression will be cleared if it is no longer used by any channel.



GE_DetachExpressions schannelname [nclear]
GE_DetachExpressionsID xchannelid [nclear]

Detached all expressions from the channel identified either by name or by channel ID. If the optional clear argument is set to 1, then any expression detached will be cleared if it is no longer used by any channel.



GE_ClearUnusedExpression sexpressionname
GE_ClearUnusedExpressions

Clears an expression, or all expressions, that are not in use by any channel.