Item Info

The item info global returns functions for traversing a list of the items in a scene and for getting information about any one of them. The information available through this global is common to all item types. Information specific to certain item types is provided through separate global functions.

Global Call

   LWItemInfo *iteminfo;
   iteminfo = global( LWITEMINFO_GLOBAL, GFUSE_TRANSIENT );

   typedef struct st_LWItemInfo {
      LWItemID      (*first)       (LWItemType, LWItemID);
      LWItemID      (*next)        (LWItemID);
      LWItemID      (*firstChild)  (LWItemID parent);
      LWItemID      (*nextChild)   (LWItemID parent, LWItemID prevChild);
      LWItemID      (*parent)      (LWItemID);
      LWItemID      (*target)      (LWItemID);
      LWItemID      (*goal)        (LWItemID);
      LWItemType    (*type)        (LWItemID);
      const char *  (*name)        (LWItemID);
      void          (*param)       (LWItemID, LWItemParam, LWTime,
                                     LWDVector);
      unsigned int  (*limits)      (LWItemID, LWItemParam,
                                     LWDVector min, LWDVector max);
      const char *  (*getTag)      (LWItemID, int);
      void          (*setTag)      (LWItemID, int, const char *);
      LWChanGroupID (*chanGroup)   (LWItemID);
      const char *  (*server)      (LWItemID, const char *, int);
      unsigned int  (*serverFlags) (LWItemID, const char *, int);
      void          (*controller)  (LWItemID, LWItemParam, int type[3]);
      unsigned int  (*flags)       (LWItemID);
      LWTime        (*lookAhead)   (LWItemID);
      double        (*goalStrength)(LWItemID, LWTime);
      void          (*stiffness)   (LWItemID, LWItemParam, LWDVector);
      unsigned int  (*axisLocks)   (LWItemID, LWItemParam);
      unsigned int  (*maxLookSteps)   (LWItemID);
      double        (*reliableDist)   (LWItemID);
      unsigned int  (*goalObjective)  (LWItemID);
      double        (*ikfkBlending)   (LWItemID, LWTime);
      unsigned int  (*ikInitialState) (LWItemID);
      LWFrame       (*ikInitialStateFrame)  (LWItemID, LWTime);
      unsigned int  (*ikSoft)      (LWItemID, LWTime, unsigned int *, double *min, double *max);
      LWItemID      (*pole)        (LWItemID);
      LWItemID      (*sameItem)             (LWItemID, LWItemParam);
      double        (*sameItemBlend)        (LWItemID, LWItemParam, LWTime);
      unsigned int  (*sameItemBlendMethod)  (LWItemID, LWItemParam);
      unsigned int  (*sameItemFlags)        (LWItemID, LWItemParam);
   } LWItemInfo;

id = first( itemtype, bone_object )

Returns the ID of the first item of a given type, or LWITEM_NULL if there are no items of this type in the scene. Valid item types are

LWI_OBJECT

LWI_LIGHT

LWI_CAMERA

LWI_BONE

If itemtype is LWI_BONE, the second argument is the ID of the boned object. Otherwise it should be LWITEM_NULL.

id = next( item )

Returns the next item of the same type as the item argument. If there are no more, this returns LWITEM_NULL.

id = firstChild( parent )

Returns the first child item of the parent item, or LWITEM_NULL if the parent item has no children.

id = nextChild( parent, child )

Returns the next child item given a parent item and the previous child, or LWITEM_NULL if there are no more children.

id = parent( item )

Returns the item's parent, if any, or LWITEM_NULL.

id = target( item )

Returns the item's target, if any, or LWITEM_NULL.

id = goal( item )

Returns the item's goal, if any, or LWITEM_NULL.

itemtype = type( item )

Returns the type of an item.

itemname = name( item )

Returns the name of the item as it appears to the user.

param( item, param_type, time, vector )

Returns vector parameters associated with an item. This data is read-only. The param_type argument identifies which parameter vector you want. The parameters are

LWIP_POSITION

The keyframed position before parenting. Equivalently, if the item is parented, this is its position relative to its parent.

LWIP_W_POSITION

The keyframed position in world coordinates (after parenting).

LWIP_ROTATION

The keyframed rotation, in radians (relative to its parent's rotation).

LWIP_SCALING

The keyframed scale factors (relative to the parent's scale).

LWIP_PIVOT

LWIP_PIVOT_ROT

The item's pivot point position and rotation, in its own coordinates. The pivot point is the origin for the item's rotations.

LWIP_RIGHT

LWIP_UP

LWIP_FORWARD

+X, +Y and +Z direction vectors for the item, in world coordinates. Together they form the item's rotation and scale transformation matrix. Since they include scaling, these vectors aren't normalized.

LWIP_W_RIGHT

LWIP_W_UP

LWIP_W_FORWARD

+X, +Y and +Z direction vectors for the world, in item coordinates. In other words, these are the inverse of the previous parameters.

The value is written to the vector array for the given time.

flags = limits( item, param_type, minvec, maxvec )

Get upper and lower bounds on vector parameters. These may be limits set by the user on joint angles or ranges of movement. The function returns an integer containing bit flags that indicate which of the three vector components contain limits. The symbols for these bits are

LWVECF_0

LWVECF_1

LWVECF_2

If the bit is set, then the corresponding element of the vector array contains a valid limit. If the bit is 0, the channel is unbounded. The param_type is one of LWIP_POSITION, LWIP_ROTATION, and LWIP_SCALING.

tag = getTag( item, tagnum )

Retrieve a tag string associated with an item.The tags are numbered starting at 1. getTag returns NULL if the tag number is out of range. Tags strings are stored with the item in the scene file.

setTag( item, tagnum, tag )

Associate a tag string with an item. If tagnum is 0, a new tag is created for the item. If tagnum is the number of an existing tag, the tag string for that tag is replaced. If tagnum is outside these values, the setTag call is ignored.

changroup = chanGroup( item )

Returns the channel group associated with an item. Use this with the Animation Envelopes and Channel Info globals.

servname = server( item, class, index )

Returns the name of a plug-in applied to an item. The class argument is the class name, and the index refers to the position in the server list for that class. The first server in the list has an index of 1. Returns NULL if no plug-in matching the arguments can be found. This function can also be used to query the names of servers that aren't associated with items, such as pixel and image filters and volumetrics, and for those the item ID is ignored.

flags = serverFlags( item, class, index )

Returns flags for the plug-in identified by the item, class name and server list index. Currently the possible flags are

LWSRVF_DISABLED

LWSRVF_HIDDEN

controller( item, param_type, hpb_controllers )

Returns a code indicating which mechanism controls the item's position, rotation, and scale. The param_type is one of LWIP_POSITION, LWIP_ROTATION, and LWIP_SCALING. The third argument is an array of three integers, one each for heading, pitch and bank, that receive a controller code for keyframes, targeting, alignment to a path, or inverse kinematics. The returned code is one of:

LWMOTCTL_KEYFRAMES

LWMOTCTL_TARGETING

LWMOTCTL_ALIGN_TO_VELOCITY

LWMOTCTL_IK

LWMOTCTL_ALIGN_TO_PATH

LWMOTCTL_POLE

itemflags = flags( item )

Returns certain item settings as a set of bit flags:

LWITEMF_ACTIVE

LWITEMF_UNAFFECT_BY_IK

LWITEMF_FULLTIME_IK

LWITEMF_GOAL_ORIENT

LWITEMF_REACH_GOAL

LWITEMF_USE_IKCHAINVALS

time = lookAhead( item )

Returns the look-ahead interval, in seconds, for motion channels controlled by LWMOTCTL_ALIGN_TO_PATH. This is the amount of time by which changes in orientation of the item anticipate changes in the path direction.

strength = goalStrength( item, time )

Returns the item's IK goal strength.

stiffness( item, param_type, vector )

Fills vector with the item's joint stiffness settings for position, rotation, or scale. Use one of LWIP_POSITION, LWIP_ROTATION, and LWIP_SCALING as the param_type.

flags = axisLocks( item, param_type )

Returns bits indicating which channels are locked in the UI. See limits().

steps = maxLookSteps( item )

Returns the maximum number of steps taken for align to path. If the no reliable distance has been found within the maximum number of steps, path alignment will be considered to be unreliable.

distance = reliableDistance( item )

Returns the distance which is considered reliable for align to path.

objective = goalObjective( item )

Returns the objective for using the item's IK goal. The returned value is one of:

LWMOTGOAL_POSITION

LWMOTGOAL_POINT

LWMOTGOAL_ONYZPLANE

blend = ikfkBlending( item, time )

Returns the IK/FK blending factor. A value of 0 means fully IK, while a value of 1 means fully FK.

state = ikInitialState( item )

Returns how the IK solver determines the initial state to start solving from. The possible states are:

LWMOTIK_INIT_FIRSTKEY

Initialize with the values from the first keyframe for each IK controlled channel.

LWMOTIK_INIT_MOSTRECENTKEY

Initialize with the values from the most recent keyframe.

LWMOTIK_INIT_CURRENTCHAN

Initialize with the current channel values.

LWMOTIK_INIT_CUSTOMFRAME

Initialize with the channel values from a given frame number.

frame = ikInitialStateFrame( item, time )

If the IK solver initial state is set to LWMOTIK_INIT_CUSTOMFRAME, then the frame number to use is returned by this function.

softik_type = ikSoft( item, time, distance_type, min, max )

Queries the soft IK settings of the item. The return value is the type of soft IK applied, if any:

LWMOTIK_SOFT_OFF

No soft IK applied.

LWMOTIK_SOFT_EXPONENTIAL

Exponential falloff soft IK applied.

LWMOTIK_SOFT_LINEAR

Linear falloff soft IK applied.

LWMOTIK_SOFT_CLAMP

Clamped soft IK applied.

The values filled into distance_type, min, and max will only be valid if soft IK is not off. They describe how the min and max soft distances are calculated:

LWMOTIK_SOFT_CHAINCHORD

The min and max values are given as a fraction of the straight-line distance between chain root and goal.

LWMOTIK_SOFT_CHAINLENGTH

The min and max values are given as a fraction of the distance along the chain from root to goal.

LWMOTIK_SOFT_CUSTOMDISTANCE

The min and max values are used as the distances directly.

id = pole( item )

Returns the item's pole, if any, or LWITEM_NULL.

id = sameItem( item, param_type )

Returns the item's "Same As Item" item for the given parameter, or LWITEM_NULL if none set. The parameter is one of:

LWIP_POSITION

LWIP_ROTATION

LWIP_SCALING

blend = sameItemBlend( item, param_type, time )

Returns the item's "Same As Item" blending factor at a given time. The parameter is one of:

LWIP_POSITION

LWIP_ROTATION

LWIP_SCALING

method = sameItemBlendMethod( item, param_type )

Returns the item's "Same As Item" blending methoditem for the given parameter. The parameter is one of:

LWIP_POSITION

LWIP_ROTATION

LWIP_SCALING

The returned method is one of:

LWMOTCTL_SAMEITEM_INTERPOLATE

LWMOTCTL_SAMEITEM_COMPENSATE

flags = sameItemFlags( item, param_type )

Returns any flags for the item's "Same As Item" setting. The parameter is one of:

LWIP_POSITION

LWIP_ROTATION

LWIP_SCALING

The returned value is zero or more of the following bitflags:

LWMOTCTL_SAMEITEM_WORLD

LightWave® 7.5 added the axisLocks function, but LWITEMINFO_GLOBAL was not incremented. If you ask for "LW Item Info 3", use the Product Info global to determine whether you're running in LightWave® 7.0 or later before attempting to call these functions.

LightWave® 9.0 added the maxLookSteps and reliableDistance functions, and the version number of item info was incremented to 4. The align to path algorithm was improved to search through time around the current time until the total item movement is sufficiently large to be considered reliable for determining alignment. The old algorithm has been renamed as "Align to Velocity" to more accurately reflect how it worked. The LWMOTCTL_ALIGN_TO_PATH define has been changed to indicate the new algorithm, while the newly introduced LWMOTCTL_ALIGN_TO_VELOCITY indicates the old algorithm.

Example

This code fragment traverses the object list, collecting names and some parameters.

   #include <lwserver.h>
   #include <lwrender.h>

   LWItemInfo *iteminfo;
   LWItemID id;
   char *name;
   LWTime t = 3.0;          /* seconds */
   LWDVector rt, up, fd;

   iteminfo = global( LWITEMINFO_GLOBAL, GFUSE_TRANSIENT );
   if ( iteminfo ) {
      id = iteminfo->first( LWI_OBJECT, NULL );
      while ( id ) {
         name = iteminfo->name( id );
         iteminfo->param( id, LWIP_RIGHT, t, rt );
         iteminfo->param( id, LWIP_UP, t, up );
         iteminfo->param( id, LWIP_FORWARD, t, fd );
         if ( rt[ 0 ] > 0.0 ) { ...

         id = iteminfo->next( id );
      }
   }

   LWDVector p, q, rt, up, fd, wrt, wup, wfd, wpos, piv;
   LWItemID id;
   ...
   iteminfo->param( id, LWIP_RIGHT,      t, rt );
   iteminfo->param( id, LWIP_UP,         t, up );
   iteminfo->param( id, LWIP_FORWARD,    t, fd );
   iteminfo->param( id, LWIP_W_POSITION, t, wpos );
   iteminfo->param( id, LWIP_PIVOT,      t, piv );

   for ( i = 0; i < 3; i++ )
      q[ i ] = ( p[ 0 ] - piv[ 0 ] ) * rt[ i ]
             + ( p[ 1 ] - piv[ 1 ] ) * up[ i ]
             + ( p[ 2 ] - piv[ 2 ] ) * fd[ i ]
             + wpos[ i ];

   iteminfo->param( id, LWIP_W_RIGHT,   t, wrt );
   iteminfo->param( id, LWIP_W_UP,      t, wup );
   iteminfo->param( id, LWIP_W_FORWARD, t, wfd );

   for ( i = 0; i < 3; i++ )
      p[ i ] = ( q[ 0 ] - wpos[ 0 ] ) * wrt[ i ]
             + ( q[ 1 ] - wpos[ 1 ] ) * wup[ i ]
             + ( q[ 2 ] - wpos[ 2 ] ) * wfd[ i ]
             + piv[ i ];