v3.5

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.

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 );
                }        
        }       
}

UserDataMap CustomProperty