Instances and instance groups are used to construct the scene DAG (directed acyclic graph). Instance groups are unordered lists of one or more instances. Instances are nodes of the DAG, they reference an item to be placed into the DAG together with a space transformation, optional inheritance parameters, and various flags. Elements that can be referenced by instances are geometric objects, cameras, lights, and instance groups. If more than one instance references the same item, this is called multiple instancing.
miInstance *mi_api_instance_begin(
char *name) /* instance name */
Begin the definition of an instance with the given name. In incremental mode, a pointer to the existing instance is returned; otherwise a pointer to a temporary instance is returned. It is not necessary to store the various flags and IDs in the instance transformation, this is done during preprocessing.
miTag mi_api_instance_end(
char *item, /* item to instance */
miTag function, /* geometry shader */
miTag params) /* transformation func */
Complete the definition of the instance. If the instanced item is not a geometry shader, the item to be instanced is given by item and function must be a null tag. If the instanced item is a geometry shader, the function list is passed in function and item must be a null pointer. It is an error if both item and function are requested to be instantiated. Incremental changes from regular to geometry shader instances and vice versa are possible.
The params tag is either the null tag (no inheritance parameters), the numerical value -1 (leave parameters unchanged during an incremental change), or the tag of a function containing inheritance parameters. Only the parameters are used, the function is ignored. The function should be deleted after being passed to mi_api_instance_end.
If an error occurs, a null tag is returned; otherwise the tag of the new instance element is returned. The type of the returned element is miSCENE_INSTANCE.
miBoolean mi_api_instgroup_begin(
char *name) /* group name */
Begin the definition of an instance group with the given name. The list of elements is not cleared even if incremental mode is disabled.
miBoolean mi_api_instgroup_clear(void)
After the instance group definition was begun, all its instances references can be cleared with this call, as if mi_api_instgroup_delitem had been called for every one of them.
miBoolean mi_api_instgroup_additem(
char *name) /* instance name */
After the instance group definition was begun, instances can be added to it. The order of the instances being added is irrelevant. Only instances can be added, never elements such as geometric objects directly.
miBoolean mi_api_instgroup_delitem(
char *name) /* instance name */
After the instance group definition was begun, instances can be deleted from it.
miTag mi_api_instgroup_end(void)
After all instances have been added to the instance group, this call completes the creation of the instance group. If an error occurs, a null tag is returned; otherwise the tag of the new instance group element is returned. The type of the returned element is miSCENE_GROUP.
Copyright © 1986-2010 by mental images GmbH