v3.0
この UserDataItem のユーザデータを含む BSTR（String）を設定したり、戻したりします。このプロパティの使用法は、UserDataMap が関連テンプレートを持つかどうかにより異なります。
テンプレート UserDataMap のコンテキストの場合：
このプロパティは、UserDataMap.Template の CustomProperty.BinaryData プロパティとのユーザ データの送受信に使用されます。テンプレートの ParameterCollection プロパティ経由で値を読み書きをするため、ユーザはユーザデータの書式を理解する必要はありません。
注：空の UserDataItem テンプレートからデータを転送しようとすると、コールに失敗します。また、テンプレートのフォーマットが UserDataItem の内容と一致しない場合もコールに失敗します。
バイナリの UserDataMap のコンテキストの場合:
このプロパティは、バイナリまたは文字列データの UserDataItem への読み込みと書き込みに使用され、サイズや構造に制限はありません。
すべてのスクリプト言語は、文字列値をユーザデータ内に保存できます。数値データまたは構造化データもテキスト形式にエンコードして、ユーザデータとして保存できます。ただし、文字列表現はバイナリ表現よりメモリを多く使用します。また、文字列のバイナリ表現は、さまざまなオペレーティングシステムおよびプラットフォームで異なります。たとえば文字 A は、Windows 2000 では 97 0、x86 プロセッサで実行されている Linux では 97 0 0 0 という表現で保存されます。
C++の開発者は文字列を使用することもできますが、真のバイナリデータも容易に格納できます。Win32 関数の SysAllocStringByteLen を使用すると、メモリの隣接ブロックを BSTR 表現に変換できます。SysStringByteLen を使用すると、ヌル文字を含んでいる可能性のある BSTr の長さを安全に決定できます。SysFreeString を使用すると、SysAllocStringByteLen で割り当てられたメモリを解放できます。このテクニックを使用した場合、メモリ使用において実質的にオーバーヘッドはありません。
注：ユーザデータにメモリアドレスその他、状況によって変化する情報を含めることはお勧めできません。
コンポーネントが多数存在する一方でユーザデータ値が少ない場合は、ユーザデータを複製せずに、テーブルインデックスをユーザデータ値として保存することがあります。この方法では、ユーザデータマップのメモリ消費を低減できます。
プラットフォーム間でバイナリユーザデータを転送するときには、バイトスワッピングを実行しなければならない場合があります。UserDataMap.LittleEndianを参照してください。
UserDataItem が空である場合は空の文字列が戻されます。
UserDataMap.ItemValue このプロパティはと同等です。
// get accessor String rtn = UserDataItem.Value; // set accessor UserDataItem.Value = String; |
'
' 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 |