Tessellation and Rendering (RC)

mi_rc_run
mi_rc_run_query
mi_rc_run_traversal_cb
mi_rc_set_taskorder

Tessellation and Rendering (RC)

mi_rc_run

#define miRENDER_PREPROC             0x000001
#define miRENDER_OBJ_DELETE          0x000002
#define miRENDER_SHADOWMAP           0x000004
#define miRENDER_DISPLAY             0x000008
#define miRENDER_RENDER              0x000010
#define miRENDER_FB_SAVE             0x000020
#define miRENDER_FB_RESTORE          0x000040
#define miRENDER_FB_DELETE           0x000080
#define miRENDER_OUTPUTSH            0x000100
#define miRENDER_POSTPROC            0x000200
#define miRENDER_IMAGE_DELETE        0x000400
#define miRENDER_CHECK               0x000800
#define miRENDER_DUMP                0x001000
#define miRENDER_ACCEL_DELETE        0x002000
#define miRENDER_LIGHTMAP            0x004000
#define miRENDER_REINHERIT           0x008000
#define miRENDER_POSTPROC_FBC        0x010000
#define miRENDER_DISPLAY_FG          0x020000
#define miRENDER_RENDER_FG           0x040000
#define miRENDER_RENDER_PM           0x080000
#define miRENDER_LIGHT_ACCEL_DELETE  0x100000
#define miRENDER_REINHERIT_LIGHTS    0x200000

#define miRENDER_DEFAULT             0x00471f
#define miRENDER_SHADOWMAP_ONLY      0x000207
#define miRENDER_FG_ONLY             0x044607
#define miRENDER_PM_ONLY             0x084603
#define miRENDER_LIGHTMAP_ONLY       0x004607

miBoolean mi_rc_run(
    miUint          mode,
    int             imgpipe,
    unsigned int    prevmask,
    miTag           root_group,
    miTag           c_inst_tag,
    miTag           camera_tag,
    miTag           option_tag,
    miInh_func      inh_func)

This is the main entry point of the renderer. It handles preprocessing, rendering, output shading, postprocessing, and realtime image previews. It is basically a wrapper around the main rendering engine, and also handles all setup and cleanup. The following arguments must be passed:

mode: A bitmap that enables or disables the various stages of tessellation and rendering. See below. The mode bitmap is ignored in cut window mode.
imgpipe: If set to a nonzero file descriptor, completed image rectangles are sent to this file descriptor in a format that the imf_disp tool can display. This implements the -imgpipe command-line option of mental ray. It is useful for real-time previews of rendering but may slow down rendering in relay library applications where the pixel data must be sent across the network. This argument is ignored if the mode mask does not specify rendering or displaying ( miRENDER_RENDER plus miRENDER_DISPLAY).
prevmask: This mode implements pixel previewing, if enabled by the preview_mode flag in the options block. It is a 32-bit mask that specifies which shaders have changed their parameters since the scene was last rendered. Each shader has a label field in its miFunction definition, which determines the bit position in prevmask, modulo 32. For example, if the parameters of shaders 10, 42, and 117 changed, then bits 10 (10 and 42 module 32) and 21 (117 modulo 32) must be set in prevmask. The renderer uses this information to determine which pixels must be rerendered. If pixel previewing is not enabled, or if the mode mask does not specify rendering, 0 should be passed.
root_group: The tag of the root group of the scene. This and the following four arguments can be obtained from the mi_api_render_params function, which picks them up from a previous mi_api_render call.
c_inst_tag: The tag of the camera instance of the scene. It must be present in the root group also.
camera_tag: The tag of the camera of the scene.
option_tag: The tag of the options of the scene.
inh_func: The inheritance function of the scene, or 0 if there is none. If the inh_is_traversal field in the options is set, then inh_func is the traversal function instead of the inheritance function.

The following bits may be added to form the mode argument (listed in typical use order, related bits are grouped together) :

bit	function
`miRENDER_PREPROC`	pre-process full scene
`miRENDER_OBJ_DELETE`	delete source geometry
`miRENDER_REINHERIT`	pre-process only geometry material inheritance
`miRENDER_REINHERIT_LIGHTS`	pre-process only light inheritance
`miRENDER_CHECK`	debugging: check scene
`miRENDER_DUMP`	debugging: dump to stdout
`miRENDER_SHADOWMAP`	render shadow maps
`miRENDER_RENDER_FG`	render final gather maps
`miRENDER_RENDER_PM`	render photon maps
`miRENDER_LIGHTMAP`	compute light maps
`miRENDER_RENDER`	render images
`miRENDER_DISPLAY`	tile display callbacks, connections to imf_disp or imgpipe
`miRENDER_DISPLAY_FG`	coarse display of final gather progress prior to tiles
`miRENDER_FB_SAVE`	make a copy of the frame buffers
`miRENDER_FB_RESTORE`	restore frame buffer copy
`miRENDER_FB_DELETE`	delete frame buffer copy
`miRENDER_OUTPUTSH`	call output shaders
`miRENDER_IMAGE_DELETE`	delete result frame buffers
`miRENDER_ACCEL_DELETE`	delete internal caches
`miRENDER_LIGHT_ACCEL_DELETE`	delete light caches
`miRENDER_POSTPROC`	scene post-processing
`miRENDER_POSTPROC_FBC`	delete tessellation during post-processing

miRENDER_PREPROC: Pre-processing traverses the entire scene graph. It builds a leaf instance list, which contains one newly allocated instance for each geometric object in the scene, and all its flags and transformation matrices compounded and inherited from the instances in the scene graph. If an object or light is multiply instanced, it will have multiple instances in the leaf instance list. All geometry shaders that are found during traversal are called to produce scene elements to be added to the leaf instance list. Pre-processing is required whenever the scene geometry changed, either because object geometry changed or because instances or groups that place them into the 3D world changed. Pre-processing is not necessary if only shader parameters change.; Pre-processing also tessellates all objects that have not been previously tessellated, and whose tessellation cannot be shared with another instance of the same object. The preprocessor manages caches and "dirty bits" to determine which objects need tessellation. Note that displacement mapping is not taken into account - if a displacement shader is added, removed, or changed, directly or indirectly through inheritance or shader or phenomenon assignment, or if the displacement shader has other external dependencies, this does not cause re-tessellation. The application should use mi_api_touch, mi_db_touch, or directly mi_scene_edit and mi_scene_edit_end on the object to force re-tessellation in this case. Note that pre-processing does not in any way change the scene graph (other than manipulating dirty flags), it only creates additional information.
miRENDER_OBJ_DELETE: This bit forces deletion of the source geometry of all objects after tessellation. Source geometry includes polygons, free-form surfaces, and subdivision surfaces that require tessellation into triangles in order to be rendered. Since rendering does not need the source geometry, this flag allows deleting it to conserve memory. This is a sub-mode of preprocessing, and it has no effect if miRENDER_PREPROC is not set.
miRENDER_REINHERIT: This mode may be used only between frame renders, with no intervening post-processing and pre-processing. It re-evaluates material and parameter inheritance as post-/pre-processing would but without its overhead, and without re-ccreating the BSP tree and other acceleration data. It is useful for rapid incremental rendering of a scene in situations where instance parameters and instance materials change, but not the scene topology or any other instance fields (especially transforms and flags).
miRENDER_REINHERIT_LIGHTS: This mode is similar to the previous full scene inheritance mode but this time only processing lights. Therefore, it is useful for quick incremental renderings when changes are applied only to the lights in the scene.
miRENDER_CHECK: After preprocessing and before shadow mapping and rendering, traverse the scene and perform consistency checks. This mode is independent of all others and can be used at any time and without other mode bits set. It is intended for application debugging.
miRENDER_DUMP: After preprocessing and before shadow mapping and rendering, traverse the scene and print the scene graph in a human-readable compressed form that provides a quick overview over the scene graph hierarchy. The verbosity level should be at least 3 (see mi_set_verbosity and miERR_INFO). This mode is also independent of all others and can be used at any time and without other mode bits set. It is intended for application debugging.
miRENDER_RENDER_FG: Perform final gather pre-computing. For backwards compatibility reasons, this flag is implicitly turned on if the miRENDER_RENDER flag is set. It is still useful to perform final gather preprocessing without rendering.
miRENDER_RENDER_PM: Pre-compute photon maps. For backwards compatibility reasons, this flag is implicitly turned on if the miRENDER_RENDER flag is set. It is still useful to compute photon maps without rendering.
miRENDER_LIGHTMAP: If the scene contains lightmap shaders, this flag enables calling them. If the flag is not set, lightmap shaders are ignored. This is useful to render only the light maps in a first pass, and later render the scene in a second pass where the generated lightmap images are used but not recomputed.
miRENDER_RENDER: Render the scene. The scene must have been pre-processed either in this or some previous call to mi_rc_run. This bit is ignored if miRENDER_FB_RESTORE is also set because in this case the rendering result would be immediately overwritten from the saved frame buffers.
miRENDER_DISPLAY: If set, rendered image rectangles are sent in realtime to connected display targets, either to the file descriptor specified by the imgpipe argument if nonzero, or to a socket opened by another program such as the imf_disp viewer via connection through the 128-byte stub output file. The imgpipe descriptor takes precedence over an external socket connection. This bit has no effect unless miRENDER_RENDER is also set. mental ray is able to feed multiple different display connections at a time.
miRENDER_DISPLAY_FG: If set along with miRENDER_DISPLAY, indirect light computed by final gathering pre-processing is shown as if it were rendered rectangles. Display is very coarse because at that stage no refinement and filtering is done, but it gives an indication of pre-processing progress. It is not on by default because it slows down pre-processing and consumes extra memory for the pixels sent to the viewer.
miRENDER_FB_SAVE: Save all frame buffers between rendering and calling the output shaders. Since output shaders generally overwrite the frame buffers, this preserves a clean copy that later allows re-running the output shaders without re-rendering first. If there are already saved frame buffers, the old saved frame buffers are deleted first. The three frame buffer mode bits are designed to support fast output shader tuning. Note that pixel previewing using prevmask does not apply to output shading because output shaders, by definition, always operate on all pixels.
miRENDER_FB_RESTORE: Restore previously saved frame buffers. This bit is ignored if miRENDER_FB_SAVE is also set because that would imply a redundant copy.
miRENDER_FB_DELETE: Delete previously saved frame buffers. This bit is ignored if miRENDER_FB_SAVE is also set. This should be done before (or together with) post-processing to free up the memory used by the saved frame buffers, which may be very large.
miRENDER_OUTPUTSH: Call the output shaders on the frame buffers created either by rendering or a frame buffer restore operation. This generally changes the frame buffers but leaves the saved frame buffers intact. Output shading includes writing to output files, unless explicitly disabled by the appropriate bits in the no_output flag in the options.
miRENDER_IMAGE_DELETE: Delete the result images stored in frame buffers. Normally, the result frame buffers are passed through output shaders and written to files as specified by the output settings in the camera, and then deleted after post-processing before mi_rc_run returns. If this flag is cleared, the image frame buffers are not deleted and are accessible with mi_rc_run_query after mi_rc_run returns.; It is important to delete the image buffers explicitly with a call to mi_rc_run with mode miRENDER_IMAGE_DELETE (and probably no other flags) before the next rendering operation because they are leaking otherwise (that is, mi_rc_run and mi_rc_run_query will not delete them, and will no longer be able to find them because their internal image tag list is overwritten). Note, that pixel preview mode also retains the frame buffers, and implicitly ignores the miRENDER_IMAGE_DELETE mode if set.
miRENDER_POSTPROC: Postprocess the scene. This involves deleting the leaf instance list and all temporary objects created by geometry shaders. Note that output shaders should always be called between pre-processing and post-processing, not outside this bracket, because they might access information such as the modified camera or object or light data that is no longer available after post-processing. Note, that pre-processing does not implicitly post-process; it must always be done explicitly. There should always be one post-processing step for every pre-processing step. Various data may survive this step and need to be cleaned-up explicitly with additional _DELETE bits.
miRENDER_POSTPROC_FBC: Post-process the geometry cache (flush box cache) for non-view dependent geometry and delete its tessellation data. This is a sub-mode of post-processing, and it has no effect if miRENDER_POSTPROC is not set. For fast turnaround times in incremental renderings it is desirable to re-use tessellation for geometry that is not changing its appearance between frames. Any view-dependent geometry is handled separately by mental ray, and will be re-tessellated upon camera changes automatically.
miRENDER_ACCEL_DELETE: Rendering accumulates various data structures that stay around after rendering completes, because they would have to be re-computed for the next frame otherwise. This currently comprises only expensive global illumination and final gather caches (in memory but not files on disc). If it is known that there will be no frame rendering for a while, and the application needs room for other purposes, it can tell mental ray to delete such data by setting this flag. It is independent of any other flag.
miRENDER_LIGHT_ACCEL_DELETE: The lights in the scene are pre-processed and cached for optimized performance and access in shaders. This mode explicitly deletes the cache, thus enforces that it gets rebuilt upon next rendering if needed. This may be used in cases where individual lights or their leaf instances have been manipulated directly, and just the cache needs to be updated for rendering avoiding a full post-/pre-processing cycle.

For convenience, these bitmaps are pre-defined for common use:

bitmap	function
`miRENDER_DEFAULT`	standard rendering and output shading
`miRENDER_SHADOWMAP_ONLY`	render only shadow maps
`miRENDER_FG_ONLY`	render only final gather maps
`miRENDER_PM_ONLY`	render only photon maps
`miRENDER_LIGHTMAP_ONLY`	render only light maps

Examples

The following code samples show several use cases for the mode bitmap:

mi_rc_run(miRENDER_DEFAULT, ...);

This is what the standalone mental ray executable uses. It pre-processes, renders, and post-processes. mental ray is then ready to repeat the process for the next frame.

mi_rc_run(miRENDER_PREPROC +
          miRENDER_OBJ_DELETE, ...);

...	/* use the tessellated geometry */

mi_rc_run(miRENDER_POSTPROC, ...);

This combination is useful to tessellate a scene (or, more commonly, a sub-graph of the scene) and then making use of the result of the tessellation for wireframe or hardware-shaded displays. Note that even though mental ray does not render, it is still necessary to define a camera and its instance, and adding the instance to the root group passed to mi_rc_run, because view-dependent approximations during preprocessing need to know where the tessellated geometry is in 3D space with respect to the camera.

mi_rc_run(miRENDER_PREPROC    +
          miRENDER_OBJ_DELETE +
          miRENDER_SHADOWMAP  +
          miRENDER_LIGHTMAP, ...);

mi_rc_run(miRENDER_DISPLAY  +
          miRENDER_RENDER   +
          miRENDER_OUTPUTSH +
          miRENDER_IMAGE_DELETE, ...);

...	/* more mi_rc_run calls */

mi_rc_run(miRENDER_POSTPROC, ...);

Here, the scene is pre-processed once, and then rendered one or more times, and then post-processed. Rendering multiple times inside the pre-/post-process bracket is useful for shader parameter tuning. The middle call to mi_rc_run may be repeated every time the user has changed a shader parameter, for example to tune a material color. This works very well with shader previewing, which lets mental ray re-render only those pixels that might be affected by the change. Note, that this example cannot deal with scene graph changes - it keeps rendering the leaf instance list created by the first call to mi_rc_run and assumes that it is still valid, and no objects have been changed, added, or deleted.

mi_rc_run(miRENDER_PREPROC    +
          miRENDER_OBJ_DELETE +
          miRENDER_SHADOWMAP  +
          miRENDER_LIGHTMAP   +
          miRENDER_RENDER     +
          miRENDER_FB_SAVE    +
          miRENDER_OUTPUTSH   +
          miRENDER_IMAGE_DELETE, ...);

mi_rc_run(miRENDER_FB_RESTORE +
          miRENDER_OUTPUTSH, ...);

...	/* more mi_rc_run calls */

mi_rc_run(miRENDER_FB_DELETE +
          miRENDER_POSTPROC, ...);

This example is similar to the previous except that only the output shaders and not the entire rendering operation are tuned. If the user wants to tune parameters of the output shaders attached to the camera, it would be inefficient to re-render every time to recreate the images that the output shaders operate on. Instead, the scene is rendered only once and then saved to the save frame buffers before calling the output shaders for the first time. After that, the save frame buffers are simply restored before calling the output shaders again. Finally, when tuning has finished, the save frame buffers are deleted and the scene is post-processed.

Obviously, all these fragments are incomplete: no return code is checked, and no calls to mi_par_aborted exist between the various calls to mi_rc_run that could stop the render loop if the user has pressed a Cancel or Abort button. Also, before mi_rc_run can be called for the first time, a scene must have been constructed using mi_api_* calls.

The following pseudocode describes the operation of mi_rc_run:

    if (miRENDER_PREPROC) {
            preprocess;
    } else {
        if (miRENDER_REINHERIT)
            scene_reinherit;
        if (miRENDER_REINHERIT_LIGHTS)
            lights_reinherit;
    }

    if (miRENDER_DUMP)
            scene_dump(root_group);

    if (miRENDER_CHECK) {
            scene_check(option_tag);
            scene_check(root_group);
    }
    if (miRENDER_SHADOWMAP && options->use_shadow_maps) {
            invalidate_local_images;
            build_shadow_maps;
    }
    if (miIMAGE_DELETE && !options->pixel_preview)
        delete_frame_buffers;

    if (miRENDER_ACCEL_DELETE) {
            delete_pm_cache;
            delete_fg_cache;
    }
    if (options->no_images > 0) {
            if (no frame buffers || !options->pixel_preview) {
                    create_frame_buffers;
                    invalidate_local_images;
            }
            if (miRENDER_DISPLAY)
                    if (imgpipe) init_display_pipe;
                    else         init_display_socket;

            if (miRENDER_LIGHTMAP)
                    build_light_maps;

            if (miRENDER_RENDER_PM || miRENDER_RENDER)
                build_photon_maps;

            if (miRENDER_RENDER_FG || miRENDER_RENDER)
                build_finalgather_maps;

            if (miRENDER_RENDER)
                    render;

            if (miRENDER_FB_SAVE)
                    copy frame_buffers to saved_frame_buffers;

            if (miRENDER_FB_RESTORE && !miRENDER_FB_SAVE)
                    copy saved_frame_buffers to frame_buffers;

            if (miRENDER_FB_DELETE && !miRENDER_FB_SAVE)
                    delete saved_frame_buffers;

            if (miRENDER_OUTPUTSH)
                    call_output_shaders;

            mi_img_invalidate_local_images;
            if (!options->pixel_preview && !miRENDER_IMAGE_DELETE)
                    delete_frame_buffers;
    }
    if (miRENDER_POSTPROC) {
            scene_postprocess;
            if (miRENDER_POSTPROC_FBC)
                    delete_box_caches;
    }

mi_rc_run_query

enum miRc_query {                   /* for mi_rc_run_query */
                                    /* after preprocessing: */
    miRCQ_NO_LIGHTS,                /* # of light leaf insts */
    miRCQ_NO_LEAF_INSTS,            /* # of object leaf insts */
    miRCQ_LIGHTS,                   /* list of light leaf insts */
    miRCQ_LEAF_INSTS,               /* list of object leaf insts */
    miRCQ_CAMERAS,                  /* list of camera leaf insts */
                                    /* after render w/o IMG_DEL: */
    miRCQ_FB,                       /* get frame buffer base */
    miRCQ_OPTIONS,                  /* render options tag */
    miRCQ_NEEDS_PREPROC,            /* needs scene preprocessing?*/
    miRCQ_DISP_NET_PORT,            /* port used by imf_disp */
    miRCQ_DISP_TALK_PORT,           /* port used by disp talk protocol */
    miRCQ_CUDA_DEVICES,             /* usable cuda device names */
    miRCQ_CUDA_DEVICES_N,           /* number of usable cuda devices*/
    miRCQ_IRAY_VERSION,             /* iray plugin version string */
    miRCQ_CUDA_DEVICE_PROPERTIES,   /* cuda device properties */
    miRCQ_CUDA_MEMORY_STATS         /* cuda mem stats for iray rendering */


miBoolean mi_rc_run_query(
    enum miRc_query mode,
    int             arg,
    void            *result);

This function picks up information after a previous mi_rc_run call. It is useful when fewer mode flags are used than miRENDER_DEFAULT to split the rendering operation, especially between pre-processing and post-processing, and between rendering and deleting the result images.

mi_rc_run_query accepts a mode that determines what to query, an argument that further describes which element to return, depending on the mode, and a result pointer that must point to a variable that the queried data is stored in. The function returns miTRUE if the query was valid and data was returned. Otherwise, it returns miFALSE. The following query modes are supported :

mode	arg	*result type	returned data
`miRCQ_NO_LIGHTS`	−	`int`	number of light leaf instances
`miRCQ_NO_LEAF_INSTS`	−	`int`	number of object leaf instances
`miRCQ_LIGHTS`	−	`miTag`	light leaf instances
`miRCQ_LEAF_INSTS`	−	`miTag`	object leaf instances
`miRCQ_CAMERAS`	−	`miTag`	camera leaf instances
`miRCQ_FB`	−	`miTag`	rendered frame buffers
`miRCQ_OPTIONS`	−	`miTag`	camera leaf instances
`miRCQ_NEEDS_PREPROC`	−	`int`	dynamic scene changes require pre-processing
`miRCQ_DISP_NET_PORT`	−	`int`	port to send disp data
`miRCQ_DISP_TALK_PORT`	−	`int`	port to receive disp commands
`miRCQ_CUDA_DEVICES`	−	`const char* const*`	array of CUDA device name strings
`miRCQ_CUDA_DEVICES_N`	−	`miUint`	number of CUDA devices
`miRCQ_IRAY_VERSION`	−	`const char*`	iray version string
`miRCQ_CUDA_DEVICE_PROPERTIES`	`int`	`miRc_cuda_device_properties`	specific CUDA device properties
`miRCQ_CUDA_MEMORY_STATS`	`int`	`miRc_cuda_memory_stats`	specific CUDA device memory info

miRCQ_NO_LIGHTS miRCQ_NO_LEAF_INSTS miRCQ_LIGHTS miRCQ_LEAF_INSTS miRCQ_CAMERAS

These queries return scene information after pre-processing. Therefore, they can be issued after calling mi_rc_run with the flag miRENDER_PREPROC. They remain valid until calling again with this flag, regardless of other flags.

miRCQ_FB

This query is valid after calling mi_rc_run to render an image but without setting the miRENDER_IMAGE_DELETE flag, which is normally on by default. A handle to the frame buffer structure is returned that allows to access the individual buffers. It is necessary to call mi_rc_run with miRENDER_IMAGE_DELETE before rendering the next frame to prevent the images from being leaked.

Example

miTag tag;

mi_rc_run(miRENDER_DEFAULT & ~miRENDER_IMAGE_DELETE, ...);

mi_rc_run_query(miRCQ_FB, 0, &tag);
if (tag) {
    miRcmap_fb* fb = (miRcmap_fb*) mi_db_access(tag);
    ... /* access individual frame buffer */
}
mi_rc_run(miRENDER_IMAGE_DELETE, ...);

Note, that in principle, this function returns valid values even during rendering, and may be called from abort or display callbacks. However, shadow mapping and other phases do not necessarily use identical camera, options, or images returned by mi_rc_run_query. Also note, that while rendering on a network of hosts, the images are incomplete and contain only tiles actually rendered on the local machine, occasionally none at all.

mi_rc_run_traversal_cb

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: root group .. curr inst */
    int               pathlen);     /* number of tags in path[] */

void mi_rc_run_traversal_cb(
    miTraversal_func  cb,           /* traversal function to call */
    void              *data)        /* this passed to traversal func */

This function allows to set a callback function that is used during traversal of the scene graph. It will be called once for each instance in the graph. The function may change the current instance inst based on the inherited information. If it returns false, the traversal of this branch of the scene DAG is terminated. A traversal function set with mi_rc_run_traversal_cb overrides the traversal function set in the options block (given that inh_is_traversal in the options is set to true).

Note, that the traversal function can also be set by passing the function pointer as inh_func to mi_rc_run and enable the inh_is_traversal flag in the options block.

mi_rc_set_taskorder

enum miRc_taskorder {
    miRC_TO_HILBERT = 0,
    miRC_TO_SPIRAL,
    miRC_TO_LEFT_RIGHT,
    miRC_TO_RIGHT_LEFT,
    miRC_TO_TOP_DOWN,
    miRC_TO_BOTTOM_UP
};

void mi_rc_set_taskorder(   /* call before mi_rc_run */
    enum miRc_taskorder o);

This function allows to change the task order visible as image tiles. It must be called before and between renderings started with mi_rc_run.