<     > 

UserDataBlob

Object Hierarchy | Related C++ Class: UserDataBlob | Supported Parameter List: UserDataBlob

Inheritance

SIObject
   ProjectItem
       Property
          UserDataBlob

Introduced

3.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.

Although scripting does not support sending binary data as part of a COM interface, the binary data is represented as a string (a BSTR to be precise) so that you can access the data through scripting.

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

Properties

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

Autodesk Softimage v7.5     <     >