v9.0 (2011)
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: [
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.
// get accessor Object rtn = UserDataBlob.Array32; // set accessor UserDataBlob.Array32 = Object; |
# 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! |
// 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 |
' 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 |