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

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

Properties

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

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

Autodesk Softimage v7.5