locator (lx_locator.hpp)

From The Foundry MODO SDK wiki
Jump to: navigation, search
There are security restrictions on this page


Locator SDK

A locator is a basic item type that has a transform.

(1) SDK: Declarations
 #define LXu_LOCATOR     "50DCCB9D-9856-4A33-9BDA-DAF3A71BBD2D"
 #define LXa_LOCATOR     "locator"

These declarations are used to test light shadow types.

(2) SDK: Declarations

Transforms

Locator-type item visibility is controlled both locally and by parent items. If an item evaluates as visible, the return value is LXe_TRUE, otherwise the return value is LXe_FALSE.

(3) SDK: ILxLocator interface
         LXxMETHOD( LxResult,
 Visible) (
         LXtObjectID              self,
         LXtObjectID              chanRead);

Locator-type items have support methods for getting and setting their transforms. This gets the evaluated world transform (position offset and 3x3 matrix) for a given item at a given time.

(4) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 WorldTransform) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix                xfrm,
         LXtVector                pos);

This method returns the transform item of the given type for the locator item. If no item exists this method returns LXe_NOTFOUND. Otherwise the item is returned.

(5) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 GetTransformItem) (
         LXtObjectID              self,
         LXtTransformType         type,
         void                   **ppvObj);

(6) User Class: Locator method
         bool
 GetXfrmItem (
         LXtTransformType         type,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_OK (GetTransformItem (type, &obj)))
                 return item.take (obj);
 
         item.clear ();
         return false;
 }

This method adds a given transform or returns the existing one. It can optionally return the index of the first value channel of the xfrm as well.

(7) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 AddTransformItem) (
         LXtObjectID              self,
         LXtTransformType         type,
         void                   **ppvObj,
         unsigned                *index);

(8) User Class: Locator method
         bool
 AddXfrmItem (
         LXtTransformType         type,
         CLxLoc_Item             &item,
         unsigned                *index = 0)
 {
         LXtObjectID              obj;
 
         if (LXx_OK (AddTransformItem (type, &obj, index)))
                 return item.take (obj);
 
         item.clear ();
         return false;
 }

This method sets the value of one of the transforms for the given locator item. The chanWrite object can be an object presenting an ILxChannelWrite interface for one of the scene's actions. If this is null the vector is written as constant channel values in some appropriate action.

(9) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 SetTransformVector) (
         LXtObjectID              self,
         LXtObjectID              chanWrite,
         LXtTransformType         type,
         const LXtVector          value);

This method creates a new transform of the requested type and inserts into the transform chain before the standard transform. It returns the new object, optionally the first value channel of the xfrm as well. If 'value' is not NULL, it sets the value of one of the transforms. The chanWrite object can be an object presenting an ILxChannelWrite interface for one of the scene's actions. If this is null the vector is written as constant channel values in some appropriate action.

(10) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 AddPreTransformItem) (
         LXtObjectID              self,
         LXtObjectID              chanWrite,
         LXtTransformType         type,
         const LXtVector          value,
         void                   **ppvObj,
         unsigned                *index);

(11) User Class: Locator method
         bool
 AddPreXfrmItem (
         ILxUnknownID             chanWrite,
         LXtTransformType         type,
         const LXtVector          value,
         CLxLoc_Item             &item,
         unsigned                *index = 0)
 {
         LXtObjectID              obj;
 
         if (LXx_OK (AddPreTransformItem (chanWrite, type, value, &obj, index)))
                 return item.take (obj);
 
         item.clear ();
         return false;
 }

This is like the above, but it inserts the transform AFTER the standard transforms.

(12) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 AddPostTransformItem) (
         LXtObjectID              self,
         LXtObjectID              chanWrite,
         LXtTransformType         type,
         const LXtVector          value,
         void                   **ppvObj,
         unsigned                *index);

(13) User Class: Locator method
         bool
 AddPostXfrmItem (
         ILxUnknownID             chanWrite,
         LXtTransformType         type,
         const LXtVector          value,
         CLxLoc_Item             &item,
         unsigned                *index = 0)
 {
         LXtObjectID              obj;
 
         if (LXx_OK (AddPostTransformItem (chanWrite, type, value, &obj, index)))
                 return item.take (obj);
 
         item.clear ();
         return false;
 }

Target

(14) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 SetTarget) (
         LXtObjectID              self,
         LXtObjectID              target,
         void                    **ppvObj);

Transforms

Inserts the transform BEFORE the very first transform.

(15) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 PrependTransformItem) (
         LXtObjectID              self,
         LXtObjectID              chanWrite,
         LXtTransformType         type,
         const LXtVector          value,
         void                   **ppvObj,
         unsigned                *index);

Inserts the transform AFTER the very last transform.

(16) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 AppendTransformItem) (
         LXtObjectID              self,
         LXtObjectID              chanWrite,
         LXtTransformType         type,
         const LXtVector          value,
         void                   **ppvObj,
         unsigned                *index);

(17) SDK: Declarations
 #define LXiLOCATOR_LOCAL        0
 #define LXiLOCATOR_WORLD        1

(18) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 SetPosition) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtObjectID              chanWrite,
         const LXtVector          pos,
         unsigned                 type,
         unsigned                 comp);

(19) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 SetRotation) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtObjectID              chanWrite,
         const LXtMatrix          m3,
         unsigned                 type,
         unsigned                 comp);

(20) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 SetScale) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtObjectID              chanWrite,
         const LXtMatrix4         m4,
         unsigned                 type,
         unsigned                 comp);

Items may have several position transforms (zeroed, pivot etc) making it difficult to set a local position directly. This function takes the desired local position values for an item and updates them to the values that need to be set on the standard position transform item to give the desired position after taking all other transforms into account.

(21) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 ExtractLocalPosition) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtVector                pos);

As above above but for the local rotation matrix.

(22) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 ExtractLocalRotation) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix                m3);

(23) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 ZeroTransform) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtObjectID              chanWrite,
         LXtTransformType         type);

This is similar to WorldTransform, except the evaluated world transform is returned in a full 4x4 matrix.

(24) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 WorldTransform4) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix4               xfrm4);

This gets the invert transformation matrix and offset

(25) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 WorldInvertTransform) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix                xfrm,
         LXtVector                pos);

This gets the evaluated local transform (position offset and 3x3 matrix - relative to its parent) for a given item at a given time.

(26) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 LocalTransform) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix                xfrm,
         LXtVector                pos);

This is similar to LocalTransform, except the evaluated local transform is returned in a full 4x4 matrix.

(27) SDK: ILxLocator interface
         LXxMETHOD(  LxResult,
 LocalTransform4) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix4               xfrm4);

Empty Locator Python user class.

(28) PY: Locator method
 pass