Sometimes large amounts of opaque data must be entered into the scene that cannot be efficiently handled with shader parameters. For example, shaders may need large amounts of particle data. For this purpose, user data blocks can be defined. A user data block consists of a header describing the data block, and the data itself. User data blocks are named.
miUserdata *mi_api_data_begin(
char *name, /* name of user data block */
int type, /* 0=literal, 1=file, 2=declared */
void *parm) /* type 0:size, 1:filename, 2:decl */
Begin the definition of a user data block named name. Its contents can be defined in three different ways: if type is 0, the data must be copied verbatim with mi_api_data_copy (see below); if type is 1, the data is read from a file; and if type is 2, the data is defined similar to regular shader parameters. This last mode is useful if the data block itself is not large but shared among a large number of shaders or other elements. In mode 0, parm is an integer specifying the number of bytes to be stored. In mode 1, parm is an allocated string that specifies the file name to load from. In mode 2, parm is the tag of a function that the parameters will be taken from (this works exactly like the params argument of the mi_api_instance_end function except that the declaration can, but doesn't have to, be of type miFUNCTION_DATA). This function returns a pointer to the new user data block, which lets the caller set up the miUserdata header.
miTag mi_api_data_end(void)
Complete the definition of the user data block, and return its tag.
miTag mi_api_data_append(
miTag front, /* list to append to */
miTag back) /* list to append */
Append the back user data block list to the front user data tag list, and return the first tag of the concatenated list. Either or both lists may be empty ( front and/or back is a null tag). User data block concatenation works the same way as shader list concatenation.
miBoolean mi_api_data_byte_copy(
int len, /* number of bytes */
miUchar *bytes) /* bytes from the mi file */
Append the given number of bytes to the user data block. This must be called between mi_api_data_begin and mi_api_data_end if the type of the user data block is 0. It may be called zero or more times, and the sum of all len arguments may not exceed the user data block size specified in the begin call. If this function may not be called for type 1 or 2 blocks, it overwrites data from the file or parameters.
miTag mi_api_data_lookup(
char *name) /* data block name to look up */
Look up the user data block with the given name, and returns its tag. If the database element with that name is not a user data block, or if the name is unknown, an error is printed and a null tag is returned.
Copyright © 1986-2009 by mental images GmbH