Scene Preprocessing

mi_scene_preprocess
mi_scene_postprocess
mi_scene_tesselate
miSCENE_PREPROCESS_CONTROL_INIT
miInh_func
miTraversal_func

Scene Preprocessing

Preprocessing prepares the scene DAG for rendering. After rendering completes, a postprocessing function reverses changes to the DAG done by preprocessing. Rendering must always be bracketed by preprocessing and postprocessing to convert the scene to a renderable format. None of these functions are normally used directly; use the mi_rc_run function instead which allows much better control over all stages of processing. These functions are deprecated and may disappear in future versions.

mi_scene_preprocess

miBoolean mi_scene_preprocess(
    miScene_preprocess *control)

Convert the scene DAG to a renderable representation, according to the instructions in the control structure. The control structure specifies the root group of the DAG, the camera instance, and other control parameters. Return miFALSE if preprocessing failed.

mi_scene_postprocess

void mi_scene_postprocess(
    miScene_preprocess *control)}

Undo the changes done by preprocessing, such as releasing allocated memory. The leaf instances and boxes stay intact. The control structure is expected to be unchanged from the preprocessing call.

mi_scene_tesselate

miBoolean mi_scene_tesselate(
    miScene_preprocess *control,
    miBoolean          lineboxes)

Build a list of leaf instances that reference triangle boxes (if lineboxes is miFALSE) or lineboxes (if lineboxes is miTRUE) for the scene given by the root group in control. This is similar to scene preprocessing, except that the scene graph is not touched in any way - no boxes are cached and no caches or dirty flags are used or changed. Object and instance visibility, shadow, and trace flags are ignored. The result of this call is a leaf instance list that the caller must release (by calling mi_scene_delete on each leaf instance). This function is intended for fast wireframe previews of small scene subsets with no internal instances, and for on-the-fly tessellation of geometry parameters of geometry shaders, but not for actual rendering. Return miFALSE if tessellation failed. Geometry shaders are not evaluated.

miSCENE_PREPROCESS_CONTROL_INIT

miSCENE_PREPROCESS_CONTROL_INIT(
    miScene_preprocess control)

This macro initializes the control structure with default values. All fields are zeroed, except the tessellate flag, which is set to miTRUE. The control structure has the following fields:

typedef struct {
      miTag         root_group;
      miTag         camera_inst;
      miTag         options;
      char          object_space;
      char          render_space;
      miCBoolean    spare[2];
      miBoolean     cache_boxes;
      miBoolean     delete_objects;
      miBoolean     tessellate;
      double        time;
      miPointer     inheritance_func;
      int           no_lights;
      int           no_leaf_insts;
      int           no_boxes;
      miTag         lights;
      miTag         leaf_insts;
      miTag         boxes;
} miScene_preprocess;

The first block must be set up by the caller of mi_scene_preprocess. The fields have the following function:

root_group is the tag of the root group of the scene DAG.
camera_inst is the tag of the camera instance to be used for rendering.
options is the tag of the rendering options.
object_space is one of 'w', 'c', or 'o', which informs the Scene module that objects coordinates are stored in world space, camera space, or object space, respectively.
render_space is either 'c' or 'o', which informs the Scene module that the renderer expects object coordinates to be in camera or object space, respectively. Scene will create matrices that transform the renderable geometry. object_space and render_space should agree. No geometry is changed, the space fields only control the way the leaf instance matrices are built.
cache_boxes has an effect only if object_coords is false. If it is true, the raw boxes resulting from tessellation of objects are retained and attached as cached untransformed boxes to the instance that refers to the object. Cached boxes are used when an object is found to need retessellation during preprocessing; retessellation is skipped and the cached copy is re-used. This speeds up preprocessing, but in the worst case the memory requirements for the scene are doubled.
delete_objects specifies that all geometric objects in the scene should be deleted during preprocessing. This can greatly reduce memory usage, but it means that all modified or transformed objects must be retranslated for the next frame. If the cache_boxes flag is also true, objects that are only retransformed but are otherwise unchanged need not be retranslated because thje cached untransformed boxes still exist (if they have not been destroyed by mi_scene_flushleaves).
tessellate specifies that the objects in the scene should be tessellated.
time is the time the scene tree is evaluated at. This field is passed to transformation functions when they are called.
inheritance_func is a inheritance function or traversal function provided by the caller that implements custom inheritance modes, as described below.

The second part of the control structure is set during preprocessing. The size and the head of the light list and the leaf instance lists are returned.

If used for mi_scene_tesselate, the following fields have no function and are ignored and not modified: cache_boxes, delete_objects, inheritance_func, no_leaf_insts, leaf_insts, no_lights, and lights.

miInh_func

typedef int (*miInh_func)(
    void               **result,
    void               *parent,
    int                parentsize,
    void               *child,
    int                childsize,
    struct miInstance  *parent,
    struct miInstance  *child,
    struct miMaterial  *mtl)

The inheritance function is used to combine parameter structures stored in the instances and called by mi_scene_postprocess. This function is expected to combine the user fields of the parent and child instances, and return the size of the result and a pointer to the result (which must be stored in *result). The function must use mi_mem_allocate for allocating the result; the Scene module will release the memory unless the returned result size is 0 or negative. The parent and child sizes are the sizes of the user field of the parent and child instances in bytes. Pointers to the parent and child DAG instances are also passed, as they are stored in the database, unmodified by scene preprocessing. Note that the inheritance mechanism never stores inherited parameters or transformations back into the DAG; all temporary results are held in local storage.

Finally, a pointer to a temporary material is passed. If the function writes a nonzero function tag into the material shader position of this material, raylib will store this material in the generated leaf instance, not the one inherited in the normal way. This gives the inheritance function control over individual material components, instead of inheriting complete monolithic materials.

The main purpose of preprocessing is the creation of the leaf instance list, which represents the renderable geometry. This leaf instance list has a similar function as the display lists found in systems like OpenGL: a flat list with resolved transformation matrices used for placing objects, lights, and cameras in the scene. They also make it unnecessary to modify the original scene graph in any way to prepare it for rendering. Leaf instance lists exist only between preprocessing and postprocessing; they are rebuilt for every frame.

miTraversal_func

It is recommended to replace inheritance functions with traversal functions. Inheritance functions can still be used but are deprecated; mental ray will assume inheritance function mode if the inh_is_traversal field in the options block is false and traversal function mode if the field is true. Traversal functions have this prototype:

typedef miBoolean (*miTraversal_func)(
    void              *data,        /* opaque this pointer */
    struct miInstance *parent,      /* previously inherited instance */
    struct miInstance *inst,        /* new instance to be inherited */
    miTag             *path,        /* path, begins with root group */
                                    /* and ends with curr DAG instance */
    int               pathlen)      /* number of tags in path[] */

The data pointer is always 0 if the traversal function was installed in the options block. If it was installed with mi_rc_run_traversal_cb, a constant opaque pointer may be defined.

The traversal function receives the previous instance parent (which is 0 at the top of the tree), the current instance found during traversal inst, the tag path path leading from the scene root group to the current instance, and the number pathlen of tags in path. The instances parent and inst are not scene DAG instances but temporary leaf instances created by mental ray. The inst instance is mental ray's proposal for the result of the inheritance, which can be overridden by the traversal function by altering inst's fields. The parent instance is the same pointer that was passed to the traversal function as inst one level up in the scene graph hierarchy; this can be used to implement top-down inheritance by overwriting fields in inst with fields from parent.

When traversal reaches the bottom of the scene graph hierarchy, the leaf instance passed to the last traversal function for this branch becomes the leaf instance used for rendering.