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