These functions establish relations between scene elements and keep reference counts. The link/unlink functions and the reference counts maintained by them are intended purely for maintaining multiple instancing. They are not general-purpose constructors that guarantee DAG consistency because they would then have to know about every tag in the scene, including shader parameter tags, and they would have to be granted a monopoly on tag manipulation. This was considered too restrictive.
The Scene module keeps reference counts for elements that define the DAG topology (groups, instances, objects, boxes, lights, and cameras) to make sure that they are deleted only when the last parent (instance, group, object, box, or function) is deleted. The fact that boxes have reference counts is not visible to the caller, it is done for Scene's own evil purposes. Other elements, such as lists attached to objects or shader parameters, keep no reference counts. For example, it is an error to reference the same polygon list in multiple objects because it would be deleted when one of these objects were deleted, leaving the other tag dangling. The Scene module does not keep backreferences, the caller is responsible for cleaning up tags that refer to the deleted element.
void mi_scene_link(
miTag ptag,
miTag ctag,
int which)
Linking creates a parent-child relationship; ctag is
linked to a new parent ptag. In the following table, there
is one row per target item with a list of items that can be
linked to it. A numerical digit means
mi_scene_link must be used
with for making the link, using the given number for the which
argument. M
means the tag is written manually, and −
means no such link can be made.
| ins | grp | cam | lig | mtl | fnc | dcl | box | obj | sub | |
|---|---|---|---|---|---|---|---|---|---|---|
| instance | − | 0 | 0 | 0 | − | 0 | − | 0 | 0 | − |
| group | 0 | − | − | − | − | − | − | − | − | − |
| camera | − | − | − | − | − | M | − | − | − | − |
| light | − | − | − | − | − | M | − | − | − | − |
| material | − | − | − | − | − | M | − | − | − | − |
| func | − | − | − | − | − | M | 0 | − | − | − |
| func decl | − | − | − | − | − | − | − | − | − | − |
| box | − | − | − | − | M | − | − | 0 | − | − |
| object | − | − | − | − | M | − | − | M | − | M |
| sub-object | − | − | − | − | − | − | − | − | − | M |
Links to substructures of objects (called sub-objects: polygons, faces, curves, scalar lists, bases etc.) are always written manually. So are tags written into shader parameters. Links to instances attach a child, not a parent, except for functions which are taken to be the transformation function. miConnects must be created manually.
Warning: linking a tag to a group may change the address of the group item in memory. A pointer to the group acquired with mi_db_access may become invalid. SCENE will print a warning using mi_debug in this case.
void mi_scene_unlink(
miTag gtag,
miTag otag,
int which)
This call undoes the link created by a call to mi_scene_link with the same arguments. Only the gtag element is affected, nothing is deleted.
void mi_scene_delete(
miTag tag)
Deletes the database element tag, provided that its reference count is 0 or less. The reference count of an element is incremented when it is linked to another element using mi_scene_link, and decremented when it is detached from another element using mi_scene_unlink.
If the element contains certain types of sub-tags that define the tree topology, these sub-tags are deleted recursively. This includes leaf instances and their child elements. Function declarations, materials, lights, images, and cameras are exempt; they are never deleted during recursion. If a function (or a material referencing a function) is deleted, the function parameters are not scanned for tags. Neither are group connection lists because connections may only specify children of the same group, which are deleted recursively.
The following table contains one row per element type to be
deleted. Each D
in a row means that if the element named in
the leftmost column is deleted, the sub-element corresponding to
the column with the D
or d
is recursively deleted, too.
Again, sub-objects are geometric structures referenced by
objects, such as polygons, faces, bases etc.
| ins | grp | cam | lig | mtl | fnc | dcl | box | obj | sub | |
|---|---|---|---|---|---|---|---|---|---|---|
| instance | − | d | d | d | − | D | − | D | d | − |
| group | d | − | − | − | − | − | − | − | − | − |
| camera | − | − | − | − | − | − | − | − | − | − |
| light | − | − | − | − | − | − | − | − | − | − |
| material | − | − | − | − | − | − | − | − | − | − |
| func | − | − | − | − | − | − | D | − | − | − |
| func decl | − | − | − | − | − | − | − | − | − | − |
| box | − | − | − | − | − | − | − | D | − | − |
| object | − | − | − | − | − | − | − | D | − | D |
| sub-object | − | − | − | − | − | − | − | − | − | − |
void mi_scene_delete_one(
miTag tag)
This function is equivalent to the standard delete function
above, but if a group is deleted, the group members are not
deleted recursively, and if an instance is deleted, the instance
is not deleted recursively. That is, in the above table only
D
tags are recursively deleted, but not d
tags. This is
used for the delete statement in the mi2 scene
format.