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;
   iteminfo = global( LWITEMINFO_GLOBAL, GFUSE_TRANSIENT );

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,
                                     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);
      void          (*stiffness)   (LWItemID, LWItemParam, LWDVector);
   } 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.

This function isn't thread-safe, so it shouldn't be called from the evaluate callbacks of classes that can be threaded (e.g. shaders, pixel filters, volumetrics).

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.

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 rotation. 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.

LWMOTCTL_KEYFRAMES
LWMOTCTL_TARGETING
LWMOTCTL_ALIGN_TO_PATH
LWMOTCTL_IK

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

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 )

Returns the item's IK goal strength.

stiffness( item, param_type, vector )

Fills vector with the item's joint stiffness settings in heading, pitch and bank. Use LWIP_ROTATION as the param_type.

History

LightWave 7.0 added the flags, lookAhead, goalStrength and stiffness functions, 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.

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 );
      }
   }

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 ];