Object Model: UserDataBlob.Array32

UserDataBlob.Array32

Introduced

v9.0 (2011)

Description

Sets or returns binary user data on the UserDataBlob as a SafeArray of unsigned integers (32 bit). The preferred language for working with this property is Python.

This property provides better performance than the UserDataBlob.ByteArray property, especially when used with the Python scripting language and its array module. The Array32 property allows you to pack up to 4 unsigned bytes inside a single unsigned integer, so that there is less overhead when accessing or setting the data.

When setting this property, you must manually convert your unsigned byte array into an unsigned integer array using this schema: [,,], where represents the byte(s) you want to store, represents any null bytes you need to add in order to make this a valid 32-bit integer, and represents the number of null bytes you had append to the end of the data to make it a valid 32-bit integer.

When converting the return value to a byte array, you need to interpret the same schema: the first item of the array represents the number of null bytes padded to the byte array; the next item(s) represent the data plus any padding as indicated by the initial padding count. These requirements must be respected:

- the data is set and returned as a SafeArray of unsigned integers (32 bit); for Python, the recommended data structure is array.array('I') and for JScript, native arrays are accepted (Python and JScript arrays are internally converted to SafeArray objects)

- the first item in each unsigned integer array must be an integer in the range of 0-3 to describe the number of null bytes needed to pad in order to make the integer array valid

- each unsigned byte must be in the range of 0-255

- the value of each integer in the integer array should be in the 0-4294967295 range in order to preserve the data appropriately

- the returned value may appear unexpected for a given scripting language

Warning: Each element of the SafeArray is converted to four bytes internally; if such a conversion is impossible, setting the property fails and the data remains unchanged

Note: The data is copied internally and will be persisted as part of the scene. There are no limits to the size or structure of this data. Internally, the UserDataBlob.Value, UserDataBlob.ByteArray and the Array32 properties refer to the same data. However, for the sake of clarity, use only one or the other across your plug-in.

C# Syntax

// get accessor
Object rtn = UserDataBlob.Array32;
// set accessor
UserDataBlob.Array32 = Object;

Examples

1. Python Example

# 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 Example

// 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 Example

' 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