User Data

Element type:	miSCENE_USERDATA
Data type:	miUserdata
Sizes:	int parameter_size
Defaults:	all nulls

typedef struct miUserdata {
        miTag           data_decl;              /* parameter declaration */
        miTag           next_data;              /* next data block in list */
        miUint          label;                  /* user-defined label integer*/
        int             parameter_size;         /* size of parameter block */
        short           one;                    /* ==1, for byte order check */
        short           spare1;                 /* not used */
        int             spare2;                 /* not used */
        char            parameters[8];          /* parameter block */
} miUserdata;

This element describes a user-definable opaque data block. The API supports setting up these blocks from literal data, from a file, or from shader-like declared parameters. The purpose is carrying user data to shaders that would be too large, contain nonstandard data types, or be repeated in too many places to make storing it as shader parameters feasible. Except in the shader-like parameter case, the data is not byte-swapped by mental ray when transported to another host; this becomes the responsibility of the data recipient.

data_decl is the tag of the declaration of the parameters, if the user data block is defined with parameters. If it was defined with literal data or read from a file, this field is a null tag.

next_data allows chaining of user data blocks, much like shaders can be chained.

parameter_size is the number of bytes stored in this data block, beginning at parameters. The rest of the header leading up to the data is not included. Zero is allowed but not useful. mental ray warns if a data block is defined larger than 16 MB.

one is set to 1 when the data block is defined, and when it was defined with parameters and has been imported and byte-swapped. Since literal and file user data blocks are not swapped, the data recipient must assume that non-byte data read from the user data block must be byte-swapped if one has the value 0x0100 instead of 1.

parameters contains the user data. Although declared with only eight characters, it is allocated smaller or larger depending on the user data block size such that it holds parameter_size bytes.