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:
[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

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