UserDataBlob

Object Hierarchy | Related C++ Class: UserDataBlob

Inheritance

SIObject

ProjectItem

Property

UserDataBlob

Introduced

v3.5

Description

The UserDataBlob is a Property which can be attached to many different parts of a scene, for example Cameras, Lights, other X3DObjects and Clusters. It allows a plug-in to read, write and persist binary user data as part of a scene.

A UserDataBlob is created by calling SceneItem.AddProperty. Multiple UserDataBlobs can be stored on a single object and a UserDataBlob can be branch applied.

The contents of a UserDataBlob can be pushed into Mental Ray. Context information needed by the shader can be stored in the UserDataBlob and then retrieved throught the Mental Ray user data API. This feature is only available when the UserDataBlob is nested directly under a Camera, Light or X3DObject. The Parameter named "RenderData" should be set to True and the "UserDataID" parameter set to the Mental Ray user data tag value that the shader expects. Real-Time shaders do not need this data pushed to them because it is possible for them to read the contents of a UserDataBlob directly through the C++ API.

For C++ developers, the easiest and most efficient way to access the binary data on a UserDataBlob is to use the C++ API (see xsi_userdatablob.h) rather than this COM Object Model interface.

This object can be thought of as a "low-level" alternative to the CustomProperty object, which does not support binary data. The UserDataMap is similar to the UserDataBlob, but supports storing per-component binary data rather than object level binary data. For example, if some user data is meant to apply to every point in a vertex cluster then it should be stored in a UserDataBlob, whereas, if the user data is meant to apply only to a single vertex, it should be stored at the correct index in a UserDataMap.

Methods

AddCustomOp AddICEAttribute AddScriptedOp AddScriptedOpFromFile
AnimatedParameters2 BelongsTo operator Clear operator EvaluateAt
GetICEAttributeFromName IsA IsAnimated2 IsClassOf operator
IsEqualTo operator IsKindOf IsLocked operator IsSelected operator
LockOwners RemoveICEAttribute SetAsSelected operator SetCapabilityFlag operator
SetLock TaggedParameters UnSetLock  
       

Properties

Application Array32 operator Branch operator BranchFlag operator
ByteArray operator Capabilities operator Categories EvaluationID
Families operator FullName operator Help HierarchicalEvaluationID
ICEAttributes IsEmpty operator LockLevel operator LockMasters operator
LockType operator Model Name operator NestedObjects
ObjectID Origin OriginPath Owners
PPGLayout operator Parameters operator Parent Parent3DObject
Selected operator Singleton operator Size operator Type operator
Value operator      
       

Examples

1. VBScript Example

'Example of the UserDataBlob
'Store some user data directly under the scene root
set oBlob = ActiveSceneRoot.AddProperty( "UserDataBlob", , "data" )
'Save a string.  Because strings are represented as widecharacters
'this takes 12 bytes on Windows and 24 bytes on Linux
oBlob.Value = "xyz123"
logmessage oBlob.fullname & " is storing this string: " & oBlob.Value & _
				 " which takes " & oBlob.Size & " bytes."
'Flush that user data
ActiveSceneRoot.Properties( "data" ).Clear

2. JScript Example

//Example of UserDataBlob
//Place the blob on a null
var oNull = ActiveSceneRoot.AddPrimitive( "Null" ) ;
var oBlob1 = oNull.AddProperty( "UserDataBlob", false, "nulldata" ) ;
oBlob1.Value = "xyz123" ;
var oBlob2 = oNull.AddProperty( "UserDataBlob", false, "emptynulldata" ) ;
//Find all UserDataBlobs on the object and print out their values
var e = new Enumerator( oNull.Properties ) ;
var item ;
for ( ;!e.atEnd();e.moveNext() )
{
	item = e.item();
	if ( item.Type == "UserDataBlob" )
	{
		if ( item.IsEmpty )
		{
			logmessage( "Found empty UserDataBlob called " + item.Name );
		}
		else
		{
			logmessage( "Found user data blob called " + item.Name + 
						  " with value " + item.Value );
		}	 
	}	
}

See Also

UserDataMap CustomProperty