Public Member Functions
UserDataBlob Class Reference

Detailed Description

The UserDataBlob is a Property that 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 with "%UserDataBlob" as the preset name. Multiple UserDataBlobs can be stored on a single object and a UserDataBlob can be branch applied.

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, to save data that applies to a single vertex, use a UserDataMap; to save data that applies to all vertices in a cluster, use a UserDataBlob instead.

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

Example:
        using namespace XSI;

        Application app ;
        Model root = app.GetActiveSceneRoot();

        UserDataBlob myBlob ;
        root.AddProperty( L"UserDataBlob", false, L"udb", myBlob ) ;

        // This is the structure that we would like to save inside Softimage
        struct ExampleData
        {
            double x ;
            int    y ;
            int    z ;
        } ;

        // Save the structure
        ExampleData data ;
        data.x = 90.1 ;
        data.y = 12 ;
        data.z = 14 ;

        myBlob.PutValue( (unsigned char*)&data, sizeof( ExampleData ) ) ;

        // Retrieve the structure again
        unsigned char * pBuffer = NULL ;
        unsigned int cntBuffer = 0 ;

        myBlob.GetValue( pBuffer, cntBuffer ) ;

        // We can conveniently read the contents of the user data
        // by casting back to the structure
        ExampleData * pData = (ExampleData*)pBuffer ;

        // Update our structure based on what is already on the userdatablob
        data.x = 3.15 + pData->x ;
        data.y = 12 + pData->y ;
        data.z = 0 ;

        // Save our updated values
        myBlob.PutValue( (unsigned char*)&data, sizeof( ExampleData ) ) ;

#include <xsi_userdatablob.h>

Inheritance diagram for UserDataBlob:
Inheritance graph
[legend]

List of all members.

Public Member Functions

  UserDataBlob ()
  ~UserDataBlob ()
  UserDataBlob (const CRef &in_ref)
  UserDataBlob (const UserDataBlob &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
UserDataBlob operator= (const UserDataBlob &in_obj)
UserDataBlob operator= (const CRef &in_ref)
CStatus  GetValue (const unsigned char *&out_buffer, unsigned int &out_size) const
CStatus  PutValue (const unsigned char *in_buffer, unsigned int in_size)
bool  IsEmpty () const
void  Clear ()
unsigned int  Size () const

Constructor & Destructor Documentation

Default constructor.

Default destructor.

UserDataBlob ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.
UserDataBlob ( const UserDataBlob in_obj )

Copy constructor.

Parameters:
in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassID class type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from Property.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from Property.

UserDataBlob& operator= ( const UserDataBlob in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:
in_obj constant class object.
Returns:
The new UserDataBlob object.
UserDataBlob& operator= ( const CRef in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref constant class object.
Returns:
The new UserDataBlob object.

Reimplemented from Property.

CStatus GetValue ( const unsigned char *&  out_buffer,
unsigned int &  out_size 
) const

Provides access to the data inside the UserDataBlob. The out_buffer will be set to point to NULL if there is no user data on the object.

For performance purposes, the returned pointer points directly to internal Softimage data. The caller does not need to free this memory and should treat this data as read-only and potentially transitive. This pointer should not be held by the caller, and, if necessary, the data should be copied locally.

Return values:
out_buffer On return this will point to the user data, if any.
out_size Size, in bytes, of the buffer pointer to by out_buffer
CStatus PutValue ( const unsigned char *  in_buffer,
unsigned int  in_size 
)

Sets binary data on a UserDataBlob.

Note:
Binary user data should not contain any memory addresses or other information that is transitive.

Softimage will copy the provided buffer so that the caller does not need to maintain the provided data in memory.

Tip:
Passing 0 as the size is equivalent to calling UserDataBlob::Clear.
Parameters:
in_buffer Pointer to a buffer containing the user data
in_size Size, in bytes, of the buffer
bool IsEmpty ( ) const

Returns true if there is no data on the UserDataBlob. This is equivalent to testing is UserDataBlob::Size returns 0.

void Clear ( )

Removes any used data from the UserDataBlob.

Reimplemented from CBase.

unsigned int Size ( ) const

Returns the size, in bytes, of the data inside the UserDataBlob.


The documentation for this class was generated from the following file: