UserDataBlob.Array32

UserDataBlob.Array32 operator

導入

v9.0 (2011)

詳細

UserDataBlob 上のバイナリユーザデータを符号なし整数（32 ビット）の Safe Array として設定したり、戻したりします。このプロパティの操作に適した言語は Python です。

このプロパティは UserDataBlob.ByteArray プロパティよりパフォーマンスに優れています。特に、Python スクリプト言語とその array module を使用する場合です。Array32 プロパティは、1 つの符号なし整数の中に最高 4 つの符号なしバイトをパックできるため、データのアクセスまたは設定を行うときのオーバーヘッドが少なくなります。

このプロパティの設定時、このスキーマを使用して、符号なしバイト配列を符号なし整数配列に手動で変換する必要があります。[,,]、ここで 保存するバイトを表し、 このプロパティを有効な 32 ビットの整数にするために、追加する必要がある null バイトを表し、さらに このプロパティを有効な 32 ビットの整数にするために、データの末尾に付加した null バイトの数を表します。

戻り値をバイト配列に変換するときは、同じ形式で解釈する必要があります。つまり、配列の最初の項目はバイト配列に追加された null バイトの個数を表し、次の項目（複数可）はデータとパディングの初期カウントで示されるすべてのパディングを表します。これらの要件は、次のように守る必要があります。

- データは、符号なし整数(32 ビット)の Safe Array として設定し、戻します。Python で推奨されるデータ構造は array.array ('I')です。JScript ではネイティブ配列が受け入れられます(Python 配列と JScript 配列は、内部で Safe Array オブジェクトに変換されます)。

- それぞれの符号なし整数配列の最初の項目は、0 ～3 の範囲の整数であり、整数配列を有効にするために追加が必要な null バイト数を記述する必要があります。

- 各符号なしバイトは、0 ～255 の範囲にする必要があります。

- 整数配列の各整数の値は、適切にデータを保持するため 0 ～4294967295 の範囲にする必要があります。

- 特定のスクリプト言語では、戻り値が突然現れることがあります。

警告: SafeArray の各要素は内部で 4 バイトに変換されます。変換できない場合は、プロパティの設定は失敗しデータは変更されないまま残ります。

注: このデータは内部でコピーされ、シーンの一部として保存されます。ユーザデータのストラクチャのサイズに制限はありません。内部的には、UserDataBlob.Value、UserDataBlob.ByteArray、および Array32 プロパティは同じデータを参照します。ただし、わかりやすいように、プラグインの全域でいずれか 1 つを使用するようにします。

C#構文

// get accessor

Object rtn = UserDataBlob.Array32;

// set accessor

UserDataBlob.Array32 = Object;

例

1. Python の例

# Setting and retrieving the data using UserDataBlob.Array32

#

import array

Application.NewScene("", False)

blob = Application.ActiveSceneRoot.AddProperty("UserDataBlob", False, "myBlob");

Application.LogMessage("----------------Setting the Array32 Property----------------")

myString = "This is a string!"

# Convert the string to an unsigned byte array

myStringAsAByteArray = array.array('B', myString)

Application.LogMessage("myStringAsAByteArray = " + str(myStringAsAByteArray))

# To convert the unsigned byte (8 bit) array to an unsigned integer (32 bit) array,

# the size of the byte array needs to be a multiple of 4.

# To do so, let's pad the end of the byte array with null bytes

NumBytesPadded = 0

while len(myStringAsAByteArray) % 4 != 0:

	myStringAsAByteArray.append( 0 )

	NumBytesPadded += 1

Application.LogMessage("myStringAsAByteArray = " + str(myStringAsAByteArray))

Application.LogMessage("NumBytesPadded = " + str(NumBytesPadded))

# Convert the unsigned byte array to an unsigned integer array

# and add the number of null bytes padded as the first index of the integer array

myStringAsAnIntArray = array.array('I', myStringAsAByteArray.tostring())

myStringAsAnIntArray.insert(0, NumBytesPadded) 

Application.LogMessage("myStringAsAnIntArray = " + str(myStringAsAnIntArray))

# Set the UserDataBlob.Array32 property

blob.Array32 = myStringAsAnIntArray

Application.LogMessage("----------------Getting the Array32 Property----------------")

# Get the UserDataBlob.Array32 property

BlobIntTuple = blob.Array32

Application.LogMessage("BlobIntTuple = " + str(BlobIntTuple))

# Convert the integer tuple to an unsigned integer array

BlobIntArray = array.array('I', BlobIntTuple)

# Get the number of null bytes padded to the end of the byte array

# and removes it from the integer array

BlobNumBytesPadded = BlobIntArray.pop(0)

Application.LogMessage("BlobNumBytesPadded = " + str(BlobNumBytesPadded))

Application.LogMessage("BlobIntArray = " + str(BlobIntArray))

# Convert the unsigned integer array to an unsigned byte array

BlobByteArray = array.array('B', BlobIntArray.tostring() )

Application.LogMessage("BlobByteArray = " + str(BlobByteArray))

# Remove the number of bytes padded from the unsigned byte array

BlobByteArray = BlobByteArray[0:len(BlobByteArray)-BlobNumBytesPadded]

Application.LogMessage("BlobByteArray = " + str(BlobByteArray))

# Print the string

Application.LogMessage("BlobString = " + BlobByteArray.tostring())

# Expected results:

# INFO : ----------------Setting the Array32 Property----------------

# INFO : myStringAsAByteArray = array('B', [84, 104, 105, 115, 32, 105, 115, 32, 97, 32, 115, 116, 114, 105, 110, 103, 33])

# INFO : myStringAsAByteArray = array('B', [84, 104, 105, 115, 32, 105, 115, 32, 97, 32, 115, 116, 114, 105, 110, 103, 33, 0, 0, 0])

# INFO : NumBytesPadded = 3

# INFO : myStringAsAnIntArray = array('I', [3L, 1936287828L, 544434464L, 1953701985L, 1735289202L, 33L])

# INFO : ----------------Getting the Array32 Property----------------

# INFO : BlobIntTuple = (3, 1936287828, 544434464, 1953701985, 1735289202, 33)

# INFO : BlobNumBytesPadded = 3

# INFO : BlobIntArray = array('I', [1936287828L, 544434464L, 1953701985L, 1735289202L, 33L])

# INFO : BlobByteArray = array('B', [84, 104, 105, 115, 32, 105, 115, 32, 97, 32, 115, 116, 114, 105, 110, 103, 33, 0, 0, 0])

# INFO : BlobByteArray = array('B', [84, 104, 105, 115, 32, 105, 115, 32, 97, 32, 115, 116, 114, 105, 110, 103, 33])

# INFO : BlobString = This is a string!

2. JScript の例

// Setting and retrieving the data using UserDataBlob.Array32

//

NewScene(null, false);

var blob = Application.ActiveSceneRoot.AddProperty("UserDataBlob", false, "myBlob");

// Create an unsigned integer array and set it as the blob data

// Don't forget that the first item must be the number of null bytes added

// to the unsigned byte array (0 in this case since we want to store only

// unsigned integer values)

var WriteArray = [0,1,3,5,4294967295];

blob.Array32 = WriteArray;

// Retrieve the blob data

// Don't forget that the first item is the number of null bytes added

// to the unsigned byte array

var ReadArray = blob.Array32;

Application.LogMessage("ReadArray  = " + ReadArray.toArray());

// Expected results:

// INFO : ReadArray  = 0,1,3,5,4294967295

3. VBScript の例

' Setting and retrieving the data using UserDataBlob.Array32

'

NewScene null , False

set  blob = Application.ActiveSceneRoot.AddProperty("UserDataBlob", false, "myBlob")

' Create an unsigned integer array and set it as the blob data

' Don't forget that the first item must be the number of null bytes added

' to the unsigned byte array (0 in this case since we want to store only

' unsigned integer values)

Dim WriteArray

WriteArray = Array(0,1,3,5,4294967295)

blob.Array32 = WriteArray

' Retrieve the blob data

' Don't forget that the first item is the number of null bytes added

' to the unsigned byte array

Dim ReadArray

ReadArray = blob.Array32

For i = 0 to Ubound(ReadArray)

	LogMessage("ReadArray(" & i & ") = " & CStr(ReadArray(i)))

Next

' Expected results:

' INFO : ReadArray(0) = 0

' INFO : ReadArray(1) = 1

' INFO : ReadArray(2) = 3

' INFO : ReadArray(3) = 5

' INFO : ReadArray(4) = 4294967295

関連項目

UserDataBlob.ByteArray UserDataBlob.Value UserDataItem.Value CustomProperty.BinaryData CustomProperty.AddParameter