Instances and Instance Groups

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.

mi_api_instance_begin
    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.

mi_api_instance_end
    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.

mi_api_instgroup_begin
    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.

mi_api_instgroup_clear
    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.

mi_api_instgroup_additem
    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.

mi_api_instgroup_delitem
    miBoolean mi_api_instgroup_delitem(
        char            *name)     /* instance name */

After the instance group definition was begun, instances can be deleted from it.

mi_api_instgroup_end
    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