v3.0

Sets or returns a BSTR (String) containing the user data for this UserDataItem. The way this property is used depends whether the UserDataMap has an associated template or not.

In the context of templated UserDataMap:

This property is used to transfer user data to and from the CustomProperty.BinaryData property of the UserDataMap.Template. In this case you do not need to understand the format of the data, because you read and write the values via the ParameterCollection property of the template.

Note: The call will fail if you attempt to transfer data from an empty UserDataItem its template. It will also fail if the format of the template does not match the content of the UserDataItem.

In the context of a binary UserDataMap:

This property is used to read and write binary or string data to the UserDataItem, with no limits imposed on size or structure.

All scripting languages can conveniently store string values inside user data. Any numeric or structured data can be encoded in a text format and saved as user data. However, a string representation uses more memory than a binary representation. Furthermore, the binary representation of strings differs on different operating systems and platforms. For example the letter A is stored as 97 0 on Windows 2000 and as 97 0 0 0 on Linux running on x86 processors.

C++ developers can also use strings, but they can also easily store true binary data. The Win32 function SysAllocStringByteLen should be used to convert an contiguous block of memory into a BSTR representation. SysStringByteLen provides a safe way to determine the length of a BSTR that may contain null characters. SysFreeString should be used to free any memory allocated by SysAllocStringByteLen. When using this technique there is practically no overhead in memory usage.

Note: It is not recommended that the user data contain any memory addresses or other information that is transitive.

If you have a large number of components but only a few different user data values then you might want to consider storing a table index as the user data value instead of duplicating the user data. This approach can reduce the memory consumption of the user data map.

When transfering binary user data between platforms it may be necessary to perform byte-swapping. See UserDataMap.LittleEndian.

An empty string is returned if the UserDataItem is empty.

This property is equivalent to UserDataMap.ItemValue.

VBScript Example

' 
' Example of the difference between a binary user data map and a templated user data map
' 
Option Explicit
NewScene ,false
dim oSphere, oCluster, oBinaryUserDataMap, oTemplatedUserDataMap, oTemplatePSet
set oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" )
set oCluster = oSphere.ActivePrimitive.Geometry.AddCluster( siEdgeCluster, "ExampleEdgeCluster" ) 
set oBinaryUserDataMap = oCluster.AddProperty( "UserDataMap",,"Binary" )
set oTemplatedUserDataMap = oCluster.AddProperty( "UserDataMap",,"Templated" )
'Create the template custom property object that will define the 
'format of the user data on the templated user data map
set oTemplatePSet = oCluster.AddProperty( "Custom_parameter_list",, "TemplatePSet" )
oTemplatePSet.AddParameter "ImagePath", siString
oTemplatePSet.AddParameter "ZetaFactor", siDouble, , , , , , 0.0, 0.0, 1.0
'This turns our second object into a templated user data map
set oTemplatedUserDataMap.Template = oTemplatePSet
'Get user data for item 13 (both are initially empty)
dim oUserDataOnBinaryUDM, oUserDataOnTemplatedUDM
set oUserDataOnBinaryUDM = oBinaryUserDataMap.Item( 13 )
set oUserDataOnTemplatedUDM = oTemplatedUserDataMap.Item( 13 )
'For the binary user data we save a string directly as the value
'(From C++ this string can easily contain binary data)
oUserDataOnBinaryUDM.Value = "Sample data"
'For the templated user data Softimage understands the structure of the
'data and we use the PSet to get and set values
oTemplatedUserDataMap.Template.Parameters("ImagePath").Value = "Image1.tif"
oTemplatedUserDataMap.Template.Parameters("ZetaFactor").Value = 0.25
'Transfer the values we saved on the pset into the user data item on edge 13
oUserDataOnTemplatedUDM.Value = oTemplatedUserDataMap.Template.BinaryData
'In both cases you can copy the values directly between different components like this.
'(However it would not be correct to try to copy data between the two maps)
oBinaryUserDataMap.Item( 15 ).Value = oBinaryUserDataMap.Item( 13 ).Value
oTemplatedUserDataMap.Item( 15 ).Value = oTemplatedUserDataMap.Item( 13 ).Value

UserDataMap UserDataMap.ItemValue CustomProperty.BinaryData