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:

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

UserDataBlob

(

)

Default constructor.

~UserDataBlob

(

)

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:

• xsi_userdatablob.h