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: LXu_LOCATOR, etc. defines
 #define LXu_LOCATOR     "50DCCB9D-9856-4A33-9BDA-DAF3A71BBD2D"
 #define LXa_LOCATOR     "locator"

These declarations are used to test light shadow types.

(2) SDK: LXiICVAL_LIGHT_SHADTYPE_NONE, etc. defines

Transforms applied to locators have a fixed set of types.

(3) SDK: Types
 typedef unsigned        LXtTransformType;
 
 #define LXiXFRM_SCALE           0
 #define LXiXFRM_ROTATION        1
 #define LXiXFRM_POSITION        2
 #define LXiXFRM_PIVOT           3
 #define LXiXFRM_PIVOT_C         4
 #define LXiXFRM_SHEAR           5
 #define LXiXFRM_PIVOT_ROT       6
 #define LXiXFRM_PIVOT_ROT_C     7

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.

(4) SDK: Locator::Visible
         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.

(5) SDK: Locator::WorldTransform
         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.

(6) SDK: Locator::GetTransformItem
         LXxMETHOD(  LxResult,
 GetTransformItem) (
         LXtObjectID              self,
         LXtTransformType         type,
         void                   **ppvObj);

(7) SDK: CLxUser_Locator::GetXfrmItem 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.

(8) SDK: Locator::AddTransformItem
         LXxMETHOD(  LxResult,
 AddTransformItem) (
         LXtObjectID              self,
         LXtTransformType         type,
         void                   **ppvObj,
         unsigned                *index);

(9) SDK: CLxUser_Locator::AddXfrmItem 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.

(10) SDK: Locator::SetTransformVector
         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.

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

(12) SDK: CLxUser_Locator::AddPreXfrmItem 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.

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

(14) SDK: CLxUser_Locator::AddPostXfrmItem 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

(15) SDK: Locator::SetTarget
         LXxMETHOD(  LxResult,
 SetTarget) (
         LXtObjectID              self,
         LXtObjectID              target,
         void                    **ppvObj);

Transforms

Inserts the transform BEFORE the very first transform.

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

Inserts the transform AFTER the very last transform.

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

(18) SDK: LXiLOCATOR_LOCAL, etc. defines
 #define LXiLOCATOR_LOCAL        0
 #define LXiLOCATOR_WORLD        1

(19) SDK: Locator::SetPosition
         LXxMETHOD(  LxResult,
 SetPosition) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtObjectID              chanWrite,
         const LXtVector          pos,
         unsigned                 type,
         unsigned                 comp);

(20) SDK: Locator::SetRotation
         LXxMETHOD(  LxResult,
 SetRotation) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtObjectID              chanWrite,
         const LXtMatrix          m3,
         unsigned                 type,
         unsigned                 comp);

(21) SDK: Locator::SetScale
         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.

(22) SDK: Locator::ExtractLocalPosition
         LXxMETHOD(  LxResult,
 ExtractLocalPosition) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtVector                pos);

As above above but for the local rotation matrix.

(23) SDK: Locator::ExtractLocalRotation
         LXxMETHOD(  LxResult,
 ExtractLocalRotation) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix                m3);

(24) SDK: Locator::ZeroTransform
         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.

(25) SDK: Locator::WorldTransform4
         LXxMETHOD(  LxResult,
 WorldTransform4) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix4               xfrm4);

This gets the invert transformation matrix and offset

(26) SDK: Locator::WorldInvertTransform
         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.

(27) SDK: Locator::LocalTransform
         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.

(28) SDK: Locator::LocalTransform4
         LXxMETHOD(  LxResult,
 LocalTransform4) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix4               xfrm4);

Empty Locator Python user class.

(29) PY: empty Locator user class
 pass