• home
• « prev
• next »
• index

• mi_scene_create
• mi_scene_recreate
• mi_scene_edit
• mi_scene_growedit
• mi_scene_edit_end
• mi_scene_check
• mi_scene_check_all
• mi_scene_dump
• mi_scene_type_name

Database Element Management

mi_scene_create

void *mi_scene_create(
    miTag           *tag,
    miScene_types   type, ...)

creates a database element of a specified type, and provides defaults. For database elements that have a variable size, one or more arguments specify the sizes of the variable sections. There are no arguments to store specific values in the new database elements; instead, a pointer is returned that can be used to fill in the data. The tag of the new element is also returned. mi_scene_create always returns a valid pointer; allocation errors abort with mi_fatal. If the created element is an instance or an object, set its dirty flag.

mi_scene_recreate

void *mi_scene_recreate(
    miTag           *tag,
    miScene_types   type, ...)

This function is equivalent to mi_scene_create, but it expects tag to point to a valid tag number. The item will be deleted, and the new item will be created with this tag instead of choosing a new tag. This function is used for some types of incremental changes.

mi_scene_edit

void *mi_scene_edit(
    miTag           tag)

If the database element must be changed (as part of an incremental change), this call must be used to obtain a pointer to it. The DB call mi_db_access may not be used for this purpose, because Scene needs to keep track of edited elements to properly preprocess them before rendering starts. mi_scene_edit always returns a valid pointer; allocation errors abort with mi_fatal. If the edited element is an instance or an object, set its dirty flag.

mi_scene_growedit

void *mi_scene_growedit(
    miTag           tag, ...)

This call is a variation of mi_scene_edit. It is used instead of mi_scene_edit if the modification requires an increase or decrease of the size of one of the sections of a variable-sized element. The size arguments have the same order as the arguments given in the mi_scene_create call. After the edit is complete, mi_scene_edit_end must be called. mi_scene_growedit always returns a valid pointer; allocation errors abort with mi_fatal. Note that resizes are inefficient and should be avoided. If the edited element is an instance or an object, set its dirty flag.

mi_scene_edit_end

void mi_scene_edit_end(
    miTag           tag)

After the incremental change of an element has completed, this function completes the edit. The pointer returned by mi_scene_edit is invalidated. Scene handles all pinning, flushing, and updates of expanded DAG elements (see functions in group 2).

Note that there are special Scene functions for accessing database elements that need to be written to, but no functions to access elements that are only read. For reading, the standard mi_db_access and mi_db_unpin functions are used. It is very inefficient to use mi_scene_edit for read-only accesses, and illegal to use mi_db_access for write accesses. There is no need to ever call mi_db_flush, this call is for use by the Scene module only.

Note also that the element delete function is in group 2, because it recursively deletes the subtree.

The Scene module supports the following types, defined by the miScene_types enumerator:

There are several additional codes that are used by mental ray internally for temporary cached data. When one of these database element types is created or resized, the size must be given as a varargs list that depends on the type:

[1] The parmsize parameter assumes that the shader has no ghost parameter block. To add such a block, pass a size twice as large as needed for the parameters, and adjust the parameter_size field in the created or resized miFunction afterwards.

[2] The type specifies the type (and hence the size) of the primitives of the box. Allowed values are miBOX_TRIANGLES and miBOX_ALGEBRAICS. Although vect and vert are stored in the box when creating or resizing, only vect→no_vectors and vect→sizeof_vertex are used for calculating the box size. Resizing a box does not shift box sections; the box contents except the header remain unchanged.

[3] The user bytes are intended for parameter information that is inherited down the DAG, either by default or by an inheritance function or traversal function provided by the scene.

[4] The nlinks and nconnects parameters are hints only. If more children are added with mi_scene_link, the Scene module will resize the group automatically if necessary. However, resizes are inefficient and should be avoided by giving an approximate number of links when creating the group.

mi_scene_check
mi_scene_check_all

miBoolean mi_scene_check(
    miTag           tag)

void mi_scene_checkall(
    miTag           tag)

Do consistency check of a database element, and print mi_debug messages for every problem found. If no problems are found, miTRUE is returned. The mi_scene_check function checks only the given element, while the mi_scene_checkall function recursively checks all sub-elements too. If a database element of type miObject is checked, all geometric sub-elements linked to the object (faces, surfaces, curves, bases, and polygons) are also checked because the check can be much more thorough if the cross-dependencies (such as index bounds) can also be checked. This function can be slow and should be used only for debugging.

mi_scene_dump

miBoolean mi_scene_dump(
    miTag           tag,
    int             verb)

Print a recursive dump of the database graph beginning at tag, using the mi_info message printing function (which means that the verbosity level must be at least 4). The verbosity verb ranges from 0 to 4, printing progressively more information. This function is useful for debugging.

mi_scene_type_name

char *mi_scene_type_name(
    miScene_types   type)

Return the name of a SCENE data type. For example, when passed the type miSCENE_OBJECT, it returns the string "object". The returned string may not be written to, and need not be released (it points to a static array). This function is useful when writing debugging code or error messages.

• home
• « prev
• next »
• index