Interface Info Layout Monitor Globals Table of Contents

Item Info

Availability  LightWave® 6.0
Component  Layout
Header  lwrender.h

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;
The global function returns a pointer to an LWItemInfo.
   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,
      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
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
The keyframed position before parenting. Equivalently, if the item is parented, this is its position relative to its parent.
The keyframed position in world coordinates (after parenting).
The keyframed rotation, in radians (relative to its parent's rotation).
The keyframed scale factors (relative to the parent's scale).
The item's pivot point position and rotation, in its own coordinates. The pivot point is the origin for the item's rotations.
+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.
+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
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

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:

itemflags = flags( item )
Returns certain item settings as a set of bit flags:

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:

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:
Initialize with the values from the first keyframe for each IK controlled channel.
Initialize with the values from the most recent keyframe.
Initialize with the current channel values.
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:
No soft IK applied.
Exponential falloff soft IK applied.
Linear falloff soft IK applied.
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:
The min and max values are given as a fraction of the straight-line distance between chain root and goal.
The min and max values are given as a fraction of the distance along the chain from root to goal.
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:

blend = sameItemBlend( item, param_type, time )
Returns the item's "Same As Item" blending factor at a given time. The parameter is one of:

method = sameItemBlendMethod( item, param_type )
Returns the item's "Same As Item" blending methoditem for the given parameter. The parameter is one of:
The returned method is one of:

flags = sameItemFlags( item, param_type )
Returns any flags for the item's "Same As Item" setting. The parameter is one of:

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


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.


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;

   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 );
The vectors returned by the param function can be used to transform points between item and world coordinates. In the following fragments, p is the position of a point in item coordinates and q is the same point's position in world coordinates:
   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 );
To convert from item to world coordinates, subtract the pivot position (to move the rotation origin to the world origin), multiply by the matrix formed from the direction vectors, and offset the result by the world position of the item.
   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 ];
To transform from world to item coordinates, just apply the same procedure in reverse, using the inverse direction vectors.
   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 ];