Item (lx-item.hpp)

There are security restrictions on this page

1 Item SDK
2 ILxSceneService
3 ILxScene
4 Items
5 Scene Graphs
6 Specific Scene Graph Interfaces
- 6.1 Item Graph Interface
- 6.2 Channel Graph Interface
7 More Methods (501)
- 7.1 501
- 7.2 801
8 903
- 8.1 (217) SDK: Scene::GeneralCollection
- 8.2 (218) SDK: Scene::GeneralCollectionRaw
9 Asset Management
10 11.0

Item SDK

Scenes contain items, actions, and graphs. Items are the fundamental scene data element, the basic unit of user interaction. Each item represents some data object in the scene -- all things which can exist in 3D or have persistent state. Item have channels, which are named attributes. Actions hold channel values that can vary over time. Graphs are named relationships between items or channels in the scene.

The item SDK is a set of interfaces for clients to query and alter items and the scenes they are in.

ILxSceneService

The scene service provides high-level scene and item system access. These methods are provided as general services that could be useful on any item.

(1) SDK: LXa_SCENESERVICE, etc. defines

 #define LXa_SCENESERVICE        "sceneservice3"
 #define LXu_SCENESERVICE        "50190141-0059-48FE-B27D-6C98E1348D7B"

Get the script query object for the service.

(2) SDK: SceneService::ScriptQuery

         LXxMETHOD(  LxResult,
 ScriptQuery) (
         LXtObjectID              self,
         void                   **ppvObj);

The root scene acts as a container for all loaded scenes. It is not visible to the user. Newly added scenes are created as sub-scenes of the root. This method returns the global root scene, and can be used to walk all of the sub-scenes.

(3) SDK: SceneService::Root

         LXxMETHOD(  LxResult,
 Root) (
         LXtObjectID              self,
         void                   **ppvObj);

Item Types

Item types are given by integers and also by unique names. -1 is normally used to indicate all types, and 0 indicates no valid type, however any item type ID zero or less is invalid.

(4) SDK: Types

 typedef int              LXtItemType;
 #define LXiTYPE_ANY      -1
 #define LXiTYPE_NONE      0

This returns the total number of item types.

(5) SDK: SceneService::ItemTypeCount

         LXxMETHOD( unsigned,
 ItemTypeCount) (
         LXtObjectID              self);

This returns each item type by index into the global list.

(6) SDK: SceneService::ItemTypeByIndex

         LXxMETHOD( LxResult,
 ItemTypeByIndex) (
         LXtObjectID              self,
         unsigned                 index,
         LXtItemType             *type);

In python the entire list can be read at once.

(7) PY: Service.Scene.ItemTypeList method

 def ItemTypeList(self):
     """list of types = ItemTypeList()
     """
     return [ self.ItemTypeByIndex(i) for i in range(self.ItemTypeCount()) ]

Given a type name, this returns the type ID.

(8) SDK: SceneService::ItemTypeLookup

         LXxMETHOD( LxResult,
 ItemTypeLookup) (
         LXtObjectID              self,
         const char              *name,
         LXtItemType             *type);

A user method provides easier syntax.

(9) SDK: CLxUser_SceneService::ItemType method

         LXtItemType
 ItemType (
         const char              *name)
 {
         LXtItemType              type;
 
         if (LXx_FAIL (ItemTypeLookup (name, &type)))
                 return LXiTYPE_NONE;
 
         return type;
 }

This method returns the internal name of a type given it's type ID.

(10) SDK: SceneService::ItemTypeName

         LXxMETHOD( LxResult,
 ItemTypeName) (
         LXtObjectID              self,
         LXtItemType              type,
         const char             **name);

Type codes can be tested for relationship. This returns LXe_TRUE if 'what' is the same type as, or a sub-type of, 'isA.'

(11) SDK: SceneService::ItemTypeTest

         LXxMETHOD( LxResult,
 ItemTypeTest) (
         LXtObjectID              self,
         LXtItemType              what,
         LXtItemType              isA);

It is also possible to look up the super-type code from a type code. This returns LXe_NOTFOUND if the item type has no super-type.

(12) SDK: SceneService::ItemTypeSuper

         LXxMETHOD( LxResult,
 ItemTypeSuper) (
         LXtObjectID              self,
         LXtItemType              type,
         LXtItemType             *super);

This method returns the number of channels shared by two items. This is the number of channels defined by their common ancestor type, if any. If they do not share any channels, this returns LXe_NOTFOUND;

(13) SDK: SceneService::ItemTypeCommonChannels

         LXxMETHOD( LxResult,
 ItemTypeCommonChannels) (
         LXtObjectID              self,
         LXtObjectID              item1,
         LXtObjectID              item2,
         unsigned                *count);

This returns the number of subtypes for a given item type.

(14) SDK: SceneService::ItemSubTypeCount

         LXxMETHOD( LxResult,
 ItemSubTypeCount) (
         LXtObjectID              self,
         LXtItemType              type,
         unsigned int            *count);

This return the the name of each subtype by index.

(15) SDK: SceneService::ItemSubTypeByIndex

         LXxMETHOD( LxResult,
 ItemSubTypeByIndex) (
         LXtObjectID              self,
         LXtItemType              type,
         unsigned int             index,
         const char             **subtype);

In python all the subtype names can be read as a list.

(16) PY: Service.Scene.ItemSubTypeList method

 def ItemSubTypeList(self, type):
     """list of sub-types = ItemSubTypeList(type)
     """
     return [ self.ItemSubTypeByIndex(type, i) for i in range(self.ItemSubTypeCount(type)) ]

Utilities

This function returns the number of components in the given one of the LXiCHANMODE_* defines.

(17) SDK: SceneService::ChannelVectorSize

         LXxMETHOD( LxResult,
 ChannelVectorSize) (
         LXtObjectID              self,
         unsigned int             mode,
         unsigned int            *size);

Useful for UIs and configs, this function returns the text hints array for the vector modes.

(18) SDK: SceneService::ChannelVectorTextHints

         LXxMETHOD( LxResult,
 ChannelVectorTextHints) (
         LXtObjectID              self,
         const LXtTextValueHint **hints);

Scenes

Create an empty scene. This is parented to the root scene, and is truely empty not a default new scene.

(19) SDK: SceneService::CreateScene

         LXxMETHOD(  LxResult,
 CreateScene) (
         LXtObjectID              self,
         void                   **ppvObj);

(20) SDK: CLxUser_SceneService::NewScene method

         bool
 NewScene (
         CLxLoc_Scene            &scene)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (CreateScene (&obj)))
                 return false;
 
         return scene.take (obj);
 }

Destroy a scene. Effectively the same as closing it. All references to the contents of the scene must have been released.

(21) SDK: SceneService::DestroyScene

         LXxMETHOD(  LxResult,
 DestroyScene) (
         LXtObjectID              self,
         LXtObjectID              scene);

This method adds a sub-scene to another scene. The refItems flag can be set to have all items in the sub-cinema referenced in the parent.

(22) SDK: SceneService::SubSceneAdd

         LXxMETHOD(  LxResult,
 SubSceneAdd) (
         LXtObjectID              self,
         LXtObjectID              scene,
         LXtObjectID              other,
         unsigned                 refItems);

This loads a scene as a sub-scene. If the parent scene is null this will be a root scene.

(23) SDK: SceneService::SubSceneLoad

         LXxMETHOD(  LxResult,
 SubSceneLoad) (
         LXtObjectID              self,
         LXtObjectID              scene,
         const char              *path,
         LXtObjectID              monitor,
         void                   **ppvObj);

Mesh Instances

Support for finding source items for mesh instance items and the instances of mesh items takes the following form:

Given an ILxItem of type LXi_CIT_INSTANCE, this function returns the LXi_CIT_MESH type source item.

(24) SDK: SceneService::GetMeshInstSourceItem

         LXxMETHOD(  LxResult,
 GetMeshInstSourceItem) (
         LXtObjectID              self,
         LXtObjectID              inst,
         void                   **ppvObj);

This method returns the number of mesh instances using the given mesh item as source.

(25) SDK: SceneService::MeshInstanceCount

         LXxMETHOD(  int,
 MeshInstanceCount) (
         LXtObjectID              self,
         LXtObjectID              mesh);

This method returns the mesh instance using the given mesh item as source by index.

(26) SDK: SceneService::MeshInstanceByIndex

         LXxMETHOD(  LxResult,
 MeshInstanceByIndex) (
         LXtObjectID              self,
         LXtObjectID              mesh,
         int                      index,
         void                   **ppvObj);

Images

Images are loaded with the following method. The path is absolute and the object returned is the new clip item. The function can return LXe_FILE_REMAP if the path needed to be altered to find an image.

(27) SDK: SceneService::LoadImage

         LXxMETHOD( LxResult,
 LoadImage) (
         LXtObjectID              self,
         LXtObjectID              scene,
         const char              *path,
         LXtObjectID              monitor,
         void                   **ppvObj);

Replicators

The GetReplicatorEnumerator interface allows you to get an enumerator for a replicator item to enumerate the positions & orientations of replicants generated by its particle source.

(28) SDK: SceneService::GetReplicatorEnumerator

         LXxMETHOD( LxResult,
 GetReplicatorEnumerator) (
         LXtObjectID              self,
         LXtObjectID              replicatorItem,
         void                   **ppvObj);

(29) SDK: CLxUser_SceneService::NewReplicatorEnumerator method

         bool
 NewReplicatorEnumerator (
         ILxUnknownID                     pItem,
         CLxLoc_ReplicatorEnumerator     &replicatorEnum)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (GetReplicatorEnumerator (pItem, &obj)))
                 return false;
 
         return replicatorEnum.take (obj);
 }

Item Type Tags

Read the value of a tag for an item type, if any. If super is true the supertypes will also be checked.

(30) SDK: SceneService::ItemTypeGetTag

         LXxMETHOD( LxResult,
 ItemTypeGetTag) (
         LXtObjectID              self,
         LXtItemType              type,
         const char              *tag,
         unsigned                 super,
         const char             **value);

Type Support

This is a simple utility class that provides item type IDs. First time it's requested it's cached.

(31) User Class: additional

 class CLxItemType {
     public:
         const char              *type_name;
         LXtItemType              cached_code;
 
         CLxItemType (
                 const char      *typeName = 0)
         {
                 set (typeName);
         }
 
                 void
         set (
                 const char      *typeName)
         {
                 type_name   = typeName;
                 cached_code = LXiTYPE_NONE;
         }
 
                 LXtItemType
         Type ()
         {
                 if (cached_code != LXiTYPE_NONE || !type_name)
                         return cached_code;
 
                 CLxUser_SceneService srv;
 
                 cached_code = srv.ItemType (type_name);
                 return cached_code;
         }
 
                 operator
         LXtItemType ()
         {
                 return Type ();
         }
 };

Item Collection

It is often useful to collect associated items in a particular graph, and populate an ILxItemCollection. This function will enumerate over all items of the provided type in the ILxItemCollection, and all items to the collection that are connected to the item in the named graph. The fwd argument specifies the direction to walk the graph.

(32) SDK: SceneService::ItemGraphCollection

         LXxMETHOD( LxResult,
 ItemGraphCollection) (
         LXtObjectID              self,
         LXtObjectID              collection,
         LXtItemType              type,
         const char              *graph,
         int                      fwd);

Scene Save

Saving scenes is done through common saver servers. Servers with the LXa_SCENE output class will be passed a scene object for vertification and saving. It's also possible to save subsets of scenes which contain only specific items. Savers that support this are marked with this server tag. The value of the tag is a string composed from space-delimited tokens:

ALL	The saver supports essentially everything, overrides other settings.
SURFACES	The saver will save surface-type items, like meshes, static meshes, or procedural surfaces.
MATERIALS	The saver will also save materials for those surfaces.
RENDER	The saver will save other items related to rendering, like lights and cameras.
ANIMATION	The saver will save animated channels as well as constant values.

(33) SDK: LXsSAV_SCENE_SUBSET, etc. defines

 #define LXsSAV_SCENE_SUBSET     "scene.subset"
 
 #define LXsSUBSET_ALL           "*"
 #define LXsSUBSET_SURFACES      "surf"
 #define LXsSUBSET_MATERIALS     "matr"
 #define LXsSUBSET_RENDER        "rend"
 #define LXsSUBSET_ANIMATION     "anim"

Servers with this tag may get passed a scene for full scene saving, or they may be passed a SceneSubset object. This is a very simple object that just contains a scene and an item collection

(34) SDK: LXu_SCENESUBSET define

 #define LXu_SCENESUBSET         "BC46E557-A612-4820-85F8-122D0FF5521C"

(35) SDK: SceneSubset::GetScene

         LXxMETHOD( LxResult,
 GetScene) (
         LXtObjectID              self,
         void                   **ppvObj);

(36) SDK: SceneSubset::GetCollection

         LXxMETHOD( LxResult,
 GetCollection) (
         LXtObjectID              self,
         void                   **ppvObj);

(37) SDK: empty SceneSubset User Class

(38) PY: empty SceneSubset user class

 pass

ILxScene

Scenes can be queried for items, graphs, and channel values. The object is polymorphic with StringTags (interface) for getting and setting scene tags.

(39) SDK: LXu_SCENE, etc. defines

 #define LXu_SCENE               "FF870F44-FED9-4dbc-95BA-2972A43FC936"
 #define LXa_SCENE               "scene2"

Localized scene object can be intialized from an item.

(40) SDK: CLxUser_Scene::from method

         bool
 from (
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         clear ();
         if (LXx_FAIL (item.Context (&obj)))
                 return false;
 
         return take (obj);
 }

Or initialized in the constructor for the wrapper.

(41) SDK: CLxUser_Scene::CLxUser_Scene method

 CLxUser_Scene (
         CLxLoc_Item             &item)
 {
         CLxUser_Scene ();
         from (item);
 }

Likewise in python.

(42) PY: Scene.from_item method

 def from_item(self, item):
     """Set the scene wrapper from an item: scene.from_item(item)
     """
     self.set(item.Context())

Basic Properties

Scenes can be set to represent a particular item type. This is done either on creation or during loading and cannot be subsequently changed. For example, a scene that represents a 3d object will have an item type of "mesh", a scene storing an image file will have an item type of "clip" etc. This function returns the root item type that the scene represents or zero if there is no specific type.

(43) SDK: Scene::ItemRootType

         LXxMETHOD(  LXtItemType,
 ItemRootType) (
         LXtObjectID              self);

This returns the filename of the scene. The path is system-specific. This will return LXe_FALSE if the scene is unnamed, LXe_OK otherwise.

(44) SDK: Scene::Filename

         LXxMETHOD(  LxResult,
 Filename) (
         LXtObjectID              self,
         const char             **filename);

This method returns a human readable version of the filename suitable for display in the UI. The SHORT flag removes the file type extension, and STAR adds an asterisk for changed cinemas.

(45) SDK: Scene::FriendlyFilename

         LXxMETHOD(  LxResult,
 FriendlyFilename) (
         LXtObjectID              self,
         unsigned                 flags,
         const char             **filename);

(46) SDK: LXfSCENENAME_STAR, etc. defines

 #define LXfSCENENAME_STAR        1
 #define LXfSCENENAME_SHORT       2

This returns the file format of the scene, which determines how the scene will be saved.

(47) SDK: Scene::FileFormat

         LXxMETHOD(  LxResult,
 FileFormat) (
         LXtObjectID              self,
         const char             **format);

Pass in 1 to indicate that the scene has been modified, and 0 to reset the state back to unchanged.

(48) SDK: Scene::Changed

         LXxMETHOD(  LxResult,
 Changed) (
         LXtObjectID              self,
         unsigned                 changed);

This returns LXe_TRUE if the scene has changed, and LXe_FALSE if it has not. It can also provide the number of changes since the last reset.

(49) SDK: Scene::HasChanged

         LXxMETHOD(  LxResult,
 HasChanged) (
         LXtObjectID              self,
         unsigned int            *numChanges);

Parenting, Enumeration and Sub-Scenes

This method returns the parent ILxScene, or LXe_NOTFOUND if this is the root scene, Thus this method can also be used to test if this scene is the root scene.

(50) SDK: Scene::Parent

         LXxMETHOD(  LxResult,
 Parent) (
         LXtObjectID              self,
         void                   **ppvObj);

The the scene's sub-scenes can be enumerated. The type argument can be used to filter the list by root type, or can be -1 to list all scenes. This method returns the number of sub-scenes.

(51) SDK: Scene::SubSceneCount

         LXxMETHOD(  LxResult,
 SubSceneCount) (
         LXtObjectID              self,
         LXtItemType              type,
         unsigned int            *count);

This method returns the sub-scene by index.

(52) SDK: Scene::SubSceneByIndex

         LXxMETHOD(  LxResult,
 SubSceneByIndex) (
         LXtObjectID              self,
         LXtItemType              type,
         unsigned int             index,
         void                   **ppvObj);

Scene target flags ( LXf_SCENETARG_ ) set by the loader can be read with this method.

(53) SDK: Scene::LoadFlags

         LXxMETHOD(  unsigned,
 LoadFlags) (
         LXtObjectID              self);

Actions

This function can allocate a channel I/O object presenting ILxChannelRead and ILxChannelWrite interfaces. The name indicates the name of the action to use, and a null name will evaluate final channels. The time specifies when values will be read, set or evaluated.

(54) SDK: Scene::Channels

         LXxMETHOD(  LxResult,
 Channels) (
         LXtObjectID              self,
         const char              *name,
         double                   time,
         void                   **ppvObj);

Get evaluated channels for read at the given time.

(55) SDK: CLxUser_Scene::GetChannels method

         bool
 GetChannels (
         CLxLoc_ChannelRead      &chan,
         double                   time) const
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (Channels (0, time, &obj))) return false;
         return chan.take (obj);
 }

Get channels from a named action.

(56) SDK: CLxUser_Scene::GetChannels method

         bool
 GetChannels (
         CLxLoc_ChannelRead      &chan,
         const char              *name,
         double                   time = 0.0) const
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (Channels (name, time, &obj))) return false;
         return chan.take (obj);
 }

Get evaluated channels in setup mode.

(57) SDK: CLxUser_Scene::GetSetupChannels method

         bool
 GetSetupChannels (
         CLxLoc_ChannelRead      &chan) const
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (SetupChannels (&obj))) {
                 return false;
         }
         else {
                 return chan.take (obj);
         }
 }

Get an interface to write channels to a named action.

(58) SDK: CLxUser_Scene::SetChannels method

         bool
 SetChannels (
         CLxLoc_ChannelWrite     &chan,
         const char              *name,
         double                   time = 0.0)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (Channels (name, time, &obj))) return false;
         return chan.take (obj);
 }

Items

The most notable attribute of scenes is that they contain items. The item list can be enumerated with these methods. Items themselves are represented as ILxItemIDs. This method gets the number of items of a given type.

(59) SDK: Scene::ItemCount

         LXxMETHOD(  LxResult,
 ItemCount) (
         LXtObjectID              self,
         LXtItemType              type,
         unsigned int            *count);

This returns an item of the given type by index.

(60) SDK: Scene::ItemByIndex

         LXxMETHOD(  LxResult,
 ItemByIndex) (
         LXtObjectID              self,
         LXtItemType              type,
         unsigned int             index,
         void                   **ppvObj);

Get the item count.

(61) SDK: CLxUser_Scene::NItems method

         int
 NItems (
         LXtItemType              type)
 {
         unsigned                 n;
 
         if (LXx_OK (ItemCount (type, &n)))
                 return n;
         else
                 return -1;
 }

Get items by index.

(62) SDK: CLxUser_Scene::GetItem method

         bool
 GetItem (
         LXtItemType              type,
         unsigned                 index,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemByIndex (type, index, &obj)))
                 return false;
 
         return item.take (obj);
 }

In python the list of all items of a given type can be read.

(63) PY: Scene.ItemList method

 def ItemList(self, type):
     """list of items = ItemList(type)
     """
     return [ self.ItemByIndex(type,i) for i in range(self.ItemCount(type)) ]

Items can be looked up by their ID string or by unique name.

(64) SDK: Scene::ItemLookup

         LXxMETHOD(  LxResult,
 ItemLookup) (
         LXtObjectID              self,
         const char              *id,
         void                   **ppvObj);

Get an item from the scene by name.

(65) SDK: CLxUser_Scene::GetItem method

         bool
 GetItem (
         const char              *name,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemLookup (name, &obj)))
                 return false;
 
         return item.take (obj);
 }

These methods allow enumeration of items by multiple types. The 'types' argument is a zero-terminated array of item types. This method get the count.

(66) SDK: Scene::ItemCountByTypes

         LXxMETHOD(  LxResult,
 ItemCountByTypes) (
         LXtObjectID              self,
         const LXtItemType       *types,
         unsigned                *count);

This method gets an item by types by index.

(67) SDK: Scene::ItemByIndexByTypes

         LXxMETHOD(  LxResult,
 ItemByIndexByTypes) (
         LXtObjectID              self,
         const LXtItemType       *types,
         unsigned                 index,
         void                   **ppvObj);

This method gets an item by types by index.

(68) SDK: CLxUser_Scene::GetItem method

         bool
 GetItem (
         LXtItemType             *types,
         unsigned                 index,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemByIndexByTypes (types, index, &obj)))
                 return false;
 
         return item.take (obj);
 }

This method returns LXe_TRUE if an item of a given type exists in the scene and returns it.

(69) SDK: Scene::AnyItemOfType

         LXxMETHOD(  LxResult,
 AnyItemOfType) (
         LXtObjectID              self,
         LXtItemType              type,
         void                   **ppvObj);

This gets a single item of the given type, if any.

(70) SDK: CLxUser_Scene::GetItem method

         bool
 GetItem (
         LXtItemType              type,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (AnyItemOfType (type, &obj)))
                 return false;
 
         return item.take (obj);
 }

This method returns the item in the given scene which is the same as, or a reference to, the given item. If there is no reference, the method will return LXe_NOTFOUND.

(71) SDK: Scene::ItemLocalize

         LXxMETHOD(  LxResult,
 ItemLocalize) (
         LXtObjectID              self,
         LXtObjectID              item,
         void                   **ppvObj);

Creating Items

This method creates a new item of the given type and adds it to the scene.

(72) SDK: Scene::ItemAdd

         LXxMETHOD(  LxResult,
 ItemAdd) (
         LXtObjectID              self,
         LXtItemType              type,
         void                   **ppvObj);

Create a new item by type code.

(73) SDK: CLxUser_Scene::NewItem method

         bool
 NewItem (
         LXtItemType              type,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemAdd (type, &obj)))
                 return false;
 
         return item.take (obj);
 }

Create a new item by type name using a scene service.

(74) SDK: CLxUser_Scene::NewItem method

         bool
 NewItem (
         const char              *typeName,
         CLxLoc_SceneService     &svc,
         CLxLoc_Item             &item)
 {
         LXtItemType              type;
 
         if (LXx_FAIL (svc.ItemTypeLookup (typeName, &type)))
                 return false;
 
         return NewItem (type, item);
 }

Create a new item by type name without using a scene service. (The service is allocated by the method.)

(75) SDK: CLxUser_Scene::NewItem method

         bool
 NewItem (
         const char              *typeName,
         CLxLoc_Item             &item)
 {
         CLxLoc_SceneService      svc;
 
         return NewItem (typeName, svc, item);
 }

This method creates a duplicate of an existing item. Also known as an instance.

(76) SDK: Scene::ItemInstance

         LXxMETHOD(  LxResult,
 ItemInstance) (
         LXtObjectID              self,
         LXtObjectID              item,
         void                   **ppvObj);

This creates a new reference top an existing item in the scene. If the reference already exists, it is returned isntead.

(77) SDK: Scene::ItemAddReference

         LXxMETHOD(  LxResult,
 ItemAddReference) (
         LXtObjectID              self,
         LXtObjectID              item,
         void                   **ppvObj);

Items

Items represent the images, meshes, cameras, lights and so on in the scene. Items also have an ILxAttributes interface which is a second method for acessing their channel list. Values read are the defaults for the channels, and setting values is disabled. Items aslo have a StringTag (interface) for getting and setting their tags.

(78) SDK: LXa_ITEM, etc. defines

 #define LXa_ITEM                "item"
 #define LXu_ITEM                "7FF2D6D5-5E28-4650-93ED-89FF257F9629"

Basic Properties

This returns the item's type. Returns LXiTYPE_NONE if the item has been destroyed.

(79) SDK: Item::Type

         LXxMETHOD(  LXtItemType,
 Type) (
         LXtObjectID              self);

This returns true if an item matches or inherits from a given type.

(80) SDK: Item::TestType

         LXxMETHOD(  LxResult,
 TestType) (
         LXtObjectID              self,
         LXtItemType              type);

This returns true if an item matches or inherits from a list of types.

(81) SDK: Item::TestTypes

         LXxMETHOD(  LxResult,
 TestTypes) (
         LXtObjectID              self,
         const LXtItemType       *types);

This returns true if an item matches or inherits from a given type.

(82) SDK: CLxUser_Item::IsA method

         bool
 IsA (
         LXtItemType              type)
 {
         return (TestType (type) == LXe_OK);
 }

This returns true if an item matches or inherits from a list of types.

(83) SDK: CLxUser_Item::IsA method

         bool
 IsA (
         LXtItemType             *types)
 {
         return (TestTypes (types) == LXe_OK);
 }

This python method returns true if an item matches or inherits from a given type. The type can be passed as a type code or string.

(84) PY: Item.IsA method

 def IsA(self, type):
     if isinstance(type, str):
         type = lx.service.Scene().ItemTypeLookup(type)
 
     return self.TestType(type)

This returns the unique identifier string of the item. The pointer value itself can also be used as a unique identifier (since that's rather hard to do with COM interfaces) since it will never change once item creation or loading is complete.

(85) SDK: Item::Ident

         LXxMETHOD(  LxResult,
 Ident) (
         LXtObjectID              self,
         const char             **ident);

This method returns the ident pointer directly.

(86) SDK: CLxUser_Item::IdentPtr method

         const char *
 IdentPtr () const
 {
         const char              *id;
 
         Ident (&id);
         return id;
 }

Get the item's ident as a C++ string.

(87) SDK: CLxUser_Item::GetIdentity method

         std::string
 GetIdentity ()
 {
         std::string      identity;
         const char      *ident;
 
         if (LXx_OK (Ident (&ident))) {
                 identity = std::string(ident);
         }
 
         return identity;
 }

Given the caveat that it might change during loading, the item ident can also be used to provide operator overloads allowing items to be sorted (less-than is the standard operator used for std::map searches, for example).

(88) SDK: CLxUser_Item::IdentPtr method

         bool
 operator< (
         const CLxUser_Item      &rhs) const
 {
         return IdentPtr () < rhs.IdentPtr ();
 }

This operator allows item wrappers to be tested for equivalence.

(89) SDK: CLxUser_Item::IdentPtr method

         bool
 operator== (
         const CLxUser_Item      &rhs) const
 {
         return IdentPtr () == rhs.IdentPtr ();
 }
 
         bool
 operator!= (
         const CLxUser_Item      &rhs) const
 {
         return IdentPtr () != rhs.IdentPtr ();
 }

The ident string can also be set. This should only be done during loading, where an item already has a well-define ident that already doesn't conflict with any of the others in the same scene.

(90) SDK: Item::SetIdent

         LXxMETHOD(  LxResult,
 SetIdent) (
         LXtObjectID              self,
         const char              *ident);

The item's raw name can be read with this methods. The name read this way does not contain the disambiguating suffix, and it may be null if unset.

(91) SDK: Item::Name

         LXxMETHOD(  LxResult,
 Name) (
         LXtObjectID              self,
         const char             **name);

The raw name can be set with this method. The item's actual name may differ from this string if some other item already has the same name.

(92) SDK: Item::SetName

         LXxMETHOD(  LxResult,
 SetName) (
         LXtObjectID              self,
         const char              *name);

A unique, human-readable name can also be returned. This name is suffixed with a number if necessary, in the user's preferred format. This may also be a synthetic name, generated from the state of the item.

(93) SDK: Item::UniqueName

         LXxMETHOD(  LxResult,
 UniqueName) (
         LXtObjectID              self,
         const char             **name);

Get the unique name as a C++ string.

(94) SDK: CLxUser_Item::GetUniqueName method

         void
 GetUniqueName (
         std::string             &name)
 {
         const char              *sptr;
 
         if (LXx_OK (UniqueName (&sptr)))
                 name = sptr;
 }

The number which is appended to non-unique names to make them unique is persistent. Since it's logically part of the name the user keeps in mind for the item, we would like it to be the same after saving and loading. This method returns the index assigned to the item.

(95) SDK: Item::UniqueIndex

         LXxMETHOD(  LxResult,
 UniqueIndex) (
         LXtObjectID              self,
         unsigned                *index);

This method allows the index to be reset during loading.

(96) SDK: Item::SetUniqueIndex

         LXxMETHOD(  LxResult,
 SetUniqueIndex) (
         LXtObjectID              self,
         unsigned                 index);

Parenting, Children and References

This returns the parent item, or LXe_NOTFOUND if there is no parent because this is a root item.

(97) SDK: Item::Parent

         LXxMETHOD( LxResult,
 Parent) (
         LXtObjectID              self,
         void                    **ppvObj);

Get the parent of this item or return false.

(98) SDK: CLxUser_Item::GetParent method

         bool
 GetParent (
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (Parent (&obj)))
                 return false;
 
         return item.take (obj);
 }

This can be used to set the parent item.

(99) SDK: Item::SetParent

         LXxMETHOD( LxResult,
 SetParent) (
         LXtObjectID              self,
         LXtObjectID              parent);

These methods allow the item hierarchy within the scene to be walked. This returns the number of child items parented to this item.

(100) SDK: Item::SubCount

         LXxMETHOD(  LxResult,
 SubCount) (
         LXtObjectID              self,
         unsigned                *count);

This returns a child item by index.

(101) SDK: Item::SubByIndex

         LXxMETHOD(  LxResult,
 SubByIndex) (
         LXtObjectID              self,
         unsigned                 index,
         void                   **ppvObj);

This returns a child item by index.

(102) SDK: CLxUser_Item::GetSubItem method

         bool
 GetSubItem (
         unsigned                 index,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (SubByIndex (index, &obj)))
                 return false;
 
         return item.take (obj);
 }

This returns the list of all children of this item.

(103) PY: Item.SubList method

 def SubList(self):
     """list of sub-items = SubList()
     """
     return [ self.SubByIndex(i) for i in range(self.SubCount()) ]

This returns the item's ancestor at the root of the scene, failing with LXe_NOTFOUND if this is a root item.

(104) SDK: Item::Root

         LXxMETHOD( LxResult,
 Root) (
         LXtObjectID              self,
         void                    **ppvObj);

Get the root ancestor of this item.

(105) SDK: CLxUser_Item::GetRoot method

         bool
 GetRoot (
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (Root (&obj)))
                 return false;
 
         return item.take (obj);
 }

This method returns the scene that the item belongs to.

(106) SDK: Item::Context

         LXxMETHOD( LxResult,
 Context) (
         LXtObjectID              self,
         void                    **ppvObj);

This method returns the scene that the item belongs to.

(107) SDK: CLxUser_Item::GetContext method

         bool
 GetContext (
         CLxLoc_Scene            &scene)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (Context (&obj)))
                 return false;
 
         return scene.take (obj);
 }

This returns an item from a sub-scene if this item is a reference. If this item is native to its cinema this returns LXe_FAILED.

(108) SDK: Item::Reference

         LXxMETHOD( LxResult,
 Reference) (
         LXtObjectID              self,
         void                   **ppvObj);

This returns LXe_TRUE if the item is referenced by any other item, meaning that it is part of any other hypergraph besides the parenting one.

(109) SDK: Item::IsReferenced

         LXxMETHOD( LxResult,
 IsReferenced) (
         LXtObjectID              self);

The source for an item is another item of the same or similar item type which is used as a source for undefined channels of this item. This is normally set implicitly by CineItemDuplicate(). This method returns the source item.

(110) SDK: Item::Source

         LXxMETHOD( LxResult,
 Source) (
         LXtObjectID              self,
         void                   **ppvObj);

This method sets the source item.

(111) SDK: Item::SetSource

         LXxMETHOD( LxResult,
 SetSource) (
         LXtObjectID              self,
         LXtObjectID              source);

Channels

Items have parameter channels, values which vary by time and other circumstances. The channel is given by an index, and it is possible to iterate through all the channels in an item. This method returns the number of channels, and the indices go from 0 to N-1. Although many channels are common for items of the same type, they may also vary by item.

(112) SDK: Item::ChannelCount

         LXxMETHOD(  LxResult,
 ChannelCount) (
         LXtObjectID              self,
         unsigned                *count);

This can be used to lookup the channel by name, returning its index.

(113) SDK: Item::ChannelLookup

         LXxMETHOD(  LxResult,
 ChannelLookup) (
         LXtObjectID              self,
         const char              *name,
         unsigned                *index);

Get the number of channels on the item.

(114) SDK: CLxUser_Item::NChannels method

         unsigned
 NChannels () const
 {
         unsigned                 count;
 
         if (LXx_OK (ChannelCount (&count)))
                 return count;
 
         return 0;
 }

Get the index of a named channels on the item.

(115) SDK: CLxUser_Item::ChannelIndex method

         int
 ChannelIndex (
         const char              *name) const
 {
         unsigned                 idx;
 
         if (LXx_OK (ChannelLookup (name, &idx)))
                 return idx;
 
         return -1;
 }

This returns the internal name of the channel, suitable for lookup.

(116) SDK: Item::ChannelName

         LXxMETHOD(  LxResult,
 ChannelName) (
         LXtObjectID              self,
         unsigned                 index,
         const char              **name);

This returns a list of the names of all channels on the item.

(117) PY: Item.ChannelList method

 def ChannelList(self):
     """list of channel names = ChannelList()
     """
     return [ self.ChannelName(i) for i in range(self.ChannelCount()) ]

Types, Vectors and Packages

This method returns the channel type given by the following predefined codes. The numeric and gradient types can be keyframed. The custom channel types can be stored in the action or they can be for evaluation only.

(118) SDK: Item::ChannelType

         LXxMETHOD(  LxResult,
 ChannelType) (
         LXtObjectID              self,
         unsigned                 index,
         unsigned                *type);

(119) SDK: LXiCHANTYPE_NONE, etc. defines

 #define LXiCHANTYPE_NONE         0
 #define LXiCHANTYPE_INTEGER      1
 #define LXiCHANTYPE_FLOAT        2
 #define LXiCHANTYPE_GRADIENT     3
 #define LXiCHANTYPE_STORAGE      4
 #define LXiCHANTYPE_EVAL         5

This method returns the vector mode for the channel, one of the LXiCHANMODE_* vector settings chosen as the channel is defined. If this is part of a vector then the component index (usually 0-2) is returned along with LXe_TRUE; otherwise, this returns LXe_FALSE.

(120) SDK: Item::ChannelVectorMode

         LXxMETHOD(  LxResult,
 ChannelVectorMode) (
         LXtObjectID              self,
         unsigned                 index,
         unsigned                *mode,
         unsigned                *components);

(121) SDK: LXiCHANMODE_SCALAR, etc. defines

 #define LXiCHANMODE_SCALAR       0
 #define LXiCHANMODE_XY           1
 #define LXiCHANMODE_XYZ          2
 #define LXiCHANMODE_RGB          3
 #define LXiCHANMODE_RGBA         4
 #define LXiCHANMODE_UV           5
 #define LXiCHANMODE_UVW          6

This method returns the storage type of the channel, which can be valid exo-type name for numeric and stored custom types.

(122) SDK: Item::ChannelStorageType

         LXxMETHOD(  LxResult,
 ChannelStorageType) (
         LXtObjectID              self,
         unsigned                 index,
         const char              **type);

This returns the evaluation type of a channel, which is the type of slot allocated in the eval state vector. This will return the "gradstack" exo-type for gradient channels.

(123) SDK: Item::ChannelEvalType

         LXxMETHOD(  LxResult,
 ChannelEvalType) (
         LXtObjectID              self,
         unsigned                 index,
         const char              **type);

This method returns LXe_TRUE if the channel is a gradient, and returns the input and output types indirectly as well.

(124) SDK: Item::ChannelGradient

         LXxMETHOD(  LxResult,
 ChannelGradient) (
         LXtObjectID              self,
         unsigned                 index,
         const char             **input,
         const char             **output);

This method returns the text hints for integer channels. If there are no hints, this returns LXe_NOTAVAILABLE. This will fail if the channel is not an integer channel.

(125) SDK: Item::ChannelIntHint

         LXxMETHOD(  LxResult,
 ChannelIntHint) (
         LXtObjectID              self,
         unsigned                 index,
         const LXtTextValueHint **hints);

This method will decode a text value using hints into a numeric value.

(126) SDK: CLxUser_Item::ChannelDecode method

         int
 ChannelDecode (
         unsigned                 index,
         const char              *encoded) const
 {
         CLxLoc_ValueService      valueSvc;
         int                      value;
         const LXtTextValueHint  *hints;
 
         if (  LXx_OK (ChannelIntHint (index, &hints))
           &&  LXx_OK (valueSvc.TextHintDecode (encoded, hints, &value)) )
                 return value;
 
         return -1;
 }

The package a channel belongs to can be found with this function. The package name is returned unless this is a user channel.

(127) SDK: Item::ChannelPackage

         LXxMETHOD(  LxResult,
 ChannelPackage) (
         LXtObjectID              self,
         unsigned                 index,
         const char             **package);

Python Channel Values

Reading channel values can be done using the Python user wrapper class. It maintains a channel_read attribute that can be used for reading channels directly on the channel item.

Reset the item so it has no read attribute.

(128) PY: Item.ReadNone method

 def ReadNone(self):
     if hasattr(self, 'channel_read'):
         del self.channel_read

Set the item to read from a named action.

(129) PY: Item.ReadAction method

 def ReadAction(self, name=lx.symbol.s_ACTIONLAYER_EDIT, time=0.0):
     """Read channel values from named action: ReadAction(<name>, <time>)
     """
     self.ReadNone()
     self.channel_read = self.Context().Channels(name, time)

Set the item to read from a setup mode.

(130) PY: Item.ReadSetup method

 def ReadSetup(self):
     """Read evaluted channel values from setup: ReadSetup()
     """
     self.ReadNone()
     self.channel_read = self.Context().SetupChannels()

Set the item to read evaluated channels.

(131) PY: Item.ReadEvaluated method

 def ReadEvaluated(self, time=0.0):
     """Read evaluated channel values: ReadEvaluated(<time>)
     """
     self.ReadAction(None, time)

Once set, channel values can be read using the user method Value() on the channel_read object.

Read the channel value using bracket syntax.

(132) PY: Item.getitem method

 def __getitem__(self, index):
     """Read channel values: val = item[channel]
     """
     return self.ChannelValue(index)

Read the channel value.

(133) PY: Item.ChannelValue method

 def ChannelValue(self, index):
     """Read channel values: val = ChannelValue(channel)
     Channel can be given by name or index.
     """
     if not hasattr(self, 'channel_read'):
         raise RuntimeError('Item wrapper not set for reading')
 
     return self.channel_read.Value(self, index)

Likewise writing sets the channel_write attribute which is then used for writing.

Set the item to write to a named action.

(134) PY: Item.WriteAction method

 def WriteAction(self, name=lx.symbol.s_ACTIONLAYER_EDIT, time=0.0):
     """Write channel values to named action: WriteAction(<name>, <time>)
     """
     if hasattr(self, 'channel_write'):
         del self.channel_write
 
     self.channel_write = ChannelWrite(self.Context().Channels(name, time))

Set the value of a channel using bracket syntax.

(135) PY: Item.setitem method

 def __setitem__(self, index, value):
     """Set channel values: item[channel] = val
     """
     return self.SetChannel(index, value)

Set the value of a channel.

(136) PY: Item.SetChannel method

 def SetChannel(self, index, value, key=False):
     """Set channel values: SetChannel(channel, value, <key>)
     Channel can be given by name or index. Set key to true to make a keyframe.
     """
     if not hasattr(self, 'channel_write'):
         raise RuntimeError('Item wrapper not set for writing')
 
     return self.channel_write.Set(self, index, value, key)

Packages

Packages can be added to items directly. When a package is added, the channels for the package are added to the item, and the local data for the package is allocated and initialized for this item. If this item already has this package, then this function does nothing.

(137) SDK: Item::PackageAdd

         LXxMETHOD(  LxResult,
 PackageAdd) (
         LXtObjectID              self,
         const char              *package);

A item can be tested to see if it already has the given package. This returns LXe_TRUE if the package has been added to this item.

(138) SDK: Item::PackageTest

         LXxMETHOD(  LxResult,
 PackageTest) (
         LXtObjectID              self,
         const char              *package);

This returns the index of the first channel in the package. This index is item specific, as different items may have different combinations of packages applied.

(139) SDK: Item::PackageStartIndex

         LXxMETHOD(  LxResult,
 PackageStartIndex) (
         LXtObjectID              self,
         const char              *package,
         unsigned                *index);

Packages can be removed with this function.

(140) SDK: Item::PackageRemove

         LXxMETHOD(  LxResult,
 PackageRemove) (
         LXtObjectID              self,
         const char              *package);

Adding User Channels

New user channels can be added directly to items using the following method. This returns an ILxAddChannel interface that will are appended new channels after the channels defined for the items type and any packages.

NOTE: This only works during load, adding user channels to items in the process of loading. It doesn't currently support adding channels in any other context.

(141) SDK: Item::ChannelAdd

         LXxMETHOD(  LxResult,
 ChannelAdd) (
         LXtObjectID              self,
         void                   **ppvObj);

Item Tags

Look up an item's tag value by type code.

(142) SDK: Item::GetTag

         LXxMETHOD(  const char *,
 GetTag) (
         LXtObjectID              self,
         LXtID4                   type);

Set the tag string associated with the type code.

(143) SDK: Item::SetTag

         LXxMETHOD(  LxResult,
 SetTag) (
         LXtObjectID              self,
         LXtID4                   type,
         const char              *tag);

More (601) Methods

This is called by the package that implements the item, indicating that its synthetic name, if it has one, should be updated.

(144) SDK: Item::InvalidateName

         LXxMETHOD(  void,
 InvalidateName) (
         LXtObjectID              self);

Returns LXe_TRUE if this item was part of the most recent load or import. Flags can further refine the test to just import or items being loaded currently.

(145) SDK: Item::WasLoaded

         LXxMETHOD(  LxResult,
 WasLoaded) (
         LXtObjectID              self,
         unsigned                 test);

(146) SDK: LXfITEMLOAD_IMPORT, etc. defines

 #define LXfITEMLOAD_IMPORT      0x01
 #define LXfITEMLOAD_CURRENT     0x02

Delete the item from the scene.

(147) SDK: Item::Delete

         LXxMETHOD(  LxResult,
 Delete) (
         LXtObjectID              self);

Scene Graphs

Graphs provide a means to create relationships between items and/or channels. The scene contains any number of graphs accessed by name,

(148) SDK: LXa_SCENEGRAPH, etc. defines

 #define LXa_SCENEGRAPH          "scenegraph"
 #define LXu_SCENEGRAPH          "FE07D3C5-C7E4-46af-8F0A-5AB173D48445"

Scene Graph Enumeration and Lookup

This method returns a scene graph from an ILxScene by name.

(149) SDK: Scene::GraphLookup

         LXxMETHOD(  LxResult,
 GraphLookup) (
         LXtObjectID              self,
         const char              *name,
         void                   **ppvObj);

This method returns a scene graph from an ILxScene by name.

(150) SDK: CLxUser_Scene::GetGraph method

         bool
 GetGraph (
         const char              *name,
         CLxLocalizedObject      &graph)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (GraphLookup (name, &obj)))
                 return false;
 
         return graph.take (obj);
 }

Graphs can also be initialized from scenes and items.

(151) User Class: SceneGraph method

 ''[[#C152|SDK Common user: Graph methods]]''

This method initializes the graph wrapper from a scene and graph name.

(152) SDK Common user: Graph methods

         bool
 from (
         CLxLoc_Scene            &scene,
         const char              *name)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (scene.GraphLookup (name, &obj)))
                 return false;
 
         return take (obj);
 }

This method initializes the graph wrapper from an item and graph name.

(153) SDK Common user: Graph methods

         bool
 from (
         CLxLoc_Item             &item,
         const char              *name)
 {
         CLxLoc_Scene             scene;
         LXtObjectID              obj;
 
         if (LXx_FAIL (item.Context (&obj)))
                 return false;
 
         scene.take (obj);
         return from (scene, name);
 }

The graph list can be walked directly to get all graphs in the scene. This method returns the number of graphs.

(154) SDK: Scene::GraphCount

         LXxMETHOD(  LxResult,
 GraphCount) (
         LXtObjectID              self,
         int                     *count);

This method returns the graph from the scene by index.

(155) SDK: Scene::GraphByIndex

         LXxMETHOD(  LxResult,
 GraphByIndex) (
         LXtObjectID              self,
         unsigned                 index,
         void                   **ppvObj);

Basic Properties

This method returns the name of a graph.

(156) SDK: SceneGraph::Name

         LXxMETHOD(  LxResult,
 Name) (
         LXtObjectID              self,
         const char             **name);

This returns the scene that the graph belongs to.

(157) SDK: SceneGraph::Context

         LXxMETHOD(  LxResult,
 Context) (
         LXtObjectID              self,
         void                   **ppvObj);

Root Items

Graphs can maintain root items in a specific order. Root items are those that do not link to any other items, like items without parents. This method returns the number of root items. .

(158) SDK: SceneGraph::RootCount

         LXxMETHOD(  LxResult,
 RootCount) (
         LXtObjectID              self,
         int                     *count);

This method gets a root item by index.

(159) SDK: SceneGraph::RootByIndex

         LXxMETHOD(  LxResult,
 RootByIndex) (
         LXtObjectID              self,
         int                      index,
         void                   **ppvObj);

Accessing root items by index can be slow. Instead the root items can be traversed by calling this function to get the first root item.

(160) SDK: SceneGraph::RootFirst

         LXxMETHOD(  LxResult,
 RootFirst) (
         LXtObjectID              self,
         void                   **ppvObj);

Once the first root item has been read, calling this function will read subsequent root items.

(161) SDK: SceneGraph::RootNext

         LXxMETHOD(  LxResult,
 RootNext) (
         LXtObjectID              self,
         void                   **ppvObj);

This function will place the given root item at the given index in the sequence. It returns LXe_OK on success, and an error code for failures including if the item is not in fact a root item.

(162) SDK: SceneGraph::RootSetPos

         LXxMETHOD(  LxResult,
 RootSetPos) (
         LXtObjectID              self,
         LXtObjectID              item,
         int                      pos);

Since clients can directly manipulate the graph links, this function should be called to remove an item from the root sequence if it's no longer a root item.

(163) SDK: SceneGraph::RootRemove

         LXxMETHOD(  LxResult,
 RootRemove) (
         LXtObjectID              self,
         LXtObjectID              item);

Empty SceneGraph Python user class.

(164) PY: empty SceneGraph user class

 pass

Specific Scene Graph Interfaces

Different graphs may have different secondary interfaces for specific behaviors. The ILxSceneGraph object can queried for these alternate interfaces.

Item Graph Interface

The item graph interface provides item-to-item linking.

(165) SDK: LXa_ITEMGRAPH, etc. defines

 #define LXa_ITEMGRAPH           "itemgraph"
 #define LXu_ITEMGRAPH           "C34D7C65-031A-4c9d-8C01-3187D383937B"

(166) User Class: ItemGraph method

 ''[[#C152|SDK Common user: Graph methods]]''

Links can be established between any pair of nodes provided the rules for the graph allow it. This function adds a link from one node to another, and the new reference is added to the end of each node's list.

(167) SDK: ItemGraph::AddLink

         LXxMETHOD( LxResult,
 AddLink) (
         LXtObjectID              self,
         LXtObjectID              from,
         LXtObjectID              to);

This allows new links to be added or the order of existing links to be changed. The link will take on the corresponding index in the forward and reverse lists for each node. An index value of -1 leaves the index unchanged, and a positive index out of range puts the link at the end of the list.

(168) SDK: ItemGraph::SetLink

         LXxMETHOD( LxResult,
 SetLink) (
         LXtObjectID              self,
         LXtObjectID              from,
         int                      fromIndex,
         LXtObjectID              to,
         int                      toIndex);

The function removes the link between two nodes. In theory it can fail based on the rules for the graph, but in practice it generally doesn't.

(169) SDK: ItemGraph::DeleteLink

         LXxMETHOD( LxResult,
 DeleteLink) (
         LXtObjectID              self,
         LXtObjectID              from,
         LXtObjectID              to);

Enumerating Links

For nodes which are the source or destination of links, the links can be queried by using a count/byIndex syntax. Forward links take the 'from' item and enumerate the 'to' items. Reverse links take the 'to' item and enumerate the 'from' items.

This gets the count of forward links.

(170) SDK: ItemGraph::FwdCount

         LXxMETHOD( LxResult,
 FwdCount) (
         LXtObjectID              self,
         LXtObjectID              item,
         unsigned                *count);

This get the destination of the forward link by index.

(171) SDK: ItemGraph::FwdByIndex

         LXxMETHOD( LxResult,
 FwdByIndex) (
         LXtObjectID              self,
         LXtObjectID              item,
         unsigned                 index,
         void                   **ppvObj);

This gets the count of reverse links.

(172) SDK: ItemGraph::RevCount

         LXxMETHOD( LxResult,
 RevCount) (
         LXtObjectID              self,
         LXtObjectID              item,
         unsigned                *count);

This get the source of the reverse link by index.

(173) SDK: ItemGraph::RevByIndex

         LXxMETHOD( LxResult,
 RevByIndex) (
         LXtObjectID              self,
         LXtObjectID              item,
         unsigned                 index,
         void                   **ppvObj);

This gets the count of forward links.

(174) SDK: CLxUser_ItemGraph::Forward method

         unsigned
 Forward (
         CLxLoc_Item             &item)
 {
         unsigned                 n;
 
         if (LXx_FAIL (FwdCount (item, &n)))
                 n = 0;
 
         return n;
 }

This get the destination of the forward link by index.

(175) SDK: CLxUser_ItemGraph::Forward method

         bool
 Forward (
         CLxLoc_Item             &item,
         unsigned                 index,
         CLxLoc_Item             &dest)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (FwdByIndex (item, index, &obj)))
                 return false;
 
         return dest.take (obj);
 }

This gets the count of reverse links.

(176) SDK: CLxUser_ItemGraph::Reverse method

         unsigned
 Reverse (
         CLxLoc_Item             &item)
 {
         unsigned                 n;
 
         if (LXx_FAIL (RevCount (item, &n)))
                 n = 0;
 
         return n;
 }

This get the source of the reverse link by index.

(177) SDK: CLxUser_ItemGraph::Reverse method

         bool
 Reverse (
         CLxLoc_Item             &item,
         unsigned                 index,
         CLxLoc_Item             &dest)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (RevByIndex (item, index, &obj)))
                 return false;
 
         return dest.take (obj);
 }

Empty ItemGraph Python user class.

(178) PY: empty ItemGraph user class

 pass

Channel Graph Interface

The channel graph interface provides item/channel-to-item/channel linking. The methods are the same as those in the item graph interface above, but take an item/channel index pair instead of just an item.

(179) SDK: LXa_CHANNELGRAPH, etc. defines

 #define LXa_CHANNELGRAPH        "channelgraph"
 #define LXu_CHANNELGRAPH        "F70C8AD7-C15F-42e7-98F6-4C4C7F6D577E"

(180) User Class: ChannelGraph method

 ''[[#C152|SDK Common user: Graph methods]]''

Create a link from an item/channel to an item/channel pair.

(181) SDK: ChannelGraph::AddLink

         LXxMETHOD( LxResult,
 AddLink) (
         LXtObjectID              self,
         LXtObjectID              from,
         int                      fromChan,
         LXtObjectID              to,
         int                      toChan);

Create or reorder a link from an item/channel to an item/channel pair.

(182) SDK: ChannelGraph::SetLink

         LXxMETHOD( LxResult,
 SetLink) (
         LXtObjectID              self,
         LXtObjectID              from,
         int                      fromChan,
         int                      fromIndex,
         LXtObjectID              to,
         int                      toChan,
         int                      toIndex);

Remove a channel link.

(183) SDK: ChannelGraph::DeleteLink

         LXxMETHOD( LxResult,
 DeleteLink) (
         LXtObjectID              self,
         LXtObjectID              from,
         int                      fromChan,
         LXtObjectID              to,
         int                      toChan);

Get the count of forward links from this channel.

(184) SDK: ChannelGraph::FwdCount

         LXxMETHOD( LxResult,
 FwdCount) (
         LXtObjectID              self,
         LXtObjectID              item,
         int                      channel,
         unsigned                *count);

Get the destination of a forward link by index.

(185) SDK: ChannelGraph::FwdByIndex

         LXxMETHOD( LxResult,
 FwdByIndex) (
         LXtObjectID              self,
         LXtObjectID              item,
         int                      channel,
         unsigned                 index,
         void                   **ppvObj,
         int                     *objChan);

Get the count of reverse links to this channel.

(186) SDK: ChannelGraph::RevCount

         LXxMETHOD( LxResult,
 RevCount) (
         LXtObjectID              self,
         LXtObjectID              item,
         int                      channel,
         unsigned                *count);

Get the source of a reverse link by index.

(187) SDK: ChannelGraph::RevByIndex

         LXxMETHOD( LxResult,
 RevByIndex) (
         LXtObjectID              self,
         LXtObjectID              item,
         int                      channel,
         unsigned                 index,
         void                   **ppvObj,
         int                     *objChan);

Empty ChannelGraph Python user class.

(188) PY: empty ChannelGraph user class

 pass

More Methods (501)

501

Methods are added here since we want them at the end of the structure.

(189) SDK: Scene::ItemRemove

         LXxMETHOD(  LxResult,
 ItemRemove) (
         LXtObjectID              self,
         LXtObjectID              item);

Remove the item from the scene.

(190) SDK: CLxUser_Scene::RemItem method

         bool
 RemItem (
         CLxLoc_Item             &item)
 {
         return LXx_OK (ItemRemove (item)) ? true : false;
 }

This loads a file into an existing scene. A monitor must be provided, and can be obtained from DialogService (interface).

(191) SDK: Scene::Import

         LXxMETHOD(  LxResult,
 Import) (
         LXtObjectID              self,
         const char              *path,
         LXtObjectID              monitor);

Invalidate an EvalModifier with the given server name. This is done automatically for item and graph events, but can also be done manually for other changes. Out of date modifier nodes will be destroyed and new ones created, allowing nodes to change their inputs and outputs.

(192) SDK: Scene::EvalModInvalidate

         LXxMETHOD(  LxResult,
 EvalModInvalidate) (
         LXtObjectID              self,
         const char              *modName);

Reset the state of an eval modifier. Modifier nodes remain as they are but any cached state is invalidated.

(193) SDK: Scene::EvalModReset

         LXxMETHOD(  LxResult,
 EvalModReset) (
         LXtObjectID              self,
         const char              *modName);

Create a new item with the specified type from passed item, replacing the original.

(194) SDK: Scene::ItemReplace

         LXxMETHOD(  LxResult,
 ItemReplace) (
         LXtObjectID              self,
         LXtObjectID              item,
         int                      type,
         void                   **ppvObj);

Create a new item with the specified type from passed item, replacing the original.

(195) SDK: CLxUser_Scene::ReplaceItem method

         bool
 ReplaceItem (
         CLxLoc_Item             &item,
         LXtItemType              type,
         CLxLoc_Item             &newItem)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemReplace (item, type, &obj)))
                 return false;
 
         return newItem.take (obj);
 }

This returns LXe_TRUE if the scene is in "Setup Mode", and LXe_FALSE otherwise.

(196) SDK: Scene::SetupMode

         LXxMETHOD(  LxResult,
 SetupMode) (
         LXtObjectID              self);

Alternate version of the Channels function, which evaluates channels in Setup mode.

(197) SDK: Scene::SetupChannels

         LXxMETHOD(  LxResult,
 SetupChannels) (
         LXtObjectID              self,
         void                   **ppvObj);

Lookup item using ident only, not full name.

(198) SDK: Scene::ItemLookupIdent

         LXxMETHOD(  LxResult,
 ItemLookupIdent) (
         LXtObjectID              self,
         const char              *id,
         void                   **ppvObj);

Lookup item using ident only.

(199) SDK: CLxUser_Scene::GetItemByIdent method

         bool
 GetItemByIdent (
         const char              *name,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemLookupIdent (name, &obj)))
                 return false;
 
         return item.take (obj);
 }

During import old idents can be used to look up imported items which will have been given new idents.

(200) SDK: Scene::ItemLookupImported

         LXxMETHOD(  LxResult,
 ItemLookupImported) (
         LXtObjectID              self,
         const char              *id,
         void                   **ppvObj);

Lookup an imported item by it's original ident.

(201) SDK: CLxUser_Scene::GetImportedItem method

         bool
 GetImportedItem (
         const char              *name,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (ItemLookupImported (name, &obj)))
                 return false;
 
         return item.take (obj);
 }

These functions can be used to get a list of all the possible (linked) render cameras.

(202) SDK: Scene::RenderCameraCount

         LXxMETHOD(  LxResult,
 RenderCameraCount) (
         LXtObjectID              self,
         int                     *count);

Note that if RenderCameraCount gives zero, feeding a value of -1 into RenderCameraByIndex will actually get the render camera (which can be any camera).

(203) SDK: Scene::RenderCameraByIndex

         LXxMETHOD(  LxResult,
 RenderCameraByIndex) (
         LXtObjectID              self,
         int                      index,
         void                   **ppvObj);

Get the number of render cameras.

(204) SDK: CLxUser_Scene::NRenderCameras method

         int
 NRenderCameras ()
 {
         int                      n;
 
         if (LXx_OK (RenderCameraCount (&n)))
                 return n;
         else
                 return 0;
 }

Get the render camera by index.

(205) SDK: CLxUser_Scene::GetRenderCameraByIndex method

         bool
 GetRenderCameraByIndex (
         int                      index,
         CLxLoc_Item             &item)
 {
         LXtObjectID              obj;
 
         if (LXx_FAIL (RenderCameraByIndex (index, &obj)))
                 return false;
 
         return item.take (obj);
 }

And this function, which takes in an eval, gets the current render camera index.

(206) SDK: Scene::RenderCameraIndex

         LXxMETHOD(  LxResult,
 RenderCameraIndex) (
         LXtObjectID              self,
         LXtObjectID              eval,
         int                     *index);

Get the render camera index.

(207) SDK: CLxUser_Scene::GetRenderCameraIndex method

         int
 GetRenderCameraIndex (
         CLxLoc_Evaluation        eval)
 {
         ILxEvaluationID          ev;
         int                      i;
 
         eval.get ((void **)&ev);
 
         if (LXx_OK (RenderCameraIndex ((ILxUnknownID)ev, &i)))
                 return i;
         else
                 return 0;
 }

This method creates a duplicate of an existing item.

(208) SDK: Scene::ItemCopy

         LXxMETHOD(  LxResult,
 ItemCopy) (
         LXtObjectID              self,
         LXtObjectID              item,
         void                   **ppvObj);

801

Items can be created in batch mode, where they are created in an incomplete state which is only finalized when the batch is ended. If the copy fails the client must call the abort function.

Start a batch for item creation.

(209) SDK: Scene::BatchCreateBegin

         LXxMETHOD(  LxResult,
 BatchCreateBegin) (
         LXtObjectID              self);

End batch item creation.

(210) SDK: Scene::BatchCreateEnd

         LXxMETHOD(  LxResult,
 BatchCreateEnd) (
         LXtObjectID              self);

Abort batch item creation.

(211) SDK: Scene::BatchCreateAbort

         LXxMETHOD(  LxResult,
 BatchCreateAbort) (
         LXtObjectID              self);

Likewise copying items can be done in a batch state. This also allows the client to specify a different destination scene for the copies to be created.

Start a batch copy, setting the destination scene if different.

(212) SDK: Scene::BatchCopyBegin

         LXxMETHOD(  LxResult,
 BatchCopyBegin) (
         LXtObjectID              self,
         LXtObjectID              destination);

End batch item copy.

(213) SDK: Scene::BatchCopyEnd

         LXxMETHOD(  LxResult,
 BatchCopyEnd) (
         LXtObjectID              self);

Abort batch item copy.

(214) SDK: Scene::BatchCopyAbort

         LXxMETHOD(  LxResult,
 BatchCopyAbort) (
         LXtObjectID              self);

This function can be used to get the world rotation of the workplane.

(215) SDK: Scene::WorkPlaneRotation

         LXxMETHOD(  LxResult,
 WorkPlaneRotation) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtMatrix                m3);

This function can be used to get the world position of the workplane.

(216) SDK: Scene::WorkPlanePosition

         LXxMETHOD(  LxResult,
 WorkPlanePosition) (
         LXtObjectID              self,
         LXtObjectID              chanRead,
         LXtVector                pos);

903

These function will return a list of items matching the item list type and arguments. The returned object is an ItemCollection. Because this is normally used for UI purposes, the collection includes only items that are visible to the user and filters out items that the user shouldn't see. There is an alternate "raw" form to get the unfiltered list.

Get a collection of visible items.

(217) SDK: Scene::GeneralCollection

         LXxMETHOD(  LxResult,
 GeneralCollection) (
         LXtObjectID              self,
         const char              *typeName,
         const char              *arg,
         LXtObjectID              rootItem,
         void                   **ppvObj);

Get a collection of all items.

(218) SDK: Scene::GeneralCollectionRaw

         LXxMETHOD(  LxResult,
 GeneralCollectionRaw) (
         LXtObjectID              self,
         const char              *typeName,
         const char              *arg,
         LXtObjectID              rootItem,
         void                   **ppvObj);

Asset Management

This method allocates a new asset object for the scene.

(219) SDK: Scene::AllocAssets

         LXxMETHOD(  LxResult,
 AllocAssets) (
         LXtObjectID              self,
         void                   **ppvObj);

The scene assets object provides a way to traverse and update the assets in a scene.

(220) SDK: LXu_SCENEASSETS define

 #define LXu_SCENEASSETS         "FB35AE38-4BF6-4B6E-87E0-6A6CB2995B78"

Get the total number of asset references in the scene.

(221) SDK: SceneAssets::Count

         LXxMETHOD(  LxResult,
 Count) (
         LXtObjectID              self,
         unsigned                *count);

Get the item for an asset by index.

(222) SDK: SceneAssets::Item

         LXxMETHOD(  LxResult,
 Item) (
         LXtObjectID              self,
         unsigned                 index,
         void                   **ppvObj);

Get the ident string for an asset by index. The ident will uniquely identify this asset with respect to the item.

(223) SDK: SceneAssets::Ident

         LXxMETHOD(  LxResult,
 Ident) (
         LXtObjectID              self,
         unsigned                 index,
         const char             **ident);

Get the type This is essentially a file type and can be used when opening dialogs.

(224) SDK: SceneAssets::FileType

         LXxMETHOD(  LxResult,
 FileType) (
         LXtObjectID              self,
         unsigned                 index,
         const char             **type);

Get the category string for an asset by index. This is an identifier for grouping like assets together, and may just be the item type.

(225) SDK: SceneAssets::Category

         LXxMETHOD(  LxResult,
 Category) (
         LXtObjectID              self,
         unsigned                 index,
         const char             **category);

Test an asset by index to determine if it's a normal path or sequence pattern.

(226) SDK: SceneAssets::IsSequence

         LXxMETHOD(  LxResult,
 IsSequence) (
         LXtObjectID              self,
         unsigned                 index);

Given the item and asset ident, this returns the current path. Returns NOTFOUND if unset.

(227) SDK: SceneAssets::GetPath

         LXxMETHOD(  LxResult,
 GetPath) (
         LXtObjectID              self,
         LXtObjectID              item,
         const char              *ident,
         char                    *buf,
         unsigned                 len);

Given the item and asset ident, this resets the current path. This alters the scene and redirects the item to use the new file.

(228) SDK: SceneAssets::SetPath

         LXxMETHOD(  LxResult,
 SetPath) (
         LXtObjectID              self,
         LXtObjectID              item,
         const char              *ident,
         const char              *newPath);

The instance assets interface is implemented by the package instance, and allows the item to present APIs for accessing its assets.

(229) SDK: LXu_INSTANCEASSETS define

 #define LXu_INSTANCEASSETS      "C7454DED-84A7-4E5E-8FBE-A98D0EE3C6B4"

Get the number of asset references for this item.

(230) SDK: InstanceAssets::Count

         LXxMETHOD(  LxResult,
 Count) (
         LXtObjectID              self,
         unsigned                *count);

Get the required information about an asset reference by index. The string returned through the buffer is the ident.

(231) SDK: InstanceAssets::IdentByIndex

         LXxMETHOD(  LxResult,
 IdentByIndex) (
         LXtObjectID              self,
         unsigned                 index,
         unsigned                *isSeq,
         const char             **fileType,
         char                    *buf,
         unsigned                 len);

Get optional category.

(232) SDK: InstanceAssets::Category

         LXxMETHOD(  LxResult,
 Category) (
         LXtObjectID              self,
         unsigned                 index,
         char                    *buf,
         unsigned                 len);

Get the path given the ident.

(233) SDK: InstanceAssets::GetPath

         LXxMETHOD(  LxResult,
 GetPath) (
         LXtObjectID              self,
         const char              *ident,
         char                    *buf,
         unsigned                 len);

Set the path given the ident, altering the scene.

(234) SDK: InstanceAssets::SetPath

         LXxMETHOD(  LxResult,
 SetPath) (
         LXtObjectID              self,
         const char              *ident,
         const char              *newPath);

11.0

Call this service method to allocate an empty collection.

(235) SDK: SceneService::AllocEmptyCollection

         LXxMETHOD(  LxResult,
 AllocEmptyCollection) (
         LXtObjectID              self,
         void                   **ppvObj);

A collection can be closed given a closure mode. All items matching the mode are added to the collection. NONE can be used just to merge the recently added items so they can be tested.

(236) SDK: SceneService::CloseCollection

         LXxMETHOD(  LxResult,
 CloseCollection) (
         LXtObjectID              self,
         LXtObjectID              collection,
         unsigned                 mode);

Delete all items belonging to a collection. The collection can be closed first, either deep or shallow.

(237) SDK: Scene::DeleteCollection

         LXxMETHOD(  LxResult,
 DeleteCollection) (
         LXtObjectID              self,
         LXtObjectID              collection,
         unsigned                 closeMode);

Often it can be useful to "fake" a scene load, populating a scene with items directly, rather than using a loader. This function will call a visitor, which can be used to add items into a scene. The advantage of this mechanism, is that any event notifications will be deferred until the "load" is complete, which could have a positive effect on performance.

(238) SDK: Scene::CustomLoad

         LXxMETHOD(  LxResult,
 CustomLoad) (
         LXtObjectID              self,
         LXtObjectID              visitor);

Item (lx-item.hpp)

Contents

Item SDK

ILxSceneService

(1) SDK: LXa_SCENESERVICE, etc. defines

(2) SDK: SceneService::ScriptQuery

(3) SDK: SceneService::Root

Item Types

(4) SDK: Types

(5) SDK: SceneService::ItemTypeCount

(6) SDK: SceneService::ItemTypeByIndex

(7) PY: Service.Scene.ItemTypeList method

(8) SDK: SceneService::ItemTypeLookup

(9) SDK: CLxUser_SceneService::ItemType method

(10) SDK: SceneService::ItemTypeName

(11) SDK: SceneService::ItemTypeTest

(12) SDK: SceneService::ItemTypeSuper

(13) SDK: SceneService::ItemTypeCommonChannels

(14) SDK: SceneService::ItemSubTypeCount

(15) SDK: SceneService::ItemSubTypeByIndex

(16) PY: Service.Scene.ItemSubTypeList method

Utilities

(17) SDK: SceneService::ChannelVectorSize

(18) SDK: SceneService::ChannelVectorTextHints

Scenes

(19) SDK: SceneService::CreateScene

(20) SDK: CLxUser_SceneService::NewScene method

(21) SDK: SceneService::DestroyScene

(22) SDK: SceneService::SubSceneAdd

(23) SDK: SceneService::SubSceneLoad

Mesh Instances

(24) SDK: SceneService::GetMeshInstSourceItem

(25) SDK: SceneService::MeshInstanceCount

(26) SDK: SceneService::MeshInstanceByIndex

Images

(27) SDK: SceneService::LoadImage

Replicators

(28) SDK: SceneService::GetReplicatorEnumerator

(29) SDK: CLxUser_SceneService::NewReplicatorEnumerator method

Item Type Tags

(30) SDK: SceneService::ItemTypeGetTag

Type Support

(31) User Class: additional

Item Collection

(32) SDK: SceneService::ItemGraphCollection

Scene Save

(33) SDK: LXsSAV_SCENE_SUBSET, etc. defines

(34) SDK: LXu_SCENESUBSET define

(35) SDK: SceneSubset::GetScene

(36) SDK: SceneSubset::GetCollection

(37) SDK: empty SceneSubset User Class

(38) PY: empty SceneSubset user class

ILxScene

(39) SDK: LXu_SCENE, etc. defines

(40) SDK: CLxUser_Scene::from method

(41) SDK: CLxUser_Scene::CLxUser_Scene method

(42) PY: Scene.from_item method

Basic Properties

(43) SDK: Scene::ItemRootType

(44) SDK: Scene::Filename

(45) SDK: Scene::FriendlyFilename

(46) SDK: LXfSCENENAME_STAR, etc. defines

(47) SDK: Scene::FileFormat

(48) SDK: Scene::Changed

(49) SDK: Scene::HasChanged

Parenting, Enumeration and Sub-Scenes

(50) SDK: Scene::Parent

(51) SDK: Scene::SubSceneCount

(52) SDK: Scene::SubSceneByIndex

(53) SDK: Scene::LoadFlags

Actions

(54) SDK: Scene::Channels

(55) SDK: CLxUser_Scene::GetChannels method

(56) SDK: CLxUser_Scene::GetChannels method

(57) SDK: CLxUser_Scene::GetSetupChannels method

(58) SDK: CLxUser_Scene::SetChannels method

Items

(59) SDK: Scene::ItemCount

(60) SDK: Scene::ItemByIndex

(61) SDK: CLxUser_Scene::NItems method